Network Working Group P. Cordell
Internet-Draft Codalogic
Intended status: Standards Track A. Newton
Expires: September 22, 2016 ARIN
March 21, 2016
Co-Constraints for JSON Content Rules
draft-cordell-jcr-co-constraints-00
Abstract
JSON Content Rules (JCR) [JCR] provides a powerful, intuitive and
concise method for defining the structure of JSON [RFC7159] messages.
However, modern JSON usage patterns occasionally mean that JCR alone
is not able to capture the required constraints in a satisfactory
way. This document describes JCR Co-Constraints (JCRCC) which
defines additional JCR directives and annotations that can be added
to a JCR ruleset in order to define more detailed constraints on JSON
messages.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on September 22, 2016.
Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
Cordell & Newton Expires September 22, 2016 [Page 1]
Internet-Draft JCR Co-Constraints March 2016
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
1. Introduction
JSON Content Rules [JCR] provides a powerful, intuitive and concise
method for defining the structure of JSON [RFC7159] messages. In
addition to describing the overall structure of JSON messages, JCR
aims to capture the constraints that are imposed on individual items
within a message. However, modern JSON usage occasionally requires
constraints that can't be expressed by JCR alone. JCR Co-Constraints
(JCRCC) defines additional JCR directives and annotations that can be
added to a JCR ruleset in order to define more detailed constraints
on items within a JSON message, and also supports specifying
constraints that depend on the relationship of multiple JSON items.
JCRCC constraints represent an additional layer of validation on top
of the validation provided by JCR alone. JCRCC constraints may
indicate that a JSON instance that was determined to be valid by the
rules of a JCR ruleset is in fact invalid. However, if the JCR
ruleset indicates that the JSON instance is invalid, JCRCC
constraints can not override that and declare the instance to be
valid. A JCR processor MAY ignore the JCRCC annotations and
directives, perhaps only issuing a warning for encountering an
unknown annotation or directive.
JCRCC uses the annotations @{id}, @{when} and @{assert} along with
the directive #{constraint}. The @{id} annotation is used to
identify an item in a JSON message that contributes to the assessment
of a JSON instance's validity. The other three each include a
'condition' expression that yields a Boolean true or false result.
The validity of the JSON instance is dependent on the results of the
various condition expressions. Condition expressions are made up of
identifiers, comparators, combiners and functions. Each of these
aspects is described in more detail below.
2. Definitions
Assessment -
The process whereby it is determined whether a JSON instance is
valid according to a JCR ruleset (which may or may not include
JCR co-constraints).
JSON instance -
A JSON message that is being validated against a JCR ruleset
(which may augmented using JCRCC).
Cordell & Newton Expires September 22, 2016 [Page 2]
Internet-Draft JCR Co-Constraints March 2016
JSON instance item -
An object member or a value in a JSON instance. Often JCRCC
annotations will define an identifier that will be associated
with a JSON instance item.
3. Annotations and Directives
JCRCC uses the annotations @{id}, @{when} and @{assert} plus the
directive #{constraint}.
3.1. The @{id} Annotation
The @{id} annotation creates an identifier for a rule in a JCR
ruleset. A maximum of one @{id} annotation is permitted per rule.
It has the form:
@{id name}
where 'name' corresponds to the 'name' production in the JCR ABNF.
The @{id} annotation associates an identifier with the rule on which
it is placed. The identifier can then be used in condition
expressions to reference the corresponding item in JSON instance
items that are mapped to the JCR rule during validation.
For example, a JCR rule of:
"type" @{id t} : string
might associate the identifier 't' with a JSON instance item such as:
"type" : "shutdown"
3.2. The @{when} Annotation
The @{when} annotation has two similar roles. If a JCR rule
indicates that a JSON instance item is optional, then it can be used
to describe the conditions when the item is present or absent.
Similarly, if a JCR rule indicates that an item has a choice of
types, then the @{when} annotation can be used to indicate which of
the possible sub-rules is applicable in the current validation
instance. Only one @{when} annotation per rule is permitted.
The @{when} annotation includes a single 'condition'. In the case of
using the @{when} annotation with an optional instance, if the
condition yields a 'true' result, then the JSON instance item
associated with the JCR rule MUST be present, otherwise it MUST be
absent.
Cordell & Newton Expires September 22, 2016 [Page 3]
Internet-Draft JCR Co-Constraints March 2016
When the @{when} annotation is used to select the applicable member/
type rule within a group or type choice, the condition of each
@{when} annotation is evaluated in turn (from left to right as shown
in the JCR rule) and the member/type rule that corresponds to the
first @{when} condition that yields a 'true' result is selected. If
none of the @{when} annotations on a group or type choice yields
true, this indicates an invalid instance. When a member/type rule
within a group or type choice that has @{when} annotations on other
members/types, but does not itself have an @{when} annotation, this
indicates the default case. In essence, if a rule contains @{when}
annotations, then an absent @{when} annotation on a member/type rule
is equivalent to @{when true}.
As an example, a @{when} annotation on an optional item may look as
follows:
? @{when $t == "shutdown"} "uptime" : integer
This indicates that the "uptime" member should be present if the JSON
instance item associated with a JCR rule with an @{id t} annotation
has the value "shutdown".
A @{when} annotation on a group may look as follows:
details ( @{when $t == "boot"} boot-details |
@{when $t == "shutdown"} shutdown-details |
default-details )
This indicates that the JCR rule named 'boot-details' is applicable
when the JSON instance item associated with an @{id t} annotation has
the value "boot", the rule 'shutdown-details' is applicable when the
value of the $t item is "shutdown", otherwise the rule 'default-
details' is applicable. (The rules identified by 'boot-details',
'shutdown-details' and 'default-details' might be groups that act as
mixins for the rule in which the 'details' rule is used.)
The @{when} annotation can reference identifiers in siblings,
ancestors, and descendants. To avoid circular or ambiguous
dependencies, the identifiers in descendants must not be part of
arrays or descendants of itself or descendants of siblings that have
@{when} annotations. The latter restriction avoids needing to know
whether a secondary @{when} annotation yields 'true' in order to
determine if the @{when} annotation being assessed yields 'true'.
When seeking identifiers, siblings are inspected first, followed by
the nearest ancestor, followed by the nearest descendent. If it is
desired to look for an identifier that is a descendent without first
looking for an identifier that is an ancestor, then the
Cordell & Newton Expires September 22, 2016 [Page 4]
Internet-Draft JCR Co-Constraints March 2016
'descendent()' method can be called on the name of the identifier.
For example:
? @{when descendent($s) == "on"} "watts" : integer
3.3. The @{assert} Annotation
The @{assert} annotation is used to specify additional constraints on
an item that can't be expressed using JCR alone. The @{assert}
annotation contains a single condition that must yield 'true' for the
JSON instance item to be considered valid. A maximum of one
@{assert} annotations is permitted per rule.
@{assert} annotations are evaluated after all sibling @{when}
annotations have been evaluated, and constraints specified by the
underlying JCR rule have been assessed. An item may have both a
@{when} annotation and a @{assert} annotation. If the condition in
the @{when} annotation yields 'false', then the item it corresponds
to should be absent in the JSON instance, so the @{assert} condition
is not evaluated. If the JSON instance item is not valid according
the underlying JCR rule, then validation fails at that point and the
@{assert} annotation is not assessed.
When seeking identifiers referenced in an @{assert} annotation,
siblings are inspected first, followed by the nearest ancestor,
followed by the nearest descendent. If it is desired to look for an
identifier that is a descendent without first looking for an
identifier that is an ancestor, then the 'descendent()' method can be
called on the name of the identifier.
An example @{assert} annotation might be:
"index" @{assert $ % 2 == 0} : integer ; Must be even
3.4. The #{constraint} Directive
The #{constraint} directive offers a way to express conditions
external to @{when} and @{assert} annotations. #{constraint}
directives can be viewed as a macro substitution mechanism. @{when}
and @{assert} annotations, and other #{constraint} directives can
reference conditions defined by a #{constraint}. The format of a
#{constraint} directive is as follows:
#{constraint name condition}
where 'name' corresponds to the 'name' production in the JCR ABNF,
and the 'condition' is the same as used in @{when} and @{assert}
annotations and is as described below.
Cordell & Newton Expires September 22, 2016 [Page 5]
Internet-Draft JCR Co-Constraints March 2016
Conceptually at least, the 'condition' in a #{constraint} directive
is substituted into @{when}, @{assert} annotations and other
#{constraint} directives wherever the constraint's 'name' is
referenced. (In practice, for the purposes of efficiency, the result
of a #{constraint} directive may be cached or memoized, to avoid
repeated computation of the sub-condition. However, such
optimizations are beyond the scope of this document.)
An example usage, equating to the earlier example, might be:
#{constraint is_even $ % 2 == 0}
"index" @{assert @is_even} : integer ; Must be even
4. Conditions
The @{when} annotation, @{assert} annotation and #{constraint}
directive contain 'conditions'. These are made up of 'identifiers',
'comparators', 'combiners' and 'functions' as described below.
4.1. Identifiers
Identifiers are used to refer to items in the JCR, and #{constraint}
directives. They have a few different forms.
'$' on its own refers to the member / type expressed by the current
JCR rule. For example:
int-pairs @{assert count( $ ) % 2 == 0} [ : integer ]
The form '$name' and '$alias.name' form is an item reference and
refers to members and types identified by JCR rules by @{id}
annotations. An 'alias' is set up using the normal JCR #import
directive and allows members / types outside the current ruleset to
be identified. For example:
@{id type} : string, {
? "uptime" @{when $type == "shutdown"} : integer }
An item reference that is not part of an 'operator' or a 'comparator'
sub-expression yields 'true' if the referenced item is present in the
JSON instance being validated, and 'false' if not. For example, the
following says that the 'dob' member must be present if the 'name'
member is present:
? "name" @{id n} : string,
? "dob" @{when $n} : full-date
Cordell & Newton Expires September 22, 2016 [Page 6]
Internet-Draft JCR Co-Constraints March 2016
An item reference that is part of an 'operator' or a 'comparator'
sub-expression yields the value of the corresponding JSON instance
item.
Item references may also be used as arguments to functions.
The '@name' and '@alias.name' form is a constraint reference and
refers to a condition expressed in a #{constraint} directive. An
'alias' is set up using the normal JCR #import directive and allows
constraints outside the current ruleset to be identified. For
example:
#{constraint is_even $ % 2 == 0}
"index" : @{assert @is_even} integer ; Must be even
4.2. Operators
The values of JSON instance items identified by identifiers, values
yielded by other 'operators' and values returned by 'functions' can
be subject to computations using 'operators'. The supported
operators are '+', '-', '*', '/' and '%'. They have their usual
C-family programming language meaning. The precedence of the
operators is as-per normal mathematics rules. Operators have higher
precedence than comparators.
4.3. Comparators
The values of JSON instance items identified by identifiers, values
yielded by 'operators' and values returned by 'functions' can be
compared using 'comparators'. The comparators are the usual '<',
'<=', '==', '!=', '>=' and '>', and have their usual C-family
language meaning. Comparators yield a 'true' or 'false' result.
When an identifier referenced by a comparator is absent, then the
comparison returns 'false'. For example:
$t == "boot"
is equivalent to:
( $t && $t == "boot" )
Similarly:
$t == "boot" || $other == "close"
is equivalent to:
Cordell & Newton Expires September 22, 2016 [Page 7]
Internet-Draft JCR Co-Constraints March 2016
( $t && $t == "boot" ) || ( $other && $other == "close" )
And:
length( $first ) > length( $second )
is equivalent to:
( $first && $second && length( $first ) > length( $second ) )
Comparators have higher precedence than combiners.
4.4. Combiners
Multiple results of 'comparators' or standalone identifiers can be
combined using 'combiners'. The supported combiners are '&&' and
'||'. They have their usual C-family programming language meaning.
4.5. Functions
JCRCC supports a number of functions that can be used to yield
specific information about a JSON instance item referenced by an
identifier. Some functions can operate on multiple types of
argument, such as identifiers or strings. In the function
descriptions below, arguments that can take multiple different types
have each type listed, separated by the pipe symbol (|). For
example, an argument description of "identifier | string" indicates
that the function can take an identifier or a string as an argument.
The functions are as follows:
name( identifier ) -
Returns the member name of the JSON instance item associated
with the identifier as a string.
length( identifier | string ) -
If the argument is an identifier, the value of the JSON
instance item associated with it MUST be represented using a
JSON string (i.e. it could be defined as a JCR ip4 type that is
represented in JSON using the string format). The function
returns the length of the string in Unicode code points. To
return the length of a JSON instance item's member name, do
"length( name( $t ) )".
count( identifier ) -
The JSON instance item associated with the identifier MUST be
an array. The function returns the number of items in the
array.
Cordell & Newton Expires September 22, 2016 [Page 8]
Internet-Draft JCR Co-Constraints March 2016
capture( identifier | string, regex ) -
The regex in the capture function MUST include a capture
expression (i.e. a suitable term in brackets). The regex is
applied to the input string, or the string value of the JSON
instance item associated with the identifier, and the sub-
string captured by the regex capture expression is returned.
descendent( identifier ) -
The normal order of identifier look up is, siblings, followed
by ancestors, followed by descendents. This function will
cause the lookup to be in the order siblings followed by
descendents. It returns a reference to a JSON instance item
that can be used in place of an identifier. For example,
"length( name( descendent( $t ) ) )".
error( q_string ) -
This function can be used for reporting error messages. The
text in the q_string may be subject to value interpolation and
internationalization by an implementation, but this is not
required. It always returns false. For example: @{assert
$%2==0 || error("value must be even")} :integer
is_null( identifier ), is_boolean( identifier ), is_string(
identifier ), is_float( identifier ), is_integer( identifier ),
is_ip4( identifier ), is_ip6( identifier ), is_fqdn( identifier ),
is_idn( identifier ), is_uri( identifier ), is_phone( identifier ),
is_email( identifier ), is_full-date( identifier ), is_full-time(
identifier ), is_date-time( identifier ), is_base64( identifier ) -
This set of functions return true if the JSON instance item
associated with the identifier has the corresponding type, and
false otherwise.
4.6. If-Then-Else
5. ABNF
The ABNF is 'work in progress'. It currently looks as below. This
does not capture where spaces are permitted.
Cordell & Newton Expires September 22, 2016 [Page 9]
Internet-Draft JCR Co-Constraints March 2016
condition = relational ( * ( "&&" relational ) /
* ( "||" relational ) )
relational = ["!"] value / value comparator value /
["!"] condition-group / ternary
value = identifier / constant / function / "@" [ alias "." ] name
identifier = "$" / "$" [ alias "." ] name
constant = "null" / "true" / "false" / integer / float /
q_string / regex
comparator = "==" / "!=" / "<" / "<=" / ">=" / ">"
condition-group = "(" condition ")"
ternary = "if" "(" condition ")" "then" "(" condition ")"
"else" "(" condition ")"
function = "name" "(" identifier ")" /
"length" "(" identifier ")" /
"count" "(" identifier ")" /
"capture" "(" regex "," identifier ")" /
"descendent" "(" identifier ")" /
"error" "(" q_string ")" /
"is_integer" "(" identifier ")" /
"is_float" "(" identifier ")" /
etc...
6. References
6.1. Normative References
[JCR] Newton, A. and P. Cordell, "A Language for Rules
Describing JSON Content", October 2015,
<https://www.ietf.org/id/draft-newton-json-content-rules-
05.txt>.
[RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March
2014, <http://www.rfc-editor.org/info/rfc7159>.
6.2. Infomative References
Cordell & Newton Expires September 22, 2016 [Page 10]
Internet-Draft JCR Co-Constraints March 2016
[ARIN_JCR_VALIDATOR]
American Registry for Internet Numbers, "JSON Content
Rules Validator (Work In Progress)",
<https://github.com/arineng/jcrvalidator>.
[CODALOGIC_JCR_VALIDATOR]
Codalogic, "cl-jcr-parser (Work In Progress)",
<https://github.com/codalogic/cl-jcr-parser>.
Appendix A. JCR Implementations
The following implementations, [ARIN_JCR_VALIDATOR] and
[CODALOGIC_JCR_VALIDATOR] have influenced the development of this
document.
Authors' Addresses
Pete Cordell
Codalogic
PO Box 30
Ipswitch IP5 2WY
UK
Email: pete.cordell@codalogic.com
URI: http://www.codalogic.com
Andrew Lee Newton
American Registry for Internet Numbers
3635 Concorde Parkway
Chantilly, VA 20151
US
Email: andy@arin.net
URI: http://www.arin.net
Cordell & Newton Expires September 22, 2016 [Page 11]