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

# Create Taxonomy Block

`POST /extensions/roboledger/{graph_id}/operations/create-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/create-taxonomy-block`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

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. A `reporting_extension` structure with `extends_network` adds rows to the entity's balance sheet, income statement, cash flow or equity statement: its arcs layer onto that Reporting Style network, anchored and checked when authored (refused with a reason, 422). Prefer an rs-gaap concept for a row — any library concept may be named, including ones not yet in this graph — and give a tenant concept a `parent_ref` to the rs-gaap concept it refines. 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.

## Path parameters

- `graph_id` string, required

## Headers

- `Idempotency-Key` string, nullable

## Request body

- CreateTaxonomyBlockRequest: Request body for the `create-taxonomy-block` operation. One envelope per taxonomy instance. `taxonomy_type` discriminates which block-type handler the command dispatcher routes to. `parent_taxonomy_id` is required for `reporting_extension` (which extends a library taxonomy) and ignored otherwise. The library path (seeding `reporting_standard` rows) does NOT flow through this envelope; library content is not tenant-writable here.
  - `name` string, required: Taxonomy display name.
  - `taxonomy_type` 'reporting_standard' | 'reporting_extension' | 'custom_ontology' | 'chart_of_accounts' | 'schedule', required: Block-type discriminator. `chart_of_accounts` and `custom_ontology` construct from scratch; `reporting_extension` extends an existing library `reporting_standard`.
  - `parent_taxonomy_id` string, nullable: Required when `taxonomy_type == 'reporting_extension'` — the id of the library `reporting_standard` being extended.
  - `version` string, nullable
  - `description` string, nullable
  - `standard` string, nullable
  - `namespace_uri` string, nullable
  - `elements` 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
  - `structures` 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
  - `associations` 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
  - `rules` 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
  - `metadata` object

## 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/28ffd375c457?raw)