SchemaForm

Render an accessible form from a JSON Schema object and submit one validated value.

Usage

<script lang="ts">
  import { SchemaForm, readSchemaFormData } from '@lostgradient/cinder';

  const schema = {
    type: 'object',
    properties: {
      name: { type: 'string', minLength: 1 },
      count: { type: 'integer', minimum: 1 },
    },
    required: ['name', 'count'],
  };

  function save(value: unknown) {
    // Called only after validation passes.
  }

  function mirrorDraft(value: unknown) {
    // Called after every edit, even when the value is not schema-valid yet.
  }
</script>

<SchemaForm {schema} name="payload" onDraftChange={mirrorDraft} onSubmit={save} />

SchemaForm always renders a real <form> and a hidden serialized output field. After valid submission, readSchemaFormData(new FormData(form), 'payload') returns the same object delivered to onSubmit.

The three value channels have distinct ownership. value seeds internal state on mount and is not a live binding, so later value changes do not discard active edits. onDraftChange reports the complete current draft after each edit, before schema validation, so consumers can mirror nested or temporarily invalid values. In-progress numeric editors and temporarily unparseable JSON fields are reported as their current raw text until the value commits or parses successfully. onSubmit reports only schema-valid output after submission.

Pass issues to show problems the host found with a submitted value, such as a server-side refusal: each { path, message } appears on the field its path names (property names and array indexes; [] is the whole value) like a built-in validation message, and editing the field clears it. A string with writeOnly: true is a password field. A path that names no field shows on the form itself. A summary of a closed group prints a value as •••• when its schema, or any schema under it, is writeOnly or x-secret, and the hidden output field is emptied once onSubmit settles, and a form whose schema has such a field offers no Edit as JSON panel, since the panel prints the whole value. An optional date, time or date-time field left blank (or cleared) is omitted from the value instead of sent as an empty string, which no RFC 3339 check accepts.

Control shapes

Each shape below has exactly one schema rule. A schema that does not match a rule keeps the rendering it had before (a generic array editor, an object group, or the raw JSON textarea), so a rule never guesses.

A oneOf with two primitives, with an object branch that has no properties, or with more than two branches stays raw JSON. An object that declares properties, or whose additionalProperties is anything other than { "type": "string" }, is not a record.

Large schemas

A form with more than eight fields (an object group counts as the fields inside it, and an array, record or choice counts as one) is large. Large forms add:

• Required fields first, then optional ones, each in schema order, in every object.
• Two columns for short fields (strings, numbers, booleans, selects, durations). Arrays, groups, chips, tags, records, choices and raw JSON take the whole row. The grid falls back to one column when the container is narrow.
• Nested objects as collapsible groups. A required group starts open and an optional one closed. A closed group summarizes what is inside it: the values that differ from their defaults (Damaged · whole order), or else the first field names with none set or, when the schema supplies defaults, defaults (Carrier, Tracking Number… · none set). Groups come only from nested objects in the schema, never from guessing at field names.
• A Find a field filter that matches labels, keys and descriptions, and opens the groups that hold a match.
• Edit as JSON, a panel for pasting a whole input. Apply parses the text, requires an object when the schema is an object, fills in defaults for missing fields, and replaces every field and draft. Pass jsonEditable={false} when the host already offers its own JSON entry point for the payload.

A failed submit clears the filter and opens every group that holds an error, so focus always has a field to land on.