Schema editor (S6)
The schema editor edits an extraction schema (JSON Schema 2020-12 plus x-dx, dialect 1.2) as a
tree. It has two homes: the slot extract.schema of the Studio's configuration panel (an extract
node) and the standalone page /schemas/edit, where a schema is created and tried without a canvas.
Code: web/src/features/schema-editor/; server: POST /v1/schemas:normalize and :import
(src/extractit/api/routers/schemas.py).
What it does
| Part | Component | Notes |
|---|---|---|
| Tree | FieldTree, FieldRow |
role=tree, virtualized (a 200-field schema keeps a few dozen rows in the DOM). Arrows move, Enter edits, Alt+↑/↓ reorders, Delete removes; drag by the handle (@dnd-kit, siblings only) |
| Inspector | FieldInspector, TablePanel |
name, type (string with date, date-time, email, uri, iban, bic, vat_id, phone; number; integer; boolean; enum with enum_descriptions; array of primitives or of objects; object), required, description, instructions (≤ 2 000 characters), x-dx.source (document, lookup, lookup_if_missing, metadata, derived, visual), normalization, evidence, PII and, for arrays of objects, x-dx.table (completeness, row_key, hint) |
| JSON view | JsonSourcePane |
a plain <textarea>; valid JSON is applied as you type. A repeated key is sent to the server as text so it is reported |
| Import / export | ImportMenu |
a JSON Schema or the output of Pydantic's model_json_schema(); export as .schema.json in canonical order. Python source is never run (see below) |
| Preview | PreviewPanel |
the button Probar en documento de muestra runs POST /v1/extract?wait=60 with tier fast (one call per press, none while typing) and shows value, status, confidence and verification; a click on a field opens the evidence viewer with its words highlighted |
Limits the editor enforces: depth 4 (x-dx.max_depth; a field at level 5 is blocked with a message and
the server answers max_depth_exceeded if it is forced from the JSON view), instructions of 2 000
characters, no external $ref, no empty enum, no repeated key. From 26 fields on it suggests splitting
the node (several smaller extractions are more accurate).
Who decides
The client validates as you type (model/validate.ts) and reports the same {pointer, rule} as the
server for what it can see; the server is the authority. 500 ms after the last change the editor calls
POST /v1/schemas:normalize and the list under the editor is exactly its errors[]. Export and
Guardar borrador are disabled while there are errors. A parity test runs both validators over the
corpus tests/golden/invalid-corpus.json.
POST /v1/schemas:normalize
{"schema": {...}, "previous_schema": {...}} # schema may also be the JSON text
200 {"schema": {...with x-dx.field_id...} | null, "errors": [{"pointer","rule","message"}], "field_count": 12}
schemaisnullwhen there are errors. Ids already in the schema are kept; withprevious_schema, a field without an id that matches it by name, or by position and type after a rename, keeps its id.errors[].ruleare the codes of the loader (duplicate_key,empty_enum,external_ref,max_depth_exceeded,instructions_too_long…) plusinvalid-field-sourceandsource-cyclefrom the deep check of the field sources (a derived field that names a field that does not exist, a lookup table that does not exist in the project).
POST /v1/schemas:import
{"format": "json_schema" | "pydantic_json_schema", "document": {...} | "<json text>"}
Local $defs and $ref are inlined and anyOf [X, null] becomes an optional field. Python source
(a .py file or pasted code) is 422 PYTHON_SOURCE_NOT_ACCEPTED: nothing the user sends is ever
executed; the bridge from a real Pydantic model is the SDK of T45.
References by field_id
Every field has an x-dx.field_id (fld_…). Renaming a field in the tree changes its key and keeps
its id, and a rule, a derived expression or a lookup refers to the id: nothing breaks on a rename.
The tree model keeps what it does not edit ($comment, examples, x-extract-hint, unknown x-dx
keys) in extras and writes it back verbatim; importing and exporting a schema gives the same JSON
after canonical ordering (canonicalize: known keys first, the rest alphabetical, required sorted;
the order of properties and enum is kept). A property test (fast-check) checks that no key is lost.
Vendor keys
The dialect rejects an unknown x-… key outside x-dx (unsupported_keyword); $comment,
examples and default are accepted and dropped by the loader. The editor keeps all of them, so
the server's verdict is what the user sees in the list.
Using it
<SchemaEditor
value={schema} // JSON Schema with x-dx
onChange={(schema) => …} // every edit, as JSON
sampleProvider={() => file} // optional: a sample document for the preview
readOnly={false}
onValidityChange={(valid, errors) => …}
/>
In the Studio the widget is registered by features/schema-editor/studio/register.ts (the glob of
components/schema-form/load.ts imports it) and loaded as a deferred chunk; the initial bundle is
unchanged.
Accessibility and security
role=tree with aria-level, aria-posinset, aria-setsize and aria-expanded; every operation has
a keyboard path. Names, descriptions and instructions are rendered as text (React escapes them; the
CSP forbids inline script) and the E2E checks that HTML in them produces no element and no CSP
violation.