How to get fully resolved flat facts and structured report output from Arelle?

[Achille Tuglo]

Hi Arelle team and community,

  I'm working on parsing XBRL instance documents and I'm currently using Arelle to extract data. The output I'm getting (facts.json via --factListCols and factTable.json via --factTable) doesn't quite match the formats
  I need for my application.

  Current Arelle output

  facts.json gives me nested tuples like:
  [
    "item",
    { "name": "ex-data:SomeMonetaryValue" },
    {
      "label": "SomeMonetaryValue",
      "contextRef": "ctx_duration_01",
      "lang": "en",
      "value": "125000"
    }
  ]

  factTable.json gives me the presentation tree with empty value placeholders:
  ["facts", { "concept": "ex-data:SomeConceptName" }, {}]

  What I need

  Output 1 — Flat facts with fully resolved contexts:

  Each fact as a self-contained object with context dimensions, period, entity, and unit resolved inline:

  {
    "concept": "ex-data:SomeMonetaryValue",
    "localName": "SomeMonetaryValue",
    "label": "Some monetary value",
    "value": "125000",
    "numericValue": 125000,
    "isNumeric": true,
    "unit": "EUR",
    "decimals": "INF",
    "contextId": "ctx_instant_01",
    "entity": "12345678",
    "periodType": "instant",
    "periodDate": "2024-01-15",
    "dimensions": []
  }

  For facts with dimensional contexts:
  {
    "concept": "ex-data:AnnualCashflow",
    "value": "18500.75",
    "numericValue": 18500.75,
    "unit": "EUR",
    "contextId": "ctx_method_year",
    "periodType": "instant",
    "periodDate": "2024-01-15",
    "dimensions": [
      { "type": "typed", "axis": "ex-dim:MethodAxis", "value": "SomeMethod" },
      { "type": "typed", "axis": "ex-dim:YearAxis", "value": "1" }
    ]
  }

  For text facts with explicit dimension members:
  {
    "concept": "ex-data:OrganisationName",
    "localName": "OrganisationName",
    "label": "Organisation name",
    "value": "Example Corp B.V.",
    "numericValue": null,
    "isNumeric": false,
    "unit": null,
    "contextId": "ctx_duration_party",
    "entity": "12345678",
    "periodType": "duration",
    "periodStart": "2024-01-01",
    "periodEnd": "2024-12-31",
    "dimensions": [
      { "type": "explicit", "axis": "ex-dim:PartyAxis", "member": "ex-dom:ClientMember" }
    ]
  }

  Output 2 — Structured report grouped by business domain:

  Facts organized into a business-domain model, with sections grouping related facts together (e.g., entity information, numeric results, dimensional tables with one row per member, narrative text fields, etc.), rather
  than a flat list or a raw presentation tree.

  My questions

1. Is there an existing Arelle plugin, command-line option, or configuration that can produce fully resolved flat facts (with dimensions, units, and period inline)?
2. Is there a way to combine the factTable presentation tree with actual fact values to produce a filled-in structured output?
3. Would writing a custom Arelle plugin be the recommended approach, or would it be simpler to parse the XBRL instance directly for this use case?
4. Are there any community plugins or examples for this kind of transformation?

  Context

  - XBRL instance files with ~50-100 contexts, ~500-800 facts, using typed and explicit dimensions
  - Both instant and duration periods
  - Units include monetary (EUR), area (sqm), and pure (ratios/percentages)
  - Target platform: .NET (C#), so I'm evaluating whether to use Arelle web server as a preprocessor or build a custom parser

  Thanks in advance for any suggestions!

[Austin Matherne]

Hi,

The custom JSON format you've described (flat facts with mix of fully resolved instance and taxonomy data: contexts, labels, dimensions, etc.) isn't something Arelle produces out of the box. Producing output in that specific shape would require writing custom code, either by creating an Arelle plugin or by using Arelle as a Python library. That said, you may want to look at the Save Loadable OIM plugin, which can convert non-JSON XBRL reports into the standard OIM JSON report format. It won't exactly match the format you've outlined (it outputs instance level data only and context details not their IDs, so it won't include taxonomy labels, for example), but it does produce a standardized, flat JSON representation of facts. Depending on your needs, it could serve as a useful starting point or even get you most of the way there, with some post-processing on your end to enrich with labels or reorganize into your business domain groupings. Typically folks who require specific output formats use Arelle to produce multiple outputs (for example, one for facts and another for labels) and then join them using a post-processing step within their own code to meet their needs.

Kind regards,

Austin Matherne

[Achille Tuglo]

 Hi Austin,
                                                                                                                                                   
  Thank you for the detailed explanation and for pointing us to the Save Loadable OIM plugin.

  In the meantime, we've gone ahead and built our own native .NET parser that reads the XBRL instance XML directly and produces the JSON formats we
   need. We're now only using Arelle for XBRL validation (schema + formula rules), which works great.

  Thanks again for the guidance, it helped confirm we were on the right track.

  Kind regards,
  Achille