The Conformance Suite¶

kPointer ships a language-agnostic conformance suite in the conformance/ directory of the repository. Each fixture file is a JSON array of test cases. A conformance runner in any language can deserialize these fixtures and check its own implementation without reading a line of Kotlin.

The reference implementation dogfoods the suite: kpointer-core drives its own tests from the syntax/* fixtures and kpointer-adapter from the algorithm/* fixtures.

If you are writing a workalike in another language, these fixtures are your acceptance test. This page describes their structure; the workalike guide covers the Kotlin-specific idioms you will need to map.

Directory layout¶

conformance/
  syntax/
    parsing.json          # RFC 6901 parsing, fragment, dot-notation, auto-dispatch
    relative-apply.json   # Applying a relative pointer to an absolute pointer
    relative-compute.json # Computing the relative pointer between two absolute pointers
  algorithm/
    resolve.json          # Resolving an absolute pointer against a document
    mutate.json           # Applying set/remove mutations to a document

Normative versus advisory¶

Some expectation fields are normative — every conforming implementation must satisfy them. Others are advisory — they describe kPointer-specific behavior a port may omit if the concept does not apply.

Error kinds¶

Every { "type": "error", … } expectation may carry an errorKind — a language-neutral string naming why the operation failed. errorKind is normative output: a conforming implementation must fail with the named kind. How the failure materializes is unconstrained, such as a Kotlin exception hierarchy, a Rust Result/enum, or a TypeScript tagged error. When errorKind is absent or null, the fixture accepts any failure.

Absent versus error¶

Missing items are treated more gently than are trying to do the impossible:

• A resolution that simply does not find a value returns absent (null / undefined) — this covers both a missing struct key and an out-of-range list index. Throwing for either is a conformance failure.
• Only a structural fault is an error: navigating through a primitive, or addressing a list with a non-integer segment.

The element type system¶

Algorithm-layer fixtures represent document nodes as typed objects rather than raw JSON, because raw JSON cannot distinguish 42 (integer) from 42.0 (float), nor null-vs-absent. Every element carries a "type" discriminator:

The explicit long-vs-double split lets single-numeric-type languages (JavaScript, AssemblyScript) preserve and test the semantic distinction.

Two elements match when their types agree, primitive values are equal, struct keys map pairwise with no extras, and lists are equal in length and elementwise.

Coverage matrix — RFC 6901 edge cases¶

A conformance suite is only as good as the edges it names. The table below maps the classic RFC 6901 edge cases to the fixture names that exercise them, so that a missing row is visibly a missing fixture.

All edge cases are covered by fixtures.

Writing a runner¶

A minimal runner, per fixture category:

1. Deserialize the fixture JSON into typed objects using the fixture schemas.
2. Build the input (parse the pointer string, build the document from the typed elements, …).
3. Execute the operation under test.
4. Compare against the expect field; report pass/fail using the fixture name as the test-case id.

The name field is a stable, kebab-case identifier suitable as a test name in any framework.

Next: Writing a Workalike covers the Kotlin idioms you will meet in the reference and how to map them into your target language.