Skip to main content
The schema-driven form renderer and the JSON Schema helpers it is built on.

CompletionProvider

Fetch argument-value suggestions for a string field. argName is the field’s path within the form (a property key at the root, a dotted path when nested); partial is the value typed so far. The caller owns the source (e.g. an MCP completion/complete call) — SchemaForm only routes string fields through the completion-backed input when a provider is supplied.

DateRangePair

A START/END pair drawable as one range control, resolved off a page’s properties. Properties Related: JsonSchema

Discriminator

A Pydantic-style discriminated-union tag: which property selects the variant. Properties

ExpressionFieldComponent

The expression-authoring door a host INJECTS into the form — JqField, which the host imports straight from @tai42/jq-studio. It is a COMPONENT, rendered as an element, never called as a function: the door owns hooks and state (editor open, worker handle), which only survive as its own element identity. A host may inject a lazy door to keep the jq subgraph in a split chunk — the form mounts it inside a Suspense boundary that paints the resting shell while that chunk resolves. Related: ExpressionFieldProps

ExpressionFieldContext

The ambient door for the whole form. Absent (the default), an expression-annotated field renders the PLAIN string input, byte-identically to an unannotated one — the jq authoring door is opt-in, because the dynamic import that would fetch it on demand still EMITS its chunks, worker, and wasm into every consumer that bundles the SDK. A host wires it ONCE above its tree (SchemaEditor’s preview and ElicitationForm render forms a caller does not own the props of, and a plugin page renders its own); the form’s own expressionField prop overrides it for a single form. Related: ExpressionFieldComponent

ExpressionFieldProps

Exactly the props the form hands an injected expression field — no more, so any expression editor can satisfy the contract, and no less, so the form is free to pass all of them. The label/description/error slots are the door’s own chrome: an expression field brings its a11y-linked label and helper slots, so the form does NOT wrap it in the usual Field. Properties Related: ExpressionInputShape

ExpressionInputKey

One top-level key of the expression’s input document, with a one-line gloss. Properties

ExpressionInputShape

What . IS for an expression-annotated field, as the form hands it to the injected door. Built by the renderer from the schema’s x-tai42-expression annotation. Like the annotation type it is built from, this MIRRORS jq-studio’s input-shape descriptor without importing it: the schema-form tree names no jq type, in code OR in its declarations, which is what keeps a consumer that never injects a door free of the jq subgraph. JqField satisfies it structurally; a test pins that. Properties Related: ExpressionInputKey

FieldWords

A form field’s own words, keyed by the root object’s property name in a form’s fieldWording. Every member is optional; an unset one draws the SDK’s own word.
  • choiceLabel: the placeholder of the field’s enum select (in place of Select…).
  • invalid: the sentence that replaces every shape error on the field and anything inside it (a format, pattern, length, bound, type or item error).
  • required: the sentence shown when the field’s required value is missing, at the field or anywhere inside it (in place of "<name>" is required).
  • addItem / removeItem / itemLabel / noItems: a list field’s add button, each item’s remove button, each item’s heading (its {n} token takes the item’s number), and the line shown while the list is empty.
Properties

FormControl

The CONTROL a surface draws for a property in place of the default for the property’s shape. chips draws a choice (a string with an enum, or an array of such strings) as a tap-to-select chip grid instead of the radio/select or checkbox group. textarea draws a string as a multi-line text control instead of a single-line box. It changes what is DRAWN, never what is accepted — the value and its validation stay the property’s own.

FormInputMode

The input KIND a string field collects, drawn as the matching keyboard or native control. The vocabulary is the HTML inputmode/control naming of the concept: numeric/decimal set a text box’s keyboard hint; tel/email/url select the matching native control. It draws, it does not validate.

JsonSchema

A structural JSON Schema node. All keys optional; the index signature keeps the type permissive so an unrecognized keyword is never a type error — it is a runtime classification concern the renderer handles. Properties Related: Discriminator, FormControl, FormInputMode, JsonSchemaType

JsonSchemaType

The JSON-Schema type keyword values Pydantic emits.

NoFiniteValueError

Thrown by defaultValueForSchema and skeletonValueForSchema when the schema admits no finite value: a chain of required properties refers back to its own definition with no null accepted on the way. A caller that seeds on a user action catches exactly this type to show the failure on its field; any other error is not a seeding outcome and propagates.

RecordEntryContext

