Create Taxonomy Block

post/extensions/roboledger/{graph_id}/operations/create-taxonomy-block

Create a taxonomy block atomically: one envelope carrying the taxonomy row plus its structures, elements, associations, and rules. Dispatches by taxonomy_type — chart_of_accounts (declarative tenant CoA), reporting_extension, and custom_ontology are supported; reporting_standard is library-origin (501). reporting_extension / custom_ontology authoring may be disabled per environment (TAXONOMY_AUTHORING_ENABLED) — disabled surfaces 403. NOT the path for a functional close schedule: a structure with block_type='schedule' here is a bare ontology row with none of the schedule machinery (per-period facts, schedule_entry_due obligations, closing-entry generator). To create a working schedule use create-information-block(block_type='schedule').

Idempotency: supply an Idempotency-Key header to make safe retries; replays within 24 hours return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.

Authentication

Authenticate in any one of these ways — not all of them:

API key in the X-API-Key header.
Bearer token in the Authorization header.

Path parameters

Name	Type	Description
`graph_id`required	string	Graph Id

Header parameters

Name	Type	Description
`Idempotency-Key`optional	string	Idempotency-Key

Request body

Required, application/json.

Field Type Description

namerequired

string

Taxonomy display name.

taxonomy_typerequired

string

Block-type discriminator. ``chart_of_accounts`` and ``custom_ontology`` construct from scratch; ``reporting_extension`` extends an existing library ``reporting_standard``.

One of: reporting_standard, reporting_extension, custom_ontology, chart_of_accounts, schedule

parent_taxonomy_idoptional

string

Required when ``taxonomy_type == 'reporting_extension'`` — the id of the library ``reporting_standard`` being extended.

versionoptional string

descriptionoptional string

standardoptional string

namespace_urioptional string

elementsoptional

TaxonomyBlockElementRequest[]

Element definition inside a Taxonomy Block envelope. ``qname`` is the envelope-local identifier — must be unique within the envelope's ``elements`` list and is used by association / rule / patch payloads as the reference token. ``parent_ref`` may reference another envelope-local qname or, for ``reporting_extension`` blocks, a library element qname.

TaxonomyBlockElementRequest fields

Field	Type	Description
`qname`required	string	Envelope-local element identifier. Must be unique within the envelope's ``elements`` list. Used as the reference token for associations, rules, and update patches.
`name`required	string	Human-readable element name (e.g. 'Total Assets').
`trait`optional	string	FASB metamodel trait for the element. Required for ``chart_of_accounts`` blocks; optional for ``custom_ontology``.
`balance_type`optional	string	'debit' \| 'credit' \| null for non-monetary concepts.
`element_type`optional	string	'concept' \| 'abstract' \| 'axis' \| 'member' \| 'hypercube'. Default: `concept`
`period_type`optional	string	'instant' \| 'duration' \| null (null = derive from classification during validation).
`is_monetary`optional	boolean	True for dollar-denominated concepts. Default: `true`
`description`optional	string
`code`optional	string	Optional chart-of-accounts code (e.g. '1000', '4100-02'). Only meaningful for ``chart_of_accounts`` blocks.
`sub_classification`optional	string
`parent_ref`optional	string	qname of the parent element — either another envelope-local qname or, for ``reporting_extension`` blocks, a library element qname.
`metadata`optional	object

structuresoptional

TaxonomyBlockStructureRequest[]

Structure definition inside a Taxonomy Block envelope.

TaxonomyBlockStructureRequest fields

Field	Type	Description
`name`required	string	Envelope-local structure name (unique within envelope).
`block_type`required	string	DB ``structures.block_type`` enum. CoA blocks use ``chart_of_accounts``; reporting extensions use the statement family, ``regulatory_disclosure`` (disclosure notes), or ``custom``; custom ontology uses ``custom``. One of: `chart_of_accounts`, `custom`, `balance_sheet`, `income_statement`, `cash_flow_statement`, `equity_statement`, `coa_mapping`, `schedule`, `rollforward`, `reconciliation`, `policy`, `metric`, `regulatory_disclosure`
`concept_arrangement`optional	string	Concept Arrangement Pattern (CAP) — how the structure's concepts relate (mirrors the ``structures.concept_arrangement`` CHECK vocabulary). A disclosure note footing members to a total is ``roll_up``. Null leaves the pattern unset. One of: `set`, `roll_up`, `roll_forward`, `roll_forward_info`, `adjustment`, `variance`, `arithmetic`, `text_block`, `level1_textblock`, `level2_textblock`, `level3_textblock`, `level4_detail`, `table_equivalent_textblock`, `grid`, `compound_fact`
`description`optional	string
`role_uri`optional	string
`metadata`optional	object

