Skip to content

Fixture Schemas

This page is the authoritative reference for the shape of each fixture file in the conformance suite. Read it alongside the JSON files in conformance/ when writing a runner or adding new fixtures.

syntax/parsing.json

Tests that a pointer string is parsed (or rejected) correctly.

{
  "name": "unique-kebab-case-id",        // required
  "description": "Human-readable note.", // optional
  "input": "<pointer string>",           // required
  "encoding": "<encoding>",              // required; see below
  "expect": { … }                        // required; see below
}

encoding values

Value Meaning
"rfc6901" Strict RFC 6901: empty string or a string starting with /
"fragment" RFC 6901 §6 URI fragment: must start with #; path portion is percent-decoded
"dotNotation" Dot-notation: segments separated by .; bare . (or all dots) is root
"auto" Auto-dispatch: / prefix → RFC 6901; # prefix → fragment; anything else → dot-notation

expect shapes

// Parsing succeeded
{ "type": "success",
  "rfc6901": "",      // normative — canonical RFC 6901 string
  "fragment": "#",    // normative — URI fragment string
  "dotNotation": ".", // advisory — omit check if unsupported; null = skip
  "depth": 0,         // normative — number of segments
  "isRoot": true }    // normative — equivalent to depth == 0

// Parsing must fail
{ "type": "error" }

syntax/relative-apply.json

Tests that a relative pointer string applied to an absolute base pointer produces the correct result.

{
  "name": "unique-kebab-case-id",
  "description": "Human-readable note.",
  "base": "/a/b",     // required — absolute pointer in RFC 6901 form
  "relative": "1/c",  // required — relative pointer string
  "expect": { … }     // required; see below
}

expect shapes

// Navigated to an absolute pointer
{ "type": "pointer", "rfc6901": "/a/c" }  // normative

// '#' query — resolved segment is a non-negative integer
{ "type": "index", "index": 2 }           // normative

// '#' query — resolved segment is a string key
{ "type": "key", "key": "b" }             // normative

// Application must fail
{ "type": "error" }

syntax/relative-compute.json

Tests that the relative pointer string from one absolute pointer to another is computed correctly.

{
  "name": "unique-kebab-case-id",
  "description": "Human-readable note.",
  "from": "/a/b",           // required — starting absolute pointer in RFC 6901 form
  "to": "/a/c",             // required — target absolute pointer in RFC 6901 form
  "expectedRelative": "1/c" // required — normative
}

expectedRelative is the minimal "go-up-N, then descend" form. Index adjustments (+N/-N) are never used in computed results; the result never ends with #.

algorithm/resolve.json

Tests that an absolute pointer resolves correctly against a document.

{
  "name": "unique-kebab-case-id",
  "description": "Human-readable note.",
  "document": { … },  // required — root element (see element type system)
  "pointer": "/foo",  // required — absolute pointer in RFC 6901 form
  "expect": { … }     // required; see below
}

expect shapes

// Pointer resolved to an element
{ "type": "element", "element": { … } }  // normative

// Pointer targeted a key/index that does not exist
{ "type": "absent" }                      // normative

// Resolution must fail
{ "type": "error" }

The distinction between absent and error is normative — see Absent versus error.

algorithm/mutate.json

Tests that a sequence of mutations is applied correctly to a document.

{
  "name": "unique-kebab-case-id",
  "description": "Human-readable note.",
  "document": { … },   // required — root element (see element type system)
  "mutations": [ … ],  // required — ordered list of mutation objects; see below
  "expect": { … }      // required; see below
}

Mutation objects

// Set (create or replace) a value
{ "type": "set", "pointer": "/x", "value": { … } }  // value is a typed element

// Remove a key or list element
{ "type": "remove", "pointer": "/x" }

Mutations are applied in order. Each operates on the document produced by the previous one.

expect shapes

// All mutations succeeded; this is the final document
{ "type": "document", "document": { … } }  // normative

// One or more mutations must fail
{ "type": "error" }

Relative pointer grammar

The relative pointer string format follows draft-bhutton-relative-json-pointer-00.

relative-pointer     = non-negative-integer
                       [ index-adjustment ]
                       ( "" / "#" / "/" json-pointer-path )

non-negative-integer = "0"
                     / ( DIGIT1 *DIGIT )       ; no leading zeros

index-adjustment     = ( "+" / "-" ) non-negative-integer

json-pointer-path    = *( "/" reference-token ) ; RFC 6901 §3

Rules: - A non-negative integer with leading zeros (e.g. "01") is rejected. - Only ASCII digits 0–9 are accepted; Unicode digit characters are rejected. - # terminates the string; no characters may follow it. - An index adjustment (+N or -N) modifies the last segment after ascending, treating it as an array index. It is an error if that segment is not a non-negative integer string, or if the adjusted value is negative. - # after an index adjustment (e.g. "0+1#") is valid. - The suffix after / is a standard RFC 6901 pointer path; tilde-escaping applies.

Dot-notation rules (advisory)

Dot-notation is a kPointer extension, not defined in any RFC. Implementations that do not support it should skip dotNotation expectation fields in syntax/parsing fixtures.

  • . (a bare dot, or any string composed entirely of dots) → root pointer.
  • "foo" → one segment ["foo"].
  • "foo.bar" → two segments ["foo", "bar"].
  • A leading . is stripped: ".foo" → ["foo"] (same as "foo").
  • Empty segments — trailing dot ("foo."), consecutive dots ("foo..bar") — are rejected.
  • Segments may not contain a literal . character; there is no escape mechanism for it.