Create a JSON schema converter package

[jonthegeek]

Summary

Track the creation of a separate package that converts JSON Schema documents into stbl specifications. stbl supplies all the validation/coercion machinery; this package is the final, JSON-Schema-specific layer on top of it and depends strongly on stbl.

This issue is a capturing point — the pieces below will become individual issues in the converter package's own repo.

What the package does

Given a JSON Schema (per JSON Schema draft 2020-12 / draft-bhutton-json-schema-01), produce an stbl spec (e.g. a specify_*() closure or a stabilize_*() call) that validates and coerces R values as the schema describes. Roughly:

• A top-level json_schema_to_stbl() entry point that walks a parsed schema and emits the corresponding stbl spec.
• Keyword-by-keyword mapping from JSON Schema to stbl primitives (most of which are being added to stbl separately — see below).

Mapping to stbl primitives (built in stbl)

These land in stbl and the converter just wires them up:

• Types → stabilize_chr(), stabilize_dbl(), stabilize_int(), stabilize_lgl(), stabilize_lst(), etc.
• minLength / maxLength → min_characters / max_characters (feat: min_characters / max_characters for stabilize_chr() #275)
• enum / const → allowed_values (feat: allowed-values constraint (enum / const) for stabilize_*() #282)
• exclusiveMinimum / exclusiveMaximum → exclusive_min / exclusive_max (feat: exclusive_min_value / exclusive_max_value for stabilize_int() and stabilize_dbl() #276)
• multipleOf → multiple_of (feat: multiple_of constraint for stabilize_int() and stabilize_dbl() #283)
• required (optionality) → optional named properties (feat: optional named properties in stabilize_lst() #279)
• additionalProperties → additional-element control (feat: control additional named elements in stabilize_lst() #281)
• uniqueItems → uniqueness constraint (feat: unique-elements constraint (uniqueItems) for stabilize_*() #280)
• prefixItems / tuple items → positional element specs (feat: positional (tuple) element specs in stabilize_lst() #284)
• items → stabilize_each() (feat: stabilize_each() #287)
• anyOf → stabilize_any_of() (rename, chore: rename stabilize_one_of() / to_one_of() to *_any_of() #285)
• oneOf → stabilize_one_of() exactly-one (feat: stabilize_one_of() (exactly one) #286)
• allOf → stabilize_all_of() (feat: stabilize_all_of() family #278)
• composition factories → specify_any_of() / specify_one_of() / specify_all_of() (feat: specify_any_of(), specify_one_of(), and specify_all_of() #288)
• not → assert_not() (feat: assert_not() #289)
• contains / minContains / maxContains → element-count constraints (feat: assert_contains() function #290)
• propertyNames → named accepting a spec (feat: named arg for stabilize_*() (covers propertyNames) #8)
• patternProperties → stabilize_lst() extension (feat: patternProperties support in stabilize_lst() #292)
• dependentRequired → stabilize_lst() extension (feat: dependentRequired support in stabilize_lst() #291)

For format, see "Format handling" below — this package owns it.

Format handling (owned by this package)

JSON Schema format (draft 2020-12 §7.3) names a string's semantic type. This package owns format support, splitting the defined formats by whether the value maps to a genuine R class:

Temporal formats → core stbl stabilizers. These coerce to real R classes (and want bidirectional to_*() methods), so they belong in stbl and the converter just wires them up:

• date → stabilize_date() / to_date() — stbl feat: stabilize_date() (RFC 3339 date) #104 (exists)
• date-time → stabilize_datetime() / to_datetime() — stbl feat: stabilize_datetime() (RFC 3339 date-time) #105 (exists)
• time → stabilize_time() — no stbl issue yet; needs one
• duration → stabilize_duration() — no stbl issue yet; needs one

String formats → this package's specify_chr() wrappers. These stay character and are validate-only (regex/rule checks). This package supplies a catalog of format rules and dedicated stabilize_uuid()-style wrappers that are thin aliases over specify_chr() (e.g. stabilize_uuid() ≈ specify_chr() with the UUID rule):

• email, idn-email
• hostname, idn-hostname
• ipv4, ipv6
• uri, uri-reference, iri, iri-reference
• uuid
• uri-template
• json-pointer, relative-json-pointer
• regex

Out of scope here: #80 also lists non-format types (stabilize_int64(), stabilize_base64_to_chr(), stabilize_binary_to_raw(), stabilize_structured_lgl(), etc.). Those come from OpenAPI or from JSON Schema's contentEncoding / contentMediaType keywords rather than format, and are a separate decision (likely converter-side or out of scope).

What the converter package owns (not stbl)

These are JSON-Schema-document concerns with no place in stbl itself:

• json_schema_to_stbl() — the walker/dispatch that turns a parsed schema into stbl calls.
• Parsing / ingestion — accept schema as parsed list, JSON string, or file/URL; pick a JSON parser.
• format support — the format-rule catalog and the string-format specify_chr() wrappers above (stabilize_uuid(), stabilize_email(), …).
• $ref / $defs resolution — internal reference and definition indirection, recursion, and (optionally) remote $ref fetching.
• Conditional schemas — if / then / else and dependentSchemas: cross-property orchestration assembled from stbl's spec-evaluation machinery (stabilize_*_of(), assert_not()), rather than new stbl primitives. (dependentRequired is the exception and lives in stbl, feat: dependentRequired support in stabilize_lst() #291.)
• Metadata / annotations — title, description, default, examples, $comment, $schema, $id: carry through or ignore as appropriate.
• Draft/dialect handling — decide which JSON Schema draft(s) to support and how strictly.

Dependencies / sequencing

The converter can't be finished until the stbl-side primitives above land. A reasonable order: composition-family rename (#285) and stabilize_each() (#287) first (they underpin most array/union handling), then scalar constraints, then the object-shape features (#279, #281, #292, #291, #8), then the walker itself. The temporal stabilizers (stabilize_date() #104, stabilize_datetime() #105, and new stabilize_time() / stabilize_duration() issues) are additional stbl prerequisites for full format coverage.