associationsoptional

TaxonomyBlockAssociationRequest[]

Association (arc) between two elements, scoped to a structure.

TaxonomyBlockAssociationRequest fields

Field	Type	Description
`structure_ref`required	string	Envelope-local structure name (references a structure declared in the same envelope).
`from_ref`required	string	qname of the source element.
`to_ref`required	string	qname of the target element.
`association_type`required	string	DB ``associations.association_type`` enum. ``presentation`` = parent-child hierarchy; ``calculation`` = summation arc. One of: `presentation`, `calculation`, `mapping`, `equivalence`, `general-special`, `essence-alias`
`order_value`optional	number
`arcrole`optional	string
`weight`optional	number	Calculation-arc coefficient (+1 / -1 for summation, other values for weighted rollups). Null for non-calculation arcs.
`metadata`optional	object

rulesoptional

TaxonomyBlockRuleRequest[]

Rule definition inside a Taxonomy Block envelope. Exactly one of ``target_structure_ref``, ``target_element_qname``, or ``target_taxonomy_self`` must be set (or all null for a global rule). The ``model_validator`` enforces this contract at the Pydantic layer. Only **arithmetic** rule patterns are user-creatable via this API (the ``rule_pattern`` Literal below). The 6 model-structure check kinds (``NoCycles``, ``NoOrphanArcs``, ``ParentBeforeChild``, ``LeafHasClassification``, ``LibraryOriginImmutability``, ``UniqueQNameInTaxonomy``) are system-managed — they're auto-emitted by :func:`emit_auto_rules` at taxonomy-block creation time and populate ``rules.rule_check_kind`` instead of ``rule_pattern``.

TaxonomyBlockRuleRequest fields

Field	Type	Description
`name`required	string	Rule identifier, unique within envelope.
`description`optional	string
`rule_category`required	string	One of 8 cm:VerificationRule subclasses. One of: `AutomatedAccountingAndReportingChecks`, `DisclosureMechanicsRule`, `FundamentalAccountingConceptRelation`, `PeerConsistencyRule`, `PriorPeriodConsistencyRule`, `ReportLevelModelStructureRule`, `ReportingSystemSpecificRule`, `ToDoManualTask`, `XBRLTechnicalSyntaxRule`
`rule_pattern`required	string	One of the cm:BusinessRulePattern mechanisms. 'Derive' rules COMPUTE a value from bound operand facts (compute-metrics) rather than verify one — the tenant-authored-metric pattern. One of: `Adjustment`, `CoExists`, `Derive`, `EqualTo`, `Exists`, `GreaterThan`, `GreaterThanOrEqualToZero`, `LessThan`, `RollForward`, `RollUp`, `SumEquals`, `Variance`
`expression`required	string	XPath-flavored predicate body (the rule expression).
`variables`optional	object[]	``$Variable`` → qname bindings. Each entry is ``{'variable_name': str, 'variable_qname': str}``.
`severity`optional	string	One of: `info`, `warning`, `error` Default: `error`
`target_structure_ref`optional	string	Envelope-local structure name this rule targets (for structure-scoped rules). Mutually exclusive with the other target_* fields.
`target_element_qname`optional	string	qname of the element this rule targets. Mutually exclusive with the other target_* fields.
`target_taxonomy_self`optional	boolean	True iff the rule targets the envelope's own taxonomy row (``target_kind='taxonomy'``). Mutually exclusive with the other target_* fields. Default: `false`
`message`optional	string
`metadata`optional	object

metadataoptional object

Example request

