Getting Started

Start with the canonical SFRS v2 filing model, validate it, and convert it to XBRL or iXBRL.

SFRS now has two model surfaces:

Canonical v2 The fact-centric model for new work.
Legacy v1 The older statement-shaped model kept for compatibility.

If you are starting fresh, build against canonical v2.

Install

npm install @sureshake/sfrs-standard @sureshake/sfrs-validator @sureshake/sfrs-converter

Minimal Canonical Filing

import type { SFRSV2Filing } from '@sureshake/sfrs-standard';

const filing: SFRSV2Filing = {
  document: {
    version: '2.0.0',
    documentType: 'filing',
    profile: 'sec-us-gaap-annual',
    jurisdiction: 'US-SEC',
    sourceFormat: 'sfrs-json',
    createdAt: new Date().toISOString(),
    generatedBy: 'example-app',
  },
  entity: {
    name: 'Acme Corporation',
    jurisdiction: 'US-DE',
    identifiers: [
      { scheme: 'cik', value: '0001234567' },
      { scheme: 'lei', value: '5493001KJTIIGC8Y1R12' },
    ],
  },
  taxonomyRefs: [
    {
      name: 'us-gaap',
      version: '2025',
      namespace: 'http://fasb.org/us-gaap/2025',
    },
  ],
  contexts: [
    {
      id: 'c_instant_2024_12_31',
      entityIdentifier: '0001234567',
      period: { instant: '2024-12-31' },
    },
    {
      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_assets',
      concept: 'us-gaap:Assets',
      contextRef: 'c_instant_2024_12_31',
      unitRef: 'u_usd',
      value: 9500000,
      decimals: -3,
    },
    {
      id: 'f_liabilities',
      concept: 'us-gaap:Liabilities',
      contextRef: 'c_instant_2024_12_31',
      unitRef: 'u_usd',
      value: 3100000,
      decimals: -3,
    },
    {
      id: 'f_equity',
      concept: 'us-gaap:StockholdersEquity',
      contextRef: 'c_instant_2024_12_31',
      unitRef: 'u_usd',
      value: 6400000,
      decimals: -3,
    },
  ],
};

Validate Canonical v2

import { validateCanonicalFiling } from '@sureshake/sfrs-validator';

const result = validateCanonicalFiling(filing);

console.log(result.valid);
console.log(result.summary);
console.log(result.errors);

Canonical validation is profile-aware for the currently supported prerelease profiles:

sec-us-gaap-annual
ifrs-esef-annual

Convert To XBRL And iXBRL

import {
  canonicalFilingToXBRL,
  canonicalFilingToIXBRL,
} from '@sureshake/sfrs-converter';

const xbrl = canonicalFilingToXBRL(filing);
const ixbrl = canonicalFilingToIXBRL(filing);

console.log(xbrl.filename, xbrl.mimeType);
console.log(ixbrl.filename, ixbrl.mimeType);

Build A Filing Package

import { createCanonicalFilingPackage } from '@sureshake/sfrs-converter';

const pkg = createCanonicalFilingPackage(filing);

console.log(pkg.manifest.primaryArtifacts);
console.log(Object.keys(pkg.files));

Parse XBRL Into Canonical v2

import { parseXBRLCanonical } from '@sureshake/sfrs-converter';

const parsed = parseXBRLCanonical(xbrlXmlString);

if (!parsed.success || !parsed.filing) {
  console.error(parsed.errors);
} else {
  console.log(parsed.filing.document.profile);
  console.log(parsed.filing.facts.length);
}

Run The Demo Flow

The quickest end-to-end walkthrough is the corpus-backed demo script:

pnpm --filter @sureshake/sfrs-standard build
pnpm --filter @sureshake/sfrs-validator build
pnpm --filter @sureshake/sfrs-converter build
pnpm demo:canonical-v2 -- --fixture sec-basic-footnote

That flow is documented in the Demo Kit.

API Path

If you want to work through HTTP instead of packages, start with:

POST /api/v1/validate
POST /api/v1/convert/from-xbrl with targetModel: "v2"
POST /api/v1/convert/to-xbrl
POST /api/v1/convert/to-ixbrl
POST /api/v1/package

See the API Reference.

Next Steps

Read the Specification for the canonical v2 model
Use the Schema Reference for field-level guidance
Review Validation Rules for canonical/profile checks
Use Examples for downloadable v1 and v2 fixtures

Getting Started

On this page