Skip to content

describe/title metadata for toJsonSchema - #24

Merged
cryo2010 merged 1 commit into
mainfrom
feat/schema-metadata
Jul 24, 2026
Merged

cryo2010 merged 1 commit into
mainfrom
feat/schema-metadata

Conversation

@cryo2010

Copy link
Copy Markdown
Owner

Summary

Adds the last item from the JSON Schema polish list: describe(text) and title(text), chainable type-preserving modifiers that attach metadata emitted by toJsonSchema and ignored by everything else:

let user = schema:
  name: string.min(2).describe("Display name")
  role: string.oneOf(["admin", "user"]).title("Role").describe("Access level")

let userDoc = user.title("User").describe("A registered account")

Semantics:

  • Invisible to validation: parsing, issues, Infer, toJson, and re-validation are unaffected; the cost is one pass-through node.
  • Chained calls merge into a single wrapper, last value wins per field; title and describe coexist.
  • A titled recursive schema names its $defs entry (#/$defs/TreeNode instead of #/$defs/def0), with a uniqueness fallback.
  • The hardcoded timestamp() description becomes overridable.
  • Motivating use case documented in the README: schemas with descriptions are directly usable as LLM tool definitions, which consume exactly this format.

Implementation

One transparent nkMeta node plus pass-through arms in validate/normalize/denormalize and a merge arm in nodeToSchema. The subtle part was peeling the wrapper everywhere node kinds are inspected, each now metadata-tolerant and covered by a test:

  • fieldDefOf: alias works in either order relative to metadata
  • strict(): peels, applies strictness, re-wraps (metadata survives)
  • primKind: integer().describe(...).coerce still passes the coerce guard
  • isOptionalField: a described optional field stays out of required
  • objFields: pick/omit/partial/merge see fields through the wrapper

Tests

9 new tests (244 total, passing under orc and arc locally). README (modifiers table, JSON Schema section with an LLM tool-definition example, snippets compile-verified) and DESIGN.md updated.

describe(text) and title(text) attach JSON Schema metadata via a
transparent nkMeta wrapper: validation, parsing, Infer, and round
trips are unaffected; nodeToSchema merges the metadata into the
emitted schema. Chained calls merge into one wrapper with last-wins
semantics, a titled recursive schema names its $defs entry, and the
built-in timestamp description becomes overridable.

The wrapper is peeled wherever node kinds are inspected: fieldDefOf
(alias in either order), strict (re-wrapped after), primKind (coerce
chains), isOptionalField (requiredness), and objFields (object
algebra).
@cryo2010
cryo2010 merged commit 754839f into main Jul 24, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant