Test the claim that the exported schema cannot drift

[VSN2015]

Tests and documentation only — no behaviour changes.

The untested claim

Because the schema is emitted from the same frozen data the server enforces, the docs cannot drift from the validation.

That's the gem's headline claim, and nothing tested it. Every existing spec checks one side: what the validator accepts, or what the exporter emits. None checked that the two agree.

The spec

spec/schema_conformance_spec.rb walks canonical JSON payloads through both a contract and its own exported schema and compares the verdicts — 53 examples across scalars and bounds, enums, exclusive and endless ranges, exact lengths, formats, arrays of scalars and of hashes, nested hashes under unknown: :error, rooted contracts, and a required string with no length: of its own.

spec/support/tiny_json_schema.rb is a deliberately small validator covering exactly the keywords the exporter emits and nothing else — a measuring instrument, not a dependency. One example asserts the exporter emits no keyword the validator silently ignores, so the two can't fall out of step as the exporter grows.

It was mutation-tested, not trusted for being green

Injected drift	Spec
drop maxItems from arrays	✅ fails
drop additionalProperties: false	✅ fails
drop the required-string minLength: 1	✅ fails
drop the root: required wrapper	✅ fails

The minLength mutation initially did not fail — a gap in my case table, not the design: that logic only bites on a required string with no length: of its own, and I had no such case. Adding one made the mutation fail as it should. Worth knowing that the table is the coverage, so extending it is how the guarantee grows.

What the sweep found

No drift in the code. It did find two places where the schema and the runtime legitimately differ that weren't written down anywhere:

• Non-canonical encodings — coercion accepts "30" for an :integer and 1 for a :string, because form and query payloads are all strings. (The exporter's comment already mentioned this one.)
• null as absence — the runtime reads {"age": null} as {}; JSON Schema cannot express that, so type: integer rejects a null the server would accept and ignore. This one was undocumented.

Both now appear in Permittable::JsonSchema's comment and in a new README subsection.

The direction is the point

Both divergences leave the schema stricter than the server, never looser — so a client validating against the published document is conservative, never surprised by a 422. The spec asserts that direction for every divergence it permits:

expect([runtime, documented]).to eq(%i[accept reject]),
  "#{expectation} is only allowed where the server accepts and the docs reject"

So a new divergence in the dangerous direction — docs promising something the server rejects — fails CI rather than shipping quietly.

Verification

• 252 examples, 0 failures
• RuboCop clean, 28 files
• The case table currently covers master's field surface; it's the natural place to extend once nullable: (Add nullable: so a contract can clear a column #13), :json (Add the :json field type for free-form hashes #15) and format: presets (Add format: presets, which export the JSON Schema format keyword #20) land — each adds schema keywords worth pinning the same way

[VSN2015]

Review of PR #27: Rigorous conformance testing. Validating emitted JSON Schemas against real runtime execution ensures contracts and exported documentation never drift.

[VSN2015]

TinyJsonSchema provides a lightweight, dependency-free validator covering exactly the emitted keywords, keeping the test suite standalone.

[VSN2015]

Bidirectional assertion checking (expect(documented).to eq(runtime)) effectively proves that client requests valid against the emitted schema will not fail server validation.