Saved schemas | Developer tools Docs

Save a JSON Schema once, then name it by schema_id on extract instead of sending it each time. Schemas can't be edited; add a version instead. delete removes a schema with every version. A saved schema, with every version, is kept until you delete it or close your account. Schema routes are free and work at any balance.

Method	Parameters	Returns	Description
`create(name, schema, *, description=None)`	`name: str`, `schema: dict`, `description: str`	`ExtractionSchema`	Saves version 1 of a new schema.
`list(**options)`	`limit: int` (1 to 200, default 50), `cursor: str`	`ExtractionSchemaList`	One page of schemas at their latest version, without their JSON Schema, sorted by `schema_id` (see Order below).
`iter(**options)`	`retry`, `timeout`, `extra_headers`	`Iterator[ExtractionSchema]`	Every schema across every page, 200 a page.
`get(schema_id)`	`schema_id: str`	`ExtractionSchema`	A schema's latest version.
`create_version(schema_id, schema, *, name=None, description=None)`	`schema_id: str`, `schema: dict`, `name: str`, `description: str`	`ExtractionSchema`	Adds the next version. Leave out `name` and `description` to keep the current ones.
`list_versions(schema_id, **options)`	`schema_id: str`, `limit: int` (1 to 200, default 50), `cursor: str`	`ExtractionSchemaList`	One page of the schema's versions, oldest first.
`iter_versions(schema_id, **options)`	`schema_id: str`, `retry`, `timeout`, `extra_headers`	`Iterator[ExtractionSchema]`	Every version, oldest first.
`delete(schema_id)`	`schema_id: str`	`None`	Deletes the schema with every version. Deleting it again does nothing. Extracts already accepted keep the copy they took and finish; afterwards `get` and an extract naming its `schema_id` raise `NaceNotFoundError`.
`get_version(schema_id, version)`	`schema_id: str`, `version: int`	`ExtractionSchema`	One specific version.

Order: list and iter return your schemas and any Nace provides (owner="platform"), which can't take versions, sorted by schema_id the way the document service's database compares text: case-insensitively, with - and _ ignored at first, so not in byte order; sorted(ids) won't match it. Versions come oldest first, version 1 first; for the newest, call get.
No automatic retries on creates: create and create_version aren't idempotent, since a retried create can save a second schema or version. They aren't retried unless you pass retry.
The JSON Schema is schema_, because schema is a Pydantic method name. model_dump(by_alias=True)["schema"] gives it under its wire name.
A limit outside 1 to 200, or a schema_id that is empty or holds /, ? or #, raises NaceError. Another account's schema_id, or deleting one of Nace's, raises NaceNotFoundError.

schemas.py

from nace_sdk import NaceClient

invoice = {
    "type": "object",
    "properties": {"invoice_number": {"type": "string"}, "total": {"type": "number"}},
}

with NaceClient() as client:
    saved = client.extraction_schemas.create("invoice", invoice, description="Invoice header fields")
    client.extraction_schemas.create_version(
        saved.schema_id,
        {**invoice, "properties": {**invoice["properties"], "due_date": {"type": "string"}}},
    )
    for version in client.extraction_schemas.iter_versions(saved.schema_id):
        print(version.version, version.schema_)
    job = client.documents.extract("https://example.com/invoice.pdf", schema_id=saved.schema_id, schema_version=1)

See Extract's saved schemas.