Export numeric bounds as JSON numbers and label every looser divergence

[VSN2015]

A bug fix in the JSON Schema exporter. One bug made the exported document invalid. The others were places where the docs accept what the server rejects, without saying so. No runtime behaviour changes. Updated after review: see the last two sections.

The bugs

1. A decimal range bound came out as strings, which makes the schema invalid. Range bounds went through json_value, the re-encoding used for an authored default:/example:. That method renders a BigDecimal as its precision-safe string. The natural way to bound a price therefore published:

optional :price, :decimal, in: BigDecimal("0.01")..BigDecimal("999.99")

{ "type": ["string", "number"], "format": "decimal", "minimum": "0.01", "maximum": "999.99" }

The metaschema requires minimum/maximum to be numbers, so the whole document failed validation.

2. A bounded :decimal sent as a string skipped its bounds, and this was not labelled. :decimal is typed ["string", "number"], but minimum/maximum only apply to numbers. So "5000" passed the docs, and the server answered inclusion.

3. normalize: was not in the export. With required :name, :string, length: 3..10, normalize: :squish:

  payload             docs (minLength 3)   server
  "   "               accept               missing   (squishes to "", which counts as absent)
  " a  "              accept               length    (squishes to "a")
  "  abcdefghij  "    reject (14 > 10)     accept    (squishes to 10 chars)

The fix

• Bounds are JSON numbers. A whole-number bound is emitted as an Integer, anything else as a Float. Exclusive and endless ranges work as before.
• An infinite bound is omitted. Float::INFINITY and BigDecimal("Infinity") mean "no bound", so no key is emitted. The same goes for NaN, which compares to nothing. Neither is a JSON number.
• normalize: is exported as x-permittable-normalize. The value is the preset's name ("squish", "email", …), which a client can apply itself, or true for a custom proc. The contract stores only the resolved lambda, so the exporter gets the name back with NORMALIZERS.key(callable), a lookup by identity. Contract data is unchanged.
• Every looser divergence is now documented: in the README's "What the schema deliberately does not say", in the JsonSchema header comment, and in spec/schema_conformance_spec.rb. The README now lists three safe cases and six looser ones.

The decision I'd most like reviewed: rounding a bound that a double cannot hold

to_f rounds to the nearest double, which can land on the wrong side of the bound. For example, BigDecimal("0.1000000000000000001").to_f is 0.1. A client that sends 0.1 passes minimum: 0.1 and the server then refuses it.

How far is "wrong" depends on the field's type:

• a :decimal field reads the number back as BigDecimal("0.1") and compares exactly;
• a :float field compares the Float through BigDecimal#<=>, which reads the Float at limited precision. So a :float field needs a few doubles more.

So the exporter doesn't model either comparison. It asks the server. It takes the most extreme value the published keyword admits:

• the bound itself for minimum/maximum;
• the value just below the bound for exclusiveMaximum;
• on an :integer field, the ceiling or floor.

While that value would fail the field's own cast and comparison, the bound moves one double inward (a minimum up, a maximum down). The published range is then only ever narrower than the enforced one, on every numeric type, and the loop stops at the first double the server accepts. (Bounds are exact as published; a client that reads the document back with ordinary double-precision floats, rather than the digits as sent, can still round a value across a boundary — that's inherent to parsing any JSON number as a double, not something the exporter controls.)

Details:

• Only the relevant side of the range is asked. A range narrower than the gap between two doubles admits no double at all, so checking both ends would never settle.
• The bound never moves outward. Where a lossy comparison would also accept a few doubles beyond the nearest one, those stay unpublished (stricter, the safe way).
• A decimal of up to 15 significant digits round-trips through a double, so every price is emitted as written: 999.99, not 999.9899999999999.
• An INTEGRAL bound is published exactly at any magnitude (10**400 included — a JSON integer has no size limit), so it never goes through this nudge at all. A genuinely FRACTIONAL bound beyond Float::MAX has no such escape and is omitted, same as an infinite bound — see the "Round 2" section below for why this needed a separate fix.

The conformance spec

The looser labels live in a LOOSER table. Each label names the keyword the diverging field's own schema must carry. The spec checks both the direction (server rejects, docs accept) and that the keyword is on that field, not anywhere in the document:

Label	Server rejects, docs accept	Field must carry
:extension_only	an over-nested :json value	x-permittable-max-depth
:range_extension	"zebra" for in: "a".."m"	x-permittable-range
:custom_validation	a value a validate: proc refuses	x-permittable-custom-validation
:normalized_first	" ", " a " under squish	x-permittable-normalize
:format_annotation	"abc" / "NaN" (:decimal), "2026-02-30" (:date), "not a time" (:datetime)	format
:string_decimal	"5000" against ..999.99	maximum (as a number)

The padded case (" abcdefghij ") goes the safe way and has its own label, :normalized_encoding.

CASES and LOOSER are now constants of a SchemaConformance module, instead of top-level constants defined inside RSpec.describe.

I mutation-checked the per-field lookup: pointing :custom_validation at x-permittable-range fails the spec. The old anywhere-in-the-document check would have passed, because a sibling field in the same case carries that extension.

TinyJsonSchema needed no change, and the "exporter emits no keyword the validator silently ignores" example still passes.

Also

• The golden fixture is unchanged.
• I did not touch the pattern code (UNTRANSLATABLE, apply_pattern!, ecma_pattern). In scalar_schema only the apply_in! call changed, because it now passes the field type.
• An untranslatable format: regexp (x-permittable-pattern) is not one of the six LOOSER cases the spec asserts — #66, reworking Ruby → ECMA-262 pattern translation, owns adding that case. The README and CHANGELOG now say so plainly instead of listing it alongside the six.

