Information Block Reference

The reference for the Information Block: every envelope field, the mechanics each block type carries, which operations each type supports, the rule vocabulary and what evaluates today, and the view projections. For the concepts behind it, read Information Blocks first.

Names below are the REST and MCP spelling (snake_case). GraphQL serves the same fields in camelCase (block_type → blockType, fact_set → factSet). The live OpenAPI spec at robosystems.ai/docs/api is the source of truth for exact types.

Table of Contents

• The Envelope
• Atom Shapes
• FactSets and Provenance
• Information Model Vocabulary
• The Registry
• Per-Type Mechanics
• Rule Patterns
• View Projection Status
• Reads
• Gotchas
• Related Documentation
• Support

The Envelope

InformationBlockEnvelope is the one wire shape for every block type. It is returned by create-information-block and update-information-block (inside the OperationEnvelope's result), by informationBlock / informationBlocks in GraphQL, by each item of reportPackage, and by the MCP tools get-information-block and list-information-blocks.

Atom Shapes

Element (elements[]): id, qname (null for tenant chart-of-accounts accounts), name, code, element_type, is_abstract, is_monetary, balance_type (debit / credit), period_type (instant / duration), item_type (the value-domain format family), documentation.

Connection (connections[]): id, from_element_id, to_element_id, association_type (presentation, calculation, mapping, equivalence, general-special, essence-alias), arcrole, order_value, weight, and classifications[] (each id, category, identifier, is_primary, confidence, source).

Fact (facts[]):

Rule (rules[]): id, rule_category, rule_pattern or rule_check_kind (exactly one is set), rule_expression, rule_target (target_kind: structure / element / association / taxonomy, plus target_ref_id), rule_variables[] (variable_name, variable_qname, variable_element_id), rule_message, rule_severity (info / warning / error), rule_origin. See Rule Patterns.

Verification result (verification_results[]): id, rule_id, structure_id, fact_set_id, status (pass / fail / error / skipped), message, period_start, period_end, evaluated_at.

Verification summary: total, passed, failed, errored, skipped, and by_category[] with the same counts per category.

FactSets and Provenance

fact_set carries id (fs_…), structure_id, period_start, period_end, factset_type, entity_id, report_id, scenario_id, and provenance.

report_id points at the owning Report when the set belongs to a package. scenario_id is null for actuals and holds a forecast block's id for that scenario's sets.

provenance is a typed descriptor discriminated on origin:

Information Model Vocabulary

concept_arrangement names how the block's concepts relate:

• Canonical: set, roll_up, roll_forward, roll_forward_info, adjustment, variance, arithmetic, text_block
• Text-block and detail levels: level1_textblock, level2_textblock, level3_textblock, level4_detail, table_equivalent_textblock
• Pseudo-patterns: grid, compound_fact

A disclosure whose arrangement is one of the text-block values (text_block, level1_textblock through level3_textblock, table_equivalent_textblock) holds narrative facts and renders as text rows; level4_detail is a numeric detail table.

member_arrangement names how dimension members aggregate, from none to full: is_a, whole_part, nested_whole_part, two_dimension_aggregation, complex_aggregating_whole_part. Null for blocks without a hypercube.

The Registry

One registry maps each block_type to its construction mode, default arrangements, mechanics class, and handlers. create-information-block, update-information-block, and delete-information-block take a body of { "block_type": …, "payload": … } and dispatch through it.

A 501 carries a message naming the right path. An unknown block_type is a 422.

The statement Structures are seeded from the taxonomy library and cannot be deleted per tenant; to remove their facts, delete the originating Report. On the library graph, only the statement types are listed; schedules, rollforwards, forecasts, disclosures, and metrics exist only on tenant graphs.

Per-Type Mechanics

Schedule

A closing-entry generator: one fact per element per month across a window, and a draft closing entry each month from its entry template.

create-information-block payload (block_type: "schedule"):

entry_template: debit_element_id, credit_element_id (chart-of-accounts ids, not qnames; one pair per schedule, so model a multi-account entry as several schedules), entry_type (standard, adjusting, closing (default), reversing), memo_template ({structure_name} is replaced), auto_reverse (post a reversing entry on the first day of the next period).

schedule_metadata:

ScheduleMechanics on the envelope: kind: "closing_entry_generator", entry_template, schedule_metadata, and periods_with_entries (months that already have a closing entry, computed at read time).

Update takes structure_id plus any of name, entry_template, schedule_metadata; delete takes structure_id. Two further operations change a live schedule: terminate-schedule (end it early with a new_end_date and a reason; removes the facts and voids the obligations past that date) and rebuild-schedule (re-run the generator in place from the stored definition, keeping the structure id: the old facts, rules, and pending obligations are replaced, and the historical/in-scope split is re-derived from the current close state). How schedule drafts post is in Period Close.

Rollforward

Decomposes one balance-sheet account's period change across declared flow concepts (cash-flow and equity-statement lines), evaluated against ledger line items when the block is read.

Payload: name, bs_source_qname, default_change_tag_qname (the flow concept that receives any residual), attribution_filters[], validation_mode, taxonomy_id. Each filter has a target_qname (the flow concept it produces) and a predicate of kind: "line_item_metadata_field" whose values are flow-concept qnames; a line item matches when its flow tag is one of them.

RollforwardMechanics: kind: "rollforward", bs_source_element_id, bs_source_qname, default_change_tag_element_id, default_change_tag_qname, attribution_filters, validation_mode:

• residual_as_default (default): the unattributed remainder becomes a fact on the default change tag
• strict: a remainder is an error
• warn_only: the imbalance is logged and allowed

Forecast

An authored scenario. The block is the scenario: its id is the scenario_id every forecast FactSet carries. compute-forecast walks the months forward from the last closed actuals and writes them into the existing statement and metric blocks, stamped with that scenario.

ForecastMechanics: kind: "forecast", scenario_kind (budget / forecast / projection), horizon_months (1 to 36), base_period (YYYY-MM), base_anchor (seam re-anchors on the newest closed month; fixed pins the walk to base_period), levers[], line_assertions[], line_growth[], and computed_months. Authoring and computing scenarios is covered in Forecasting and Metrics.

Statement family

balance_sheet, income_statement, cash_flow_statement, equity_statement, comprehensive_income. StatementMechanics: kind: "statement_renderer", template_id (reserved, not yet used), rollup_root_element_ids (the roll-up roots, such as the Assets total), period_comparisons (1 to 4 columns). Envelopes carry view.rendering. Rendering is covered in Reporting and Rendering.

Disclosure

regulatory_disclosure: a note beyond the statements (inventory by category, PP&E by class, debt maturities). The structure is vocabulary, authored with create-taxonomy-block; its numeric facts arrive when a Report reaches its mapped concepts, and its narrative facts are bound from a document with bind-text-block. Uses StatementMechanics. A numeric disclosure renders like a statement; a text-block disclosure renders one row per narrative fact.

Metric

A standing per-period series: ratios, covenant tests, KPIs. The structure (elements, presentation arcs, Derive rules) is authored with create-taxonomy-block. Facts are written by compute-metrics, which evaluates the Derive rules against a period's closed statements, or by assert-metrics, which records externally observed values. Envelopes carry view.rendering and view.chart.

MetricMechanics (kind: "metric", source_block_ids, derivation_type, expression, unit) is declared for a block-level derivation expression that is not evaluated yet; the computation runs through the Derive rules. See Forecasting and Metrics.

Rule Patterns

A rule has either a rule_pattern (arithmetic over fact values) or a rule_check_kind (a structural check over the model), never both.

A rule whose variables have no bound fact reports skipped rather than failing. The default tolerance can be overridden per rule.

rule_check_kind values are LeafHasClassification, LibraryOriginImmutability, NoCycles, NoOrphanArcs, ParentBeforeChild, and UniqueQNameInTaxonomy. They are emitted automatically when a taxonomy block is created, and the same invariants are enforced when the taxonomy block is written; evaluate-rules does not evaluate them.

rule_category: AutomatedAccountingAndReportingChecks, DisclosureMechanicsRule, FundamentalAccountingConceptRelation, PeerConsistencyRule, PriorPeriodConsistencyRule, ReportLevelModelStructureRule, ReportingSystemSpecificRule, ToDoManualTask, XBRLTechnicalSyntaxRule.

rule_origin: native (authored in a seed or by a tenant), forked (taken from an upstream artifact), auto (emitted by the platform for a taxonomy block).

evaluate-rules takes structure_id and optionally fact_set_id, period_start, period_end. It returns structure_id, results[], and summary keyed pass / fail / error / skipped.

View Projection Status

The rendering payload (rows, periods, validation, unmapped_count) is described in Reporting and Rendering § The View Projections.

Reads

GraphQL at POST /extensions/{graph_id}/graphql:

• informationBlock(id, scenarioId, series, seriesHistory, seriesForecast): one envelope. scenarioId selects a forecast scenario (omit for actuals). series: true renders a statement block as its whole monthly series; non-statement types ignore it. seriesHistory / seriesForecast cap the series at the last N actual and first N forecast columns.
• informationBlocks(blockType, category, limit, offset, scenarioId): a list; filters combine as AND; limit defaults to 50.
• reportPackage(reportId): a saved Report's metadata plus items[], each with fact_set_id, structure_id, display_order, and the pinned block envelope.

MCP: get-information-block (id, scenario_id, series, series_history, series_forecast) and list-information-blocks (block_type, category, limit, offset, include_atoms, scenario_id).

Gotchas

• Cents in, dollars out. Request amounts (monthly_amount, original_amount, residual_value, periodic_amounts) are integer cents. Fact values on the envelope are in the unit, so a monthly_amount of 83333 reads back as 833.33.
• Statements are rendered, not created. create-information-block with a statement, disclosure, or metric type returns 501. Author a schedule, rollforward, or forecast; produce statements with create-report.
• Element ids, not qnames. Schedule templates take chart-of-accounts element ids. A qname such as us-gaap:Depreciation does not resolve there.
• periodic_amounts is strict. One entry per month in the window, none negative, summing exactly to original_amount; anything else is rejected at create.
• The graph is the URL. informationBlock and informationBlocks take no graphId argument.
• fact_set: null and facts: [] are normal for a statement Structure no report or close has instantiated yet.
• verification_summary is null until the rules run. Call evaluate-rules, or close the period.
• disclosure_id is derived. It is present only when a Disclosure mapping exists; tenant-authored schedules carry null.
• The information-block view operation is a different call. It reads one section of a filing or report whole; see Information Blocks § Live and Pinned Reads.

Related Documentation

Wiki Guides:

• Information Blocks - The concepts: atoms and molecules, FactSets, rules, views
• Reporting and Rendering - The rendering payload and statement production
• Forecasting and Metrics - Forecast scenarios and metric blocks
• Period Close - Schedule drafts and the close-time rule run
• Taxonomy and Frameworks - Taxonomy blocks, which author disclosure and metric structures

Codebase Documentation:

• API reference - Full request and response schemas
• API Models - The Pydantic models behind the envelope

Support

• Issues
• Wiki
• Projects
• Discussions