---
title: "Update Taxonomy Block"
method: POST
path: "/extensions/roboledger/{graph_id}/operations/update-taxonomy-block"
tags: ["RoboLedger: Taxonomy & Mapping"]
---

# Update Taxonomy Block

`POST /extensions/roboledger/{graph_id}/operations/update-taxonomy-block`

## Request

- Base URL: `https://api.robosystems.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/update-taxonomy-block`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

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. An envelope that removes an account's arc and adds one on the same primary statement moves it: a reclassification, allowed.

**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.

## Path parameters

- `graph_id` string, required

## Headers

- `Idempotency-Key` string, nullable

## Request body

- UpdateTaxonomyBlockRequest: Request body for the `update-taxonomy-block` operation. Top-level fields (name / description / version) apply to the taxonomy row itself. The delta lists mutate atoms incrementally — the validator re-runs every create-time check across the projected post-update state before anything commits.
  - `taxonomy_id` string, required
  - `name` string, nullable
  - `description` string, nullable
  - `version` string, nullable
  - `elements_to_add` TaxonomyBlockElementRequest[]
    - `qname` string, required: 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` string, required: Human-readable element name (e.g. 'Total Assets').
    - `trait` string, nullable: FASB metamodel trait for the element. Required for `chart_of_accounts` blocks; optional for `custom_ontology`.
    - `balance_type` string, nullable: 'debit' | 'credit' | null for non-monetary concepts.
    - `element_type` string: 'concept' | 'abstract' | 'axis' | 'member' | 'hypercube'.
    - `period_type` string, nullable: 'instant' | 'duration' | null (null = derive from classification during validation).
    - `is_monetary` boolean: True for dollar-denominated concepts.
    - `description` string, nullable
    - `code` string, nullable: Optional chart-of-accounts code (e.g. '1000', '4100-02'). Only meaningful for `chart_of_accounts` blocks.
    - `sub_classification` string, nullable
    - `parent_ref` string, nullable: qname of the parent element — either another envelope-local qname or, for `reporting_extension` blocks, a library element qname.
    - `metadata` object
  - `elements_to_update` ElementUpdatePatch[]
    - `qname` string, required: qname identifier of the element to update.
    - `name` string, nullable
    - `description` string, nullable
    - `trait` string, nullable
    - `balance_type` string, nullable
    - `period_type` string, nullable
    - `is_monetary` boolean, nullable
    - `code` string, nullable
    - `parent_ref` string, nullable
    - `metadata` object, nullable
    - `is_active` boolean, nullable: 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_remove` string[]: qnames of elements to remove.
  - `structures_to_add` TaxonomyBlockStructureRequest[]
    - `name` string, required: Envelope-local structure name (unique within envelope).
    - `block_type` 'chart_of_accounts' | 'custom' | 'balance_sheet' | 'income_statement' | 'cash_flow_statement' | 'equity_statement' | 'coa_mapping' | 'schedule' | 'rollforward' | 'reconciliation' | 'policy' | 'metric' | 'regulatory_disclosure', required: 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`.
    - `concept_arrangement` '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', nullable: 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.
    - `description` string, nullable
    - `role_uri` string, nullable
    - `target_framework` string, nullable: `coa_mapping` only: the framework this mapping maps the chart into, e.g. `rs-gaap`. Omitted means the graph's book framework. A chart holds one mapping per framework.
    - `extends_network` string, nullable: `reporting_extension` only: the role URI of the Reporting Style network this structure extends (e.g. `https://robosystems.ai/seattle/cm-roles/roles/rs-gaap-presentation/CashFlow-indirect`). Its arcs then render as rows of that statement for every entity whose Style composes it. `block_type` must be that network's statement type. A row's parent must be on the network, a balance sheet, income statement or cash flow row needs a calculation arc from its section subtotal, an equity movement hangs from the roll-forward's root, and a tenant concept placed as a row must set `parent_ref` to the rs-gaap concept it refines — prefer the rs-gaap concept itself (any library concept may be named, including ones not yet in this graph).
    - `metadata` object
  - `structures_to_update` StructureUpdatePatch[]
    - `structure_id` string, required: Structure id to update.
    - `name` string, nullable
    - `description` string, nullable
    - `role_uri` string, nullable
    - `concept_arrangement` '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', nullable
    - `metadata` object, nullable
  - `structures_to_remove` string[]: Structure ids to remove.
  - `associations_to_add` TaxonomyBlockAssociationRequest[]
    - `structure_ref` string, required: Envelope-local structure name (references a structure declared in the same envelope).
    - `from_ref` string, required: qname of the source element.
    - `to_ref` string, required: qname of the target element.
    - `association_type` 'presentation' | 'calculation' | 'mapping' | 'equivalence' | 'general-special' | 'essence-alias', required: DB `associations.association_type` enum. `presentation` = parent-child hierarchy; `calculation` = summation arc.
    - `order_value` number, nullable
    - `arcrole` string, nullable
    - `weight` number, nullable: Calculation-arc coefficient (+1 / -1 for summation, other values for weighted rollups). Null for non-calculation arcs.
    - `metadata` object
  - `associations_to_remove` string[]: Association ids to remove.
  - `rules_to_add` TaxonomyBlockRuleRequest[]
    - `name` string, required: Rule identifier, unique within envelope.
    - `description` string, nullable
    - `rule_category` 'AutomatedAccountingAndReportingChecks' | 'DisclosureMechanicsRule' | 'FundamentalAccountingConceptRelation' | 'PeerConsistencyRule' | 'PriorPeriodConsistencyRule' | 'ReportLevelModelStructureRule' | 'ReportingSystemSpecificRule' | 'ToDoManualTask' | 'XBRLTechnicalSyntaxRule', required: One of 8 cm:VerificationRule subclasses.
    - `rule_pattern` 'Adjustment' | 'CoExists' | 'Derive' | 'EqualTo' | 'Exists' | 'GreaterThan' | 'GreaterThanOrEqualToZero' | 'LessThan' | 'RollForward' | 'RollUp' | 'SumEquals' | 'Variance', required: 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.
    - `expression` string, required: XPath-flavored predicate body (the rule expression).
    - `variables` object[]: `$Variable` → qname bindings. Each entry is `{'variable_name': str, 'variable_qname': str}`.
    - `severity` 'info' | 'warning' | 'error'
    - `target_structure_ref` string, nullable: Envelope-local structure name this rule targets (for structure-scoped rules). Mutually exclusive with the other target_* fields.
    - `target_element_qname` string, nullable: qname of the element this rule targets. Mutually exclusive with the other target_* fields.
    - `target_taxonomy_self` boolean: True iff the rule targets the envelope's own taxonomy row (`target_kind='taxonomy'`). Mutually exclusive with the other target_* fields.
    - `message` string, nullable
    - `metadata` object
  - `rules_to_remove` string[]: Rule ids to remove.

