Skip to content
Documentation/Issuer guides

Upload operating data

Prepare JSON with a matching plant, calendar periods, and registered metrics.

On this page

Currently accepted file format

The ingest endpoint accepts .json files up to 1,000,000 bytes. Select plantId and recordType in the dashboard; do not add a header or salts to the upload file.

The example uses a fictional plant. Replace plantCode with your real plant code and use metrics registered for its asset category.

JSON
{
  "schemaVersion": "2.0.0",
  "plantCode": "SOLAR-DEMO-01",
  "periods": [
    {
      "period": "2026-08",
      "metrics": {
        "inverter_yield_kwh": "24000",
        "ongrid_export_kwh": "22000"
      }
    }
  ]
}

Validation rules

  1. Use YYYY-MM periods, 1–12 periods per record, and no repeated period within a file.
  2. Prefer decimal strings for metrics with a decimal point; no exponents or thousands separators.
  3. Metric keys must be registered and satisfy precision and range constraints.
  4. Do not repeat JSON keys or add fields outside the schema.

Current month and provisional data

In ledger v3 mode, a record containing the current month at ingestion is provisional. It can be committed and verified off-chain but cannot be anchored.

Provisional status is fixed by ingestedAt and timezone. Ingest again after the month closes to create a new record; the old record does not become final merely with time.

Sources reviewed in the monorepo

Based on source code; live availability is stated separately.

  • apps/api/src/modules/shadow-ledger/api/shadow-ledger.controller.ts
  • packages/hashing/src/schema-v2.ts
  • docs/specs/ucy-hash-v2.md