Specification

The canonical SFRS model is now v2: a fact-centric filing format designed to preserve XBRL semantics in a JSON-native structure.

This is the model that new import, validation, export, and package generation work targets.

Canonical Shape

An SFRSV2Filing contains:

{
  "document": {},
  "entity": {},
  "taxonomyRefs": [],
  "contexts": [],
  "units": [],
  "facts": [],
  "footnotes": [],
  "relationships": [],
  "extensions": [],
  "views": {}
}

Design Principles

Facts Are The Canonical Center

Statements such as a balance sheet or income statement are not the canonical storage model in v2.

The canonical record is a set of facts with:

a concept
a context
a unit
a value
optional decimals or precision
optional dimensional qualifiers

Contexts And Units Are First-Class

Unlike the older flattened model, canonical v2 explicitly preserves:

instant and duration periods
entity identifiers attached to contexts
explicit dimensions
typed dimensions
reusable units

That makes round-trip conversion to and from XBRL materially more realistic.

Relationships Stay In The Filing

Canonical v2 can preserve relationship structures such as:

presentation
calculation
definition
footnote

The goal is not to make JSON mimic XML syntax. The goal is to keep the semantics required for interoperable reporting.

Core Objects

`document`

Metadata about the filing package itself.

Important fields:

version Currently 2.0.0
documentType Currently filing
profile For example sec-us-gaap-annual
jurisdiction For example US-SEC
sourceFormat For example xbrl, ixbrl, or sfrs-json

`entity`

The reporting entity with one or more identifiers.

Identifiers are modeled as { scheme, value } pairs rather than fixed top-level slots.

Supported schemes in the current type surface:

lei
cik
isin
ticker
local

`taxonomyRefs`

The taxonomies the filing claims against.

Each reference can include:

name
version
namespace
entryPoint

`contexts`

A context binds facts to an entity/time slice and optionally dimensions.

Each context can contain:

an id
an entityIdentifier
a period
optional dimensions

`units`

Units are reusable and referenced by facts.

Examples:

iso4217:USD
xbrli:shares
composed measures for more complex cases

`facts`

Each fact is an object with a stable identity.

Typical fields:

id
concept
contextRef
unitRef
value
decimals
precision
nil
language

`footnotes`

Footnotes are linked explicitly to facts using factRefs.

`relationships`

Relationships carry semantic edges between concepts, facts, or footnotes.

Key fields include:

arcrole
from
to
weight
order

Example Canonical Filing

{
  "document": {
    "version": "2.0.0",
    "documentType": "filing",
    "profile": "sec-us-gaap-annual",
    "jurisdiction": "US-SEC",
    "sourceFormat": "sfrs-json",
    "createdAt": "2026-03-10T00:00:00Z"
  },
  "entity": {
    "name": "Acme Corporation",
    "jurisdiction": "US-DE",
    "identifiers": [
      { "scheme": "cik", "value": "0001234567" }
    ]
  },
  "taxonomyRefs": [
    { "name": "us-gaap", "version": "2025" }
  ],
  "contexts": [
    {
      "id": "c_duration_2024",
      "entityIdentifier": "0001234567",
      "period": {
        "startDate": "2024-01-01",
        "endDate": "2024-12-31"
      }
    }
  ],
  "units": [
    { "id": "u_usd", "measures": ["iso4217:USD"] }
  ],
  "facts": [
    {
      "id": "f_revenue",
      "concept": "us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax",
      "contextRef": "c_duration_2024",
      "unitRef": "u_usd",
      "value": 25000000,
      "decimals": -3
    }
  ]
}

Profiles

Canonical v2 is profile-driven. The current prerelease includes:

Profile	Jurisdiction	Taxonomy	Status
`sec-us-gaap-annual`	`US-SEC`	`us-gaap` 2025	prerelease
`ifrs-esef-annual`	`EU-ESEF`	`ifrs` 2025	prerelease

Profiles define things such as:

required identifier schemes
required facts
package output paths
expected capability surface

Legacy v1

The older statement-shaped model still exists as a compatibility surface in the repo and API, but it is no longer the canonical design center.

Use it only when maintaining older integrations.

Current Limits

Canonical v2 is still prerelease.

What it does well now:

preserve contexts, units, facts, dimensions, footnotes, and core relationships
validate against first profile layers
export to XBRL and iXBRL
build package manifests with deterministic file metadata

What it does not claim yet:

regulator-ready submission parity
broad real-filing compatibility across a public corpus
full jurisdiction coverage beyond the registered profiles

Specification

On this page