One record entry, handed to a host-supplied value renderer. Properties Related: JsonSchema

RecordEntryRenderer

A host-supplied per-entry value renderer for record fields — the injection point a masked/secret editor (or any other value affordance) mounts through. It returns the node to render in the entry’s value slot; returning entry.defaultField falls back to the built-in editor. Absent (the default), every entry renders its defaultField. Related: RecordEntryContext

RecordEntryRendererContext

Related: RecordEntryRenderer

SchemaForm

Render a controlled form for schema. The root is usually an object (a tool’s input schema); a scalar/array/union root renders as a single field group. Props Related: SchemaFormProps

SchemaFormErrors

A structured, per-path bag of validation problems. Keys are dotted/bracketed paths from the form root ("" = the root value, "user.name", "tags[0]"); each entry is a loud, human-readable message. Empty object = valid.

SchemaFormProps

Properties Related: CompletionProvider, ExpressionFieldComponent, FieldWords, JsonSchema

SecretRef

The value SecretRefField emits and reads back. The source discriminant is what the host branches on:
  • key — reference an existing env key; the host resolves the reference.
  • paste — a new plaintext secret; the host stores it under a generated key and records the reference. secret is write-only and never rendered.

SecretRefField

Props Related: SecretRefFieldProps

SecretRefFieldProps

Properties Related: SecretRef

TemplatedTextCatalogContext

The ambient stored-template source for the whole form. Absent (the default), a templated-text field gets no catalog, as every TemplatedTextField given none: the stored source offers no templates and inline content is authored as usual. Related: UseTemplatedTextCatalog

UseTemplatedTextCatalog

The hook a host supplies so a form’s templated-text fields can offer stored templates: it returns the catalog (the template ids plus the storage-presence and fetch state) the field’s stored-template picker reads. The form holds no data edge, so the host owns the fetch; a field calls the hook only when it renders, so a form without a templated-text field never fetches the catalog. It is a HOOK, called on every render of a templated-text field, so the injected reference must be stable (a module-level function). Related: TemplatedTextCatalog

dateRangePairs

The date-range pairs among properties that are drawable as ONE control. A pair qualifies when: the END names an existing sibling START in rangeStart; BOTH are format: date; both carry the SAME visibleWhen (deep-equal, or both absent); AND no OTHER field’s visibleWhen names either end — otherwise merging the pair would leave that field’s predicate pointing at a control that no longer draws on its own, so the pair stays two date fields (the documented degrade). properties is ONE page’s ordered list; a field is used in at most one pair. Each pair also names each end’s timeOf time among the same properties, which draws inside the group. Parameters Related: DateRangePair, JsonSchema

defaultValueForSchema

The initial value for a schema. root carries the $defs document for $ref resolution and defaults to the schema itself (the common whole-tool-schema call). Parameters Related: JsonSchema

fieldDrawingOrder

names in drawing order: each timeOf time moved to sit right after the date it names. names is one page’s fields, or every property of a page-less form or a readback, in their given order. A time moves only when the name it points at is in names and does not itself point at another listed name; any other time (its date not listed, a chain of times, a cycle) keeps its place. Every name appears exactly once and every other name keeps its relative order. Pure and idempotent, so every walker that orders the same list draws it the same way. Parameters Related: JsonSchema

isFieldVisible

Whether a property carrying schema.visibleWhen is visible against the current values of its enclosing object. Absent predicate ⇒ always visible. Exactly one of equals/in/notEmpty must be present; otherwise the predicate is malformed and the field stays visible. Parameters Related: JsonSchema

resolveRef

Resolve an internal $ref against the document root, following chained refs (a $ref whose target is itself a $ref). Only same-document pointers are supported (#/$defs/Name, #/definitions/Name, #); an external or unresolvable ref throws LOUDLY rather than yielding a silent empty schema. A schema with no $ref is returned unchanged. A pointer cycle throws. Parameters Related: JsonSchema

validateAgainstSchema

Validate value against schema, returning a per-path error bag (empty = valid). The caller runs this before submit and feeds the result back to SchemaForm for display. options.maxUploadBytes mirrors the renderer’s maxUploadBytes prop so a media field’s byte cap is enforced identically here; options.fieldWording puts a field’s own invalid sentence in place of the SDK’s word for any shape error on that field, and its own required sentence in place of the SDK’s message for a missing required value at or inside that field. Parameters Related: JsonSchema, SchemaFormErrors