Update Taxonomy Block

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

Incrementally mutate a taxonomy block via typed delta lists (elements/structures/associations/rules to add, update, remove). Dispatches by the target taxonomy's stored taxonomy_type. For a chart of accounts: add, rename and reclassify accounts freely; an account with facts or line items is never removed — retire it with elements_to_update[].is_active=false (history stays, new postings are refused, pickers hide it; true reactivates). Removal and whole-chart delete work only with no activity. Library-origin block types (reporting_standard) surface 501. reporting_extension / custom_ontology authoring may be disabled per environment (TAXONOMY_AUTHORING_ENABLED) — disabled surfaces 403. Closed months are immutable against curation: a mapping arc added or removed for an account with landed history in a closed month, or a balance_type / period_type / trait change on such an account, is refused (422, protected_facts) naming the months to reopen first.

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

taxonomy_idrequired string

nameoptional string

descriptionoptional string

versionoptional string

elements_to_addoptional

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

elements_to_updateoptional

ElementUpdatePatch[]

Partial-update patch for a single element, keyed by qname.

ElementUpdatePatch fields

Field	Type	Description
`qname`required	string	qname identifier of the element to update.
`name`optional	string
`description`optional	string
`trait`optional	string
`balance_type`optional	string
`period_type`optional	string
`is_monetary`optional	boolean
`code`optional	string
`parent_ref`optional	string
`metadata`optional	object
`is_active`optional	boolean	Retire (`false`) or reactivate (`true`) a chart account. Retiring keeps its history and hides it from account pickers and the chart tree, and new line items on it are refused — the way to take an account with activity out of use, since removal needs no facts and no line items.

elements_to_removeoptional

string[]

qnames of elements to remove.

structures_to_addoptional

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

structures_to_updateoptional

StructureUpdatePatch[]

Partial-update patch for a single structure, keyed by structure_id. ``concept_arrangement`` makes a mis-CAP'd structure repairable in place (e.g. promoting a ``set`` note to ``roll_up`` so it gains a footing rule); ``block_type`` stays immutable — it drives block-type routing, so changing it is a re-create, not an edit.

StructureUpdatePatch fields

Field	Type	Description
`structure_id`required	string	Structure id to update.
`name`optional	string
`description`optional	string
`role_uri`optional	string
`concept_arrangement`optional	string	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`
`metadata`optional	object

structures_to_removeoptional

string[]

Structure ids to remove.

associations_to_addoptional

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

associations_to_removeoptional

string[]

Association ids to remove.

rules_to_addoptional

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

rules_to_removeoptional

string[]

Rule ids to remove.

Example request

curl

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/update-taxonomy-block" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme CoA (v2)",
  "taxonomy_id": "tax_acme_coa",
  "version": "2.0"
}'

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