Domains

A workspace classifies its files against a domain. See Domains for the concept, and the API reference for every field.

• A domain is a two-level taxonomy: a list of classes, each a group and a subgroup with a description written for the classifier.
• Whose it is: Nace provides some (whose owner is platform), and your account can author its own (whose owner is tenant).
• Cost: managing domains costs nothing and works at any balance.

A domain version is a draft or published:

Nace's own domains never change either: copy them the same way. A workspace is pinned to the version it was made with, so editing a copy never reaches it.

To use a published domain, pass its slug to nace workspace-create --domain; see Create a workspace.

Every domain command is nace domains followed by an action, and takes its inputs as flags: the domain's id as --id, never a bare argument. nace domains alone exits 2 and lists the actions.

List domainsCopy Anchor Link

nace domains list --owner platform --status published
# domains (2):
#   <domain_id>  generic  v1  published  platform  Generic
#   <domain_id>  leases  v3  published  tenant  Leases

nace domains list prints domains (<total>):, the number of domains that match, then one line per domain, indented two spaces: <domain_id> <slug> v<version> <status> <owner> <display_name>. Every version of a slug is a domain of its own, so a slug can be listed more than once. When more pages follow, the last line is next: <cursor>. Pass it as --cursor for the next page. An empty list prints domains (0):.

Read a domainCopy Anchor Link

nace domains get --id <domain_id>
# <domain_id>  leases  v1  draft  tenant  Lease files
# classes (2):
#   leases / amendments: Amendments to a signed lease.
#     aliases: lease amendment, amended lease
#   leases / originals: The signed lease as first agreed.

nace domains get prints the domain's line, as nace domains list prints it, then inherits: and the slug of its parent when it has one, then classes (<n>): and one line per class, indented two spaces: <group> / <subgroup>: <description>, with a line aliases: and the class's earlier names, indented four spaces, when it has any. With --json, it prints the whole domain object, with the taxonomy as Drex holds it. A domain you can't see exits 1 with 404 domain_not_found.

Create a domainCopy Anchor Link

nace domains create --slug leases --display-name "Lease files" --taxonomy leases.taxonomy.json
# <domain_id>  leases  v1  draft

nace domains create creates a draft owned by your account and prints its <domain_id> <slug> v<version> <status> line, or {"domain": ..., "validation": ...} with --json. The slug is lowercase letters and digits joined by _, up to 64 characters, and can't be changed later; a blank one exits 2 before any request. One your account already uses fails with 409. The command isn't retried automatically, since a retry after a create that went through would fail with that 409: if it fails with a timeout or a 5xx, check nace domains list --slug before you run it again.

A taxonomy is a list of classes, {"classes": [{"group": ..., "subgroup": ..., "description": ..., "aliases": [...]}]}. Each class has:

• group and subgroup: lowercase letters, digits and single underscores, up to 64 characters each.
• description: what the classifier reads.
• aliases (optional): earlier names. A class without it has none.

If a class doesn't follow these rules, the command is refused with 422 invalid_request, and no draft is made. A class missing group, subgroup or description gets the message "The taxonomy is malformed."

A draft that follows them can still be one nace domains publish refuses: one with no classes, or with a class in the reserved group other. What is wrong with the taxonomy so far is printed on stderr, as the taxonomy has <n> validation errors: and one line per error, - <path>: <message> (<code>), and the command still exits 0.

Update a domainCopy Anchor Link

nace domains update --id <domain_id> --display-name "Leases"
# <domain_id>  leases  v1  draft

nace domains update changes the draft's name, its taxonomy, or both, and prints the same line as nace domains create, or {"domain": ..., "validation": ...} with --json; validation errors go to stderr as they do there. Pass at least one change, --display-name or --taxonomy; with neither, it exits 2 before any request. --taxonomy replaces every class, so send the whole taxonomy. A published domain fails with 409 domain_not_editable, and one of Nace's with 403: run nace domains duplicate and edit the copy.

Publish a domainCopy Anchor Link

nace domains publish --id <domain_id>
# <domain_id>  leases  v1  published

nace domains publish freezes a draft so workspaces can use it by its slug, and prints its line, or {"domain": ..., "validation": ...} with --json. It can't be undone, and the command isn't retried automatically, since a retry after a publish that went through would fail with 409. A taxonomy that fails validation exits 1 and prints each error on stderr, below the error line, as - <path>: <message> (<code>):

error: 422 [invalid_request_error/domain_validation_failed] The taxonomy fails validation. (req_...)
  - taxonomy.classes[1]: 'leases/amendments' is declared more than once; the pair is the folder path. (duplicate_class)

Fix them with nace domains update, then publish again.

Duplicate a domainCopy Anchor Link

nace domains duplicate --id <domain_id>
# <domain_id>  leases_copy_1  v1  draft

nace domains duplicate copies any domain you can see, Nace's included, into a draft owned by your account under a new slug, and prints its line, or {"domain": ..., "validation": ...} with --json. Workspaces pinned to the original never see the copy. The command isn't retried automatically, since a retry after a copy that went through would make a second one.