Home

Background

JSON Content Rules (JCR) is a language for specifying and testing the interchange of data in JSON format used by computer protocols and processes. The syntax of JCR is a superset of JSON possessing the conciseness and utility that has made JSON popular. It was created by the American Registry for Internet Numbers (ARIN) in an effort to better describe the JSON structures in protocols such as RDAP.

A First Example: Specifying Content

The following JSON data describes a JSON object with two members, "line-count" and "word-count", each containing an integer.

  { "line-count" : 3426, "word-count" : 27886 }

This is also JCR that describes a JSON object with a member named "line-count" that is an integer that is exactly 3426 and a member named "word-count" that is an integer that is exactly 27886.

For a protocol specification, it is probably more useful to specify that each member is any integer and not specific, exact integers:

  { "line-count" : integer, "word-count" : integer }

Since line counts and word counts should be either zero or a positive integer, the specification may be further narrowed:

  { "line-count" : 0.. , "word-count" : 0.. }

A Second Example: Testing Content

Building on the first example, this second example describes the same object but with the addition of another member, "file-name".

  {
    "file-name"  : "rfc7159.txt",
    "line-count" : 3426,
    "word-count" : 27886
  }

The following JCR describes objects like it.

  {
    "file-name"  : string,
    "line-count" : 0..,
    "word-count" : 0..
  }

For the purposes of writing a protocol specification, JCR may be broken down into named rules to reduce complexity and to enable re-use. The following example takes the JCR from above and rewrites the members as named rules.

  {
    $fn,
    $lc,
    $wc
  }

  $fn = "file-name"  : string
  $lc = "line-count" : 0..
  $wc = "word-count" : 0..

With each member specified as a named rule, software testers can override them locally for specific test cases. In the following example, the named rules are locally overridden for the test case where the file name is "rfc4627.txt".

  $fn = "file-name"  : "rfc4627.txt"
  $lc = "line-count" : 2102
  $wc = "word-count" : 16714

In this example, the protocol specification describes the JSON object in general and an implementation overrides the rules for testing specific cases.

More Information on JCR

More information on JCR can be found at json-content-rules.org. The current published specification is an IETF Internet Draft (I-D) versioned as -09, This software closely tracks the -09 version, which can be found here