Skip to content

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}
  • schema is null when there are errors. Ids already in the schema are kept; with previous_schema, a field without an id that matches it by name, or by position and type after a rename, keeps its id.
  • errors[].rule are the codes of the loader (duplicate_key, empty_enum, external_ref, max_depth_exceeded, instructions_too_long…) plus invalid-field-source and source-cycle from 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.