curl

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/create-taxonomy-block" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "elements": [
    {
      "balance_type": "debit",
      "code": "1000",
      "name": "Cash",
      "qname": "acme:Cash",
      "trait": "asset"
    },
    {
      "balance_type": "credit",
      "code": "2000",
      "name": "Accounts Payable",
      "qname": "acme:AccountsPayable",
      "trait": "liability"
    }
  ],
  "name": "Acme CoA",
  "structures": [
    {
      "block_type": "chart_of_accounts",
      "name": "main"
    }
  ],
  "taxonomy_type": "chart_of_accounts"
}'

Responses

200 Successful Response

Field Type Description

operationrequired

string

Kebab-case operation name

operationIdrequired

string

op_-prefixed ULID for audit and SSE correlation

statusrequired

string

Operation lifecycle state

One of: completed, pending, failed

resultoptional

TaxonomyBlockEnvelope

Command-specific result payload

TaxonomyBlockEnvelope fields

Field Type Description

idrequired

string

Taxonomy row id.

namerequired string

taxonomy_typerequired

string

Block-type discriminator — 'reporting_standard' | 'reporting_extension' | 'chart_of_accounts' | 'custom_ontology'.

display_namerequired

string

Registry-sourced display label.

categoryrequired

string

Registry-sourced sidebar grouping.

parent_taxonomy_idoptional string

parent_taxonomy_nameoptional string

versionoptional string

standardoptional string

namespace_urioptional string

is_lockedoptional

boolean

Default: false

elementsoptional

TaxonomyBlockElement[]

Element projection for the Taxonomy Block envelope.

TaxonomyBlockElement fields

Field	Type	Description
`id`required	string
`qname`optional	string
`name`required	string
`trait`optional	string
`balance_type`optional	string
`period_type`optional	string
`element_type`optional	string	Default: `concept`
`is_monetary`optional	boolean	Default: `true`
`parent_qname`optional	string
`depth`optional	integer
`origin`required	string	Provenance — 'library' if the element's taxonomy is locked (``is_locked=true``), else 'tenant'. One of: `library`, `tenant`

structuresoptional

TaxonomyBlockStructure[]

Structure projection for the Taxonomy Block envelope.

TaxonomyBlockStructure fields

Field	Type	Description
`id`required	string
`name`required	string
`block_type`required	string
`description`optional	string
`role_uri`optional	string

associationsoptional

TaxonomyBlockAssociation[]

Association projection for the Taxonomy Block envelope.

TaxonomyBlockAssociation fields

Field	Type	Description
`id`required	string
`structure_id`required	string
`from_element_qname`required	string
`to_element_qname`required	string
`association_type`required	string
`order_value`optional	number
`arcrole`optional	string
`weight`optional	number

rulesoptional

TaxonomyBlockRule[]

Rule projection for the Taxonomy Block envelope. Exactly one of ``rule_pattern`` (arithmetic) or ``rule_check_kind`` (model-structure) is non-null per row, enforced by the ``check_rule_pattern_kind_xor`` DB constraint.

TaxonomyBlockRule fields

Field	Type	Description
`id`required	string
`name`required	string
`rule_category`required	string
`rule_pattern`optional	string
`rule_check_kind`optional	string
`rule_expression`required	string
`severity`optional	string	Default: `error`
`origin`optional	string	'forked' \| 'native' \| 'auto' — matches DB CHECK. Default: `native`
`target_kind`optional	string
`target_ref`optional	string	Polymorphic display string — structure_id, element qname, association_id, or taxonomy_id depending on ``target_kind``.

verification_resultsoptional object[]

element_countoptional

integer

Default: 0

structure_countoptional

integer

Default: 0

association_countoptional

integer

Default: 0

atrequired

string

ISO-8601 UTC timestamp

createdByoptional

string

User ID that initiated the operation (null for legacy callers)

idempotentReplayoptional

boolean

True when this envelope came from the idempotency cache — the underlying command did not execute again. False on fresh executions.

Default: false

Status	Meaning
400	Invalid request
401	Authentication required
403	Access denied
404	Resource not found
409	Idempotency-Key conflict — key reused with different body
422	Validation error
429	Rate limit exceeded
500	Internal server error