Review follow-up

1. Infinite bounds. BigDecimal("Infinity") crashed the export (to_i raised FloatDomainError), and Float::INFINITY was emitted as Infinity. Both are now omitted, and so is NaN. Specs: treats an infinite bound as no bound at all, omits a NaN bound.
2. The nudge on :float fields. The nudge is now checked against the field's own cast and comparison, as described above. Specs cover both :decimal and :float: the published minimum and maximum are accepted, and the minimum is no further inward than it needs to be.
3. Missing looser cases. Strings whose validity is only a format (:decimal, :date, :datetime), validate: procs, and non-numeric ranges are now labelled and direction-checked.
4. Release notes. The Unreleased "Added" bullet now points to the full looser list under Fixed. The README's safe list counts three cases, including :normalized_encoding.
5. The keyword check now looks at the diverging field's own schema.
6. The spec tables moved into the SchemaConformance module.

master was merged in first, with master's CHANGELOG entries kept ahead of this PR's.

Round 2: final regression-pass fixes

A last regression pass compared every export against master's and found one real regression plus three documentation-accuracy issues. All fixed:

1. A bound beyond Float's range was dropped entirely, where master published it validly. optional :x, :float, in: (10**400..) used to export no minimum at all — the inward-nudge loop asks the field's own cast whether the bound is "honoured" by routing it through to_f, which overflows a value this large to Infinity, walks the bound to Infinity, and drops it. Master published minimum: 10**400 outright. Fixed: json_bound now returns an integral bound exactly, before the nudge loop runs, whenever to_f would overflow it — a JSON integer has no size limit, so this needs no Float conversion and none of the machinery that exists only to protect a fractional bound from double-rounding. A genuinely fractional bound past Float::MAX (e.g. BigDecimal("1e400") + BigDecimal("0.5")) has no arbitrary-precision JSON fallback and stays omitted — now a documented, deliberate choice rather than a silent one. New specs: publishes an integral bound beyond Float::MAX exactly, matching master and omits a FRACTIONAL bound beyond Float::MAX, unlike an integral one.
2. The exclusiveMaximum/JSON-rounding concern isn't an exporter bug. A published bound rounding across its boundary when a client parses it with an ordinary double is inherent to IEEE754 parsing, not something the exporter can fix from the document side. The CHANGELOG and README now say so explicitly next to the "narrower than enforced" claim, rather than leaving it as an unqualified guarantee.
3. The CHANGELOG/README looser-divergence counts didn't match what the spec asserts. LOOSER has six keys; the README's "Six cases go the other way" header was accurate, but its bullet list bundled :custom_validation, :range_extension and the untranslatable format: regexp into one bullet — five bullets naming seven rules, one of which (the regexp case) has no conformance case at all. Split into six one-to-one bullets, and the regexp case is now called out separately as not asserted by this spec, owned by Translate format: regexps into patterns valid under Ajv's u flag #66. Same fix applied to the parallel CHANGELOG bullet.
4. Removed a stale CHANGELOG line. "No behaviour changes: this release adds tests and documentation only" sat mid-Unreleased even though Unreleased contains substantial behaviour changes (this PR's own export changes among them). Deleted.

Verification

• 2 new examples this round in json_schema_spec.rb (publishes an integral bound beyond Float::MAX exactly, matching master, omits a FRACTIONAL bound beyond Float::MAX, unlike an integral one), on top of the 30 from the original round (5 in json_schema_spec.rb, 25 conformance payloads). 673 examples in total, 0 failures.
• RuboCop clean.

🤖 Generated with Claude Code

[VSN2015]

Addressed all six review points in dd5be8e (after merging master): infinite/NaN bounds omitted instead of crashing; the inward nudge now checks the field's own cast and comparison, so :float is safe too; format-only strings, validate: and non-numeric ranges added to the looser list and labelled; release notes and README counts reconciled; LOOSER markers checked on the diverging field's own schema; the tables moved into a SchemaConformance module. 671 examples, 0 failures; RuboCop clean. Details are in the updated description.

[VSN2015]

Final regression pass, addressed in fc88567:

1. Regression fixed: optional :x, :float, in: (10**400..) was dropping minimum entirely (the inward-nudge loop overflowed the bound to Infinity via to_f and dropped it), where master published minimum: 10**400 outright. json_bound now returns an integral bound exactly, before the nudge loop, whenever it's beyond Float::MAX — a JSON integer needs no size limit and no Float round-trip. Failing spec added first (publishes an integral bound beyond Float::MAX exactly, matching master), confirmed red, then fixed. A companion spec documents the deliberate omission of a genuinely fractional bound past Float::MAX (no arbitrary-precision JSON fallback exists for that case).
2. Qualified the "narrower than the enforced range" claim in CHANGELOG/README: exact as published, but a client parsing with ordinary doubles can still round across a boundary — inherent to double parsing, not an exporter bug, no code change.
3. Fixed the CHANGELOG/README looser-divergence counts to match spec/schema_conformance_spec.rb's LOOSER table (six keys): split the bundled bullet so each of the six gets its own line, and called out the untranslatable format: regexp case (x-permittable-pattern) as not asserted here — owned by Translate format: regexps into patterns valid under Ajv's u flag #66.
4. Deleted the stale "No behaviour changes: this release adds tests and documentation only" CHANGELOG line.

ASDF_RUBY_VERSION=3.2.2 bundle exec rspec: 673 examples, 0 failures (671 → 673: two new examples this round). ASDF_RUBY_VERSION=3.2.2 bundle exec rubocop: clean.