> 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) | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://india-energy-stack.gitbook.io/docs/schemas/arrfiling.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.