## Response `200`

Successful Response

- OperationEnvelopeTaxonomyBlockEnvelope
  - `operation` string, required: Kebab-case operation name
  - `operationId` string, required: op_-prefixed ULID for audit and SSE correlation
  - `status` 'completed' | 'pending' | 'failed', required: Operation lifecycle state
  - `result` TaxonomyBlockEnvelope: The Taxonomy Block exchange format. One envelope per taxonomy instance. Carries identity + type, registry-sourced display metadata, the parent taxonomy pointer (for `reporting_extension` blocks), and bundled atoms (elements, structures, associations, rules, verification results).
    - `id` string, required: Taxonomy row id.
    - `name` string, required
    - `taxonomy_type` string, required: Block-type discriminator — 'reporting_standard' | 'reporting_extension' | 'chart_of_accounts' | 'custom_ontology'.
    - `display_name` string, required: Registry-sourced display label.
    - `category` string, required: Registry-sourced sidebar grouping.
    - `parent_taxonomy_id` string, nullable
    - `parent_taxonomy_name` string, nullable
    - `version` string, nullable
    - `standard` string, nullable
    - `namespace_uri` string, nullable
    - `is_locked` boolean
    - `elements` TaxonomyBlockElement[]
      - `id` string, required
      - `qname` string, nullable
      - `name` string, required
      - `trait` string, nullable
      - `balance_type` string, nullable
      - `period_type` string, nullable
      - `element_type` string
      - `is_monetary` boolean
      - `parent_qname` string, nullable
      - `depth` integer, nullable
      - `origin` 'library' | 'tenant', required: Provenance — 'library' if the element's taxonomy is locked (`is_locked=true`), else 'tenant'.
    - `structures` TaxonomyBlockStructure[]
      - `id` string, required
      - `name` string, required
      - `block_type` string, required
      - `description` string, nullable
      - `role_uri` string, nullable
      - `target_framework` string, nullable: `coa_mapping` only: the framework the mapping maps into.
    - `associations` TaxonomyBlockAssociation[]
      - `id` string, required
      - `structure_id` string, required
      - `from_element_qname` string, required
      - `to_element_qname` string, required
      - `association_type` string, required
      - `order_value` number, nullable
      - `arcrole` string, nullable
      - `weight` number, nullable
    - `rules` TaxonomyBlockRule[]
      - `id` string, required
      - `name` string, required
      - `rule_category` string, required
      - `rule_pattern` string, nullable
      - `rule_check_kind` string, nullable
      - `rule_expression` string, required
      - `severity` string
      - `origin` string: 'forked' | 'native' | 'auto' — matches DB CHECK.
      - `target_kind` string, nullable
      - `target_ref` string, nullable: Polymorphic display string — structure_id, element qname, association_id, or taxonomy_id depending on `target_kind`.
    - `verification_results` object[]
    - `element_count` integer
    - `structure_count` integer
    - `association_count` integer
  - `at` string, required: ISO-8601 UTC timestamp
  - `createdBy` string, nullable: User ID that initiated the operation
  - `idempotentReplay` boolean: True when this envelope came from the idempotency cache — the underlying command did not execute again. False on fresh executions.

## Other responses

- `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

---

[API](https://skmtc.dev/robosystems/apis/robosystems-api.md) · [All operations](https://skmtc.dev/robosystems/apis/robosystems-api/llms.txt) · [OpenAPI document](https://skmtc.dev/robosystems/apis/robosystems-api/revisions/e661e2d5ca6a?raw)