Saved schemas | Developer tools Docs

Save a JSON Schema once, then name it with schema_id on an extract instead of sending it each time. Schemas can't be edited; add a version instead. You can delete a schema with every version. A saved schema, with every version, is kept until you delete it or close your account. Extracts already accepted keep the copy they took. The schema routes are free and work at any balance.

Method	Returns	Description
`extractionSchemas.create(params, options?)`	`APIPromise<ExtractionSchema>`	Saves version 1 of a new schema.
`extractionSchemas.list(params?, options?)`	`APIPromise<ExtractionSchemaList>`	One page of schemas at their latest version, sorted by `schema_id` (case-insensitively, with `-` and `_` ignored at first; not byte order), without `schema`.
`extractionSchemas.iter(params?, options?)`	`AsyncGenerator<ExtractionSchema>`	Every schema, in `list`'s order, 200 a page. `params` takes no filters.
`extractionSchemas.get(schemaId, options?)`	`APIPromise<ExtractionSchema>`	A schema's latest version.
`extractionSchemas.createVersion(schemaId, params, options?)`	`APIPromise<ExtractionSchema>`	Adds the next version, which becomes the latest.
`extractionSchemas.listVersions(schemaId, params?, options?)`	`APIPromise<ExtractionSchemaList>`	One page of a schema's versions, oldest first.
`extractionSchemas.iterVersions(schemaId, params?, options?)`	`AsyncGenerator<ExtractionSchema>`	Every version, oldest first, 200 a page.
`extractionSchemas.getVersion(schemaId, version, options?)`	`APIPromise<ExtractionSchema>`	One version.
`extractionSchemas.delete(schemaId, options?)`	`Promise<void>`	Deletes the schema with every version. Deleting it again resolves too; Nace's schemas and another account's are a `404`.

Parameter type	Fields
`CreateExtractionSchemaParams`	`name` (1 to 128 characters), `schema` (the JSON Schema), `description?` (up to 2000 characters).
`CreateExtractionSchemaVersionParams`	`schema`, and `name?` and `description?`, which keep their current values when left out.
`ExtractionSchemaListParams`	`limit?` (1 to 200, default 50; out of range throws a `NaceError`) and `cursor?`.

Retries: create and createVersion aren't idempotent, so they aren't retried unless you pass retry in options: a retried create can save a second schema.
Nace's schemas: the list can include schemas Nace provides, with owner: "platform". You can extract with them, but they take no new versions (404).
Ids: another account's schema_id answers 404. An empty id, or one with /, ? or #, throws a NaceError before sending.

An ExtractionSchema has schema_id, name, description, version, owner ("account" or "platform"), created_at, updated_at and schema, which list and iter leave out; version pages include it. An ExtractionSchemaList has items, next_cursor and, when the service counts them, total_count.

schemas.ts

const saved = await client.extractionSchemas.create({
  name: "invoice",
  description: "Invoice header fields",
  schema: {
    type: "object",
    properties: { invoice_number: { type: "string" }, total: { type: "number" } },
  },
});

const job = await client.documents.extract({
  source: "https://example.com/invoice.pdf",
  schema_id: saved.schema_id,
});

const v2 = await client.extractionSchemas.createVersion(saved.schema_id, {
  schema: {
    type: "object",
    properties: { invoice_number: { type: "string" }, total: { type: "number" }, due_date: { type: "string" } },
  },
});
await client.documents.extract({
  source: "https://example.com/invoice.pdf",
  schema_id: saved.schema_id,
  schema_version: v2.version,
});

for await (const version of client.extractionSchemas.iterVersions(saved.schema_id)) {
  console.log(version.version, version.name);
}

See Extract's saved schemas.