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. For the full list of errorCode values used in { "type": "error" }
expectations, see the Error Codes page.
syntax/parsing.json¶
Tests that a pointer string is parsed (or rejected) correctly.
{
"version": "0.1.0", // suite format version
"cases": [
{
"name": "unique-kebab-case-id", // required
"description": "Human-readable note.", // optional
"requiresCapability": "jsPath", // optional — see Capabilities; absent = always run
"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 |
"jsPath" |
JavaScript access path: dot, ['…']/["…"], and [N] segments, with backslash escaping; empty string is root |
"auto" |
Auto-dispatch: / prefix → RFC 6901; # prefix → fragment; anything else → jsPath |
expect shapes¶
// Parsing succeeded
{ "type": "success",
"rfc6901": "", // normative — canonical RFC 6901 string
"fragment": "#", // normative — URI fragment string
"jsPath": "", // advisory — requires the jsPath capability; absent = skip
"depth": 0, // normative — number of segments
"isRoot": true } // normative — equivalent to depth == 0
// Parsing must fail; errorCode is optional — see Error Codes page
{ "type": "error", "errorCode": "KP-1001" } // normative when present
syntax/js-access-path.json¶
A dedicated, deeper corpus for the JavaScript access path notation — same shape as
syntax/parsing.json's cases, but encoding/requiresCapability are always "jsPath". Sampled
from the vega-util splitAccessPath oracle vectors and representative real-world Vega-Lite
field-accessor strings; see JavaScript access path rules
below.
{
"version": "0.2.0",
"cases": [
{
"name": "unique-kebab-case-id", // required
"description": "Human-readable note, often citing a source URL.", // optional
"requiresCapability": "jsPath", // always present
"input": "<jsPath string>", // required
"encoding": "jsPath", // always present
"expect": { … } // required; same shape as syntax/parsing.json
}
]
}
syntax/relative-apply.json¶
Tests that a relative pointer string applied to an absolute base pointer produces the correct result.
{
"version": "0.1.0",
"cases": [
{
"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; errorCode is optional — see Error Codes page
{ "type": "error", "errorCode": "KP-2001" } // normative when present
syntax/relative-compute.json¶
Tests that the relative pointer string from one absolute pointer to another is computed correctly.
{
"version": "0.1.0",
"cases": [
{
"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.
{
"version": "0.1.0",
"cases": [
{
"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; errorCode is optional — see Error Codes page
{ "type": "error", "errorCode": "KP-3001" } // normative when present
The distinction between absent and error is normative — see
Absent versus error.
Double matching uses total ordering
double element values must be compared with a total-order comparison, not the language's
default ==. In particular, -0.0 and 0.0 are distinct expected values, and NaN
equals NaN. Use Double.compare (Kotlin/Java), f64::total_cmp (Rust), or an equivalent
bit-pattern comparison in other languages.
algorithm/mutate.json¶
Tests that a sequence of mutations is applied correctly to a document.
{
"version": "0.1.0",
"cases": [
{
"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; errorCode is optional — see Error Codes page
{ "type": "error", "errorCode": "KP-4001" } // normative when present
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.
JavaScript access path rules (advisory)¶
The JavaScript access path is a kPointer extension, not defined in any RFC — the static
member-access subset of JavaScript used by tools like Vega-Lite's encoding.*.field accessors.
Runners that do not support it should declare the jsPath capability absent; the dispatch layer
then skips jsPath cases and suppresses the jsPath output field check automatically. See
Capabilities.
""(empty input) → root pointer."foo"→ one segment["foo"]."foo.bar"→ two segments["foo", "bar"]."foo[0]"→ two segments["foo", "0"]— the bracket is structural, not a literal key."foo['bar']"/"foo[\"bar\"]"→ a quoted-bracket segment holds any literal string, including one containing.,[, or].- Backslash escaping inside a dot segment:
\.,\[,\]produce a literal.,[,]in the current segment (e.g."a\\.b"→ one segment["a.b"]). - Empty segments — a leading
.(".foo"), trailing dot ("foo."), consecutive dots ("foo..bar") — are rejected. - Malformed brackets/quotes — unterminated bracket (
"foo[0"), unterminated quote ("foo['bar"), empty bracket ("foo[]"), a dangling backslash ("foo\\"), or junk after a closing quote ("foo['a'x") — are rejected, all witherrorCode"KP-1004".