Perception
Saved schemas
Save a JSON Schema once, then name it with nace extract --schema-id instead of sending it every time. Saved schemas are free and work at any balance. See Saved schemas.
List and read schemas
nace schemas # yours and Nace's, by schema_id
nace schema sch_... > invoice.schema.json # the JSON Schema itself
nace schema-versions sch_... # oldest first
nace schema-version sch_... 2| Command | What it prints |
|---|---|
schemas | One line per schema at its latest version, sch_... vN name, 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. It can also include schemas Nace provides, whose owner is platform. |
schema SCHEMA_ID | The latest version's JSON Schema on stdout, ready for --schema, and its sch_... vN name line on stderr. |
schema-versions SCHEMA_ID | One line per version, oldest first. |
schema-version SCHEMA_ID VERSION | That version's JSON Schema, like schema. |
schemas and schema-versions page like nace jobs:
| Flag | What it does |
|---|---|
--limit N | Items per page, 1 to 200 (default 20). A larger number exits 2. |
--cursor CURSOR | Start at this page: the next_cursor of the page before. |
--all | Every item, across every page. Not with --cursor. |
--json | Print {"items": [...], "next_cursor": ...}. Items from schemas leave out the JSON Schema; items from schema-versions include it as schema. |
Without --json, when more pages follow, stderr says more schemas: --cursor <next> (or --all), or more versions. An empty list says no schemas (or no versions) on stderr. With --json, the list commands print {"items": [...], "next_cursor": ...} and nothing on stderr. With --json, schema and schema-version print the whole record: schema_id, name, version, owner, created_at, updated_at and schema, plus description when the schema has one.
Save a schema or a version
nace schema-create invoice --schema invoice.schema.json --description "Invoice header fields"
# sch_... v1 invoice
nace schema-version-add sch_... --schema invoice-v2.schema.json
# sch_... v2 invoice| Command | Flag | What it does |
|---|---|---|
schema-create NAME | -s, --schema SCHEMA | Required. The JSON Schema, as a JSON object: a file path, @FILE, inline JSON, or -. |
--description TEXT | What the schema is for. | |
schema-version-add SCHEMA_ID | -s, --schema SCHEMA | Required. The new version's JSON Schema. |
--name NAME | Rename the schema; omit it to keep the current name. | |
--description TEXT | Omit it to keep the current description. |
Both print the saved version's sch_... vN name line on stdout, or the whole record with --json. A saved version can't be edited: add a version instead, or delete the whole schema with nace schema-delete. Nace's own schemas can't take versions.
Neither command is retried automatically, because a retry could save a second schema or version. If one fails with a timeout or a 5xx, check nace schemas or nace schema-versions before you run it again.
Delete a schema
nace schema-delete sch_...nace schema-delete <schema_id> deletes one of your saved schemas with every version. Stderr says deleted <schema_id>; stdout stays empty. Deleting a schema that is already deleted succeeds again. Afterwards nace schema and an extract with its --schema-id fail with 404 schema_not_found; extracts already accepted keep the copy of the schema they took and finish. Nace's own schemas and another account's fail with 404.
A saved schema, with every version, is kept until you delete it or close your account.