> For the complete documentation index, see [llms.txt](https://india-energy-stack.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://india-energy-stack.gitbook.io/docs/schemas/arrfiling.md). # ArrFiling (WIP) *A structured, machine-readable version of the Aggregate Revenue Requirement (ARR) filing a distribution licensee submits to its state electricity regulator.* > ⚠️ **Work in progress — subject to change.** Field names, enums and interpretation are not final. Do not depend on it for production integrations yet. | | | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------ | | **Canonical base** | `https://india-energy-stack.github.io/ies-accelerator/schemas/ArrFiling` | | **Latest version** | **v0.5** | | **Status** | Work in progress (current: **v0.5**) · **Filed by** DISCOMs · **Received by** SERCs / Joint Electricity Regulatory Commissions | | **Category** | Data Exchange payloads | | **Used in** | [DISCOM Regulatory Filing](/docs/draft-work-in-progress/discom-regulatory-filing/discom-regulatory-filing.md) | What this schema is for, in plain language — standards basis, design rationale, open points: [ArrFiling (Schemas Overview)](/docs/schemas-overview/schemas-overview/arr-filing.md). ## Developer resources — v0.5 (current) | Resource | URL | Notes | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | | Field reference (README) | | human-readable field reference for this version | | `attributes.yaml` | | OpenAPI 3.1 source of truth | | `schema.json` | | compiled JSON Schema (Draft 2020-12) — validate against this | | `context.jsonld` | | JSON-LD context for semantic resolution | | `vocab.jsonld` | | RDF vocabulary with standards alignments | | `examples/` | [https://github.com/India-Energy-Stack/ies-accelerator/tree/main/schemas/ArrFiling/v0.5/examples](https://github.com/India-Energy-Stack/ies-accelerator/tree/main/schemas/ArrFiling/v0.5/examples/README.md) | worked payloads | ## Field reference — v0.5 (current) *A field name in **bold** with a trailing **\*** is required; all others are optional. **Type** shows units for QuantitativeValue models. Descriptions are simplified to the plain meaning of each field — the per-version pages (see **Versions** below) carry the full text, standards basis and notes.* **ArrFiling** | Field | Type | Description | | ----------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **`objectType`** \* | `ARR_FILING` | — | | `id` | text | Unique identifier for this filing. | | **`filingId`** \* | text | Regulatory filing reference number. | | `filingDate` | date | — | | `filingType` | `MYT` / `ANNUAL` / `TRUE_UP` / `REVISED` | MYT - Multi-Year Tariff control period filing (multiple years, mix of actual/proposed) ANNUAL - single year or historical year-by-year approved data TRUE\_UP - reconciliation of actuals vs previously approved amounts REVISED - amended filing with corrections | | **`licensee`** \* | text | Full name of the distribution licensee. | | `licenseeCode` | text | Short code for the licensee. | | `stateProvince` | text | — | | **`regulatoryCommission`** \* | text | SERC or Joint ERC that receives the filing. | | `controlPeriodStart` | text | Start fiscal year of MYT control period (only for MYT filings). | | `controlPeriodEnd` | text | End fiscal year of MYT control period. | | **`currency`** \* | `INR` | — | | **`unitScale`** \* | `CRORE` / `LAKH` / `ABSOLUTE` | Scale of all amounts in the filing. | | `status` | `DRAFT` / `SUBMITTED` / `UNDER_REVIEW` / `APPROVED` / `REJECTED` | — | | `formReference` | text | Regulatory form identifier. | | `notes` | list of text | Footnotes, regulatory order references, and explanatory notes. | | **`fiscalYears`** \* | list of ArrFiscalYear | — | **ArrFiscalYear** | Field | Type | Description | | -------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`fiscalYear`** \* | text | Fiscal year label. | | `yearType` | `BASE_YEAR` / `CONTROL_PERIOD` / `HISTORICAL` | BASE\_YEAR - reference year in an MYT filing (typically the year before the control period) CONTROL\_PERIOD - a year within the MYT control period being filed for HISTORICAL - a past year with finalized data (used in annual/historical filings) | | **`amountBasis`** \* | `AUDITED` / `APPROVED` / `PROPOSED` / `TRUED_UP` / `NOT_FILED` | AUDITED - actual costs verified by auditors APPROVED - amounts approved by the SERC in a tariff order PROPOSED - amounts requested by the DISCOM, pending SERC approval TRUED\_UP - reconciled amounts after comparing actuals to approved NOT\_FILED - placeholder year in a control period, no data yet | | **`lineItems`** \* | list of ArrLineItem | — | **ArrLineItem** | Field | Type | Description | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`lineItemId`** \* | text | Stable identifier for this line item across years. | | `serialNumber` | integer | Display order as shown in the regulatory form. | | **`category`** \* | `VARIABLE` / `FIXED` / `INCOME` / `SUB_TOTAL` / `ARR` / `ADJUSTMENT` | VARIABLE - costs varying with energy volume (power purchase) FIXED - costs independent of volume (O\&M, depreciation, interest, return) INCOME - revenue credits that reduce the ARR (negative amounts) SUB\_TOTAL - computed aggregation of other line items ARR - the final net/aggregate revenue requirement ADJUSTMENT - true-up corrections, pass-throughs, FPPCA adjustments | | `subCategory` | `POWER_PURCHASE` / `NETWORK_COST` / `O_AND_M` / `DEPRECIATION` / `INTEREST` / `RETURN_ON_EQUITY` / `PROVISIONAL` / `OTHER` / `NON_TARIFF_INCOME` / `REVENUE_CREDIT` / `TOTAL` / `NET_ARR` | Functional sub-classification for analysis and comparison across DISCOMs. | | **`head`** \* | text | Short heading as used in the regulatory form. | | `particulars` | text | Detailed description or the "Particulars" column value. | | **`amount`** \* | number / null | Amount in the filing's currency and unitScale. | | `formReference` | text | Reference to the supporting sub-form or schedule. | | `componentOf` | text | lineItemId of the parent subtotal this item contributes to. | | `formula` | text | Human-readable computation formula expressed as references to other lineItemIds. | ## Versions Every published version stays reachable at its canonical URL — clients pin a version explicitly. Click a version for its full field reference. | Version | Status | Notes | Files | | --------------------------------------- | ----------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [v0.5](/docs/schemas/arrfiling/v0.5.md) | **Current** | Three relational models: ArrFiling, ArrFiscalYear, ArrLineItem | [schema.json](https://india-energy-stack.github.io/ies-accelerator/schemas/ArrFiling/v0.5/schema.json) · [attributes.yaml](https://india-energy-stack.github.io/ies-accelerator/schemas/ArrFiling/v0.5/attributes.yaml) · [examples](https://github.com/India-Energy-Stack/ies-accelerator/tree/main/schemas/ArrFiling/v0.5/examples/README.md) |