{
  "anchors": [
    {
      "about": "2-letter state/jurisdiction code (PD-003).",
      "format": "usps_state",
      "kind": "geography",
      "name": "state",
      "scope": "universal"
    },
    {
      "about": "EIA plant code; joins within the EIA family.",
      "format": "positive_int",
      "kind": "entity",
      "name": "eia_plant_id",
      "scope": "opportunistic"
    },
    {
      "about": "EIA generator id, unique within a plant.",
      "format": "short_code",
      "kind": "entity",
      "name": "generator_id",
      "scope": "opportunistic"
    },
    {
      "about": "EIA-reported BA code; source-reported, not a validated footprint (PD-002/009).",
      "format": "ba_code",
      "kind": "entity",
      "name": "balancing_authority_code",
      "scope": "opportunistic"
    }
  ],
  "capability": "power.asset_ownership",
  "codebooks": {},
  "data_point": {
    "does_not_answer": [
      "normalized or matched corporate identity across owner-name variants",
      "beneficial ownership, parent-company control, voting rights, or economic control",
      "market value, acquisition cost, or probability of an ownership change",
      "operator ownership inferred from a later or earlier vintage"
    ],
    "grain": "plant_generator_owner_annual",
    "id": "power.asset_ownership",
    "product_spec": "blocks/power_asset_ownership/card.md",
    "represented_fact": "Annual EIA-860 reports the raw ownership shares and owner identities for generators that are jointly owned or wholly owned by an entity other than the operator. A generator absent from the Owner schedule is wholly owned by its operator, as EIA explicitly documents; the block carries same-vintage generator/operator context so consumers can apply that default without treating absence as unknown ownership.",
    "source_basis": [
      "energy.eia.eia860_owner"
    ],
    "source_decisions": [
      "docs/sources/energy/eia/eia860_owner/source-decision.md"
    ]
  },
  "input": {
    "controls": [
      "include_records",
      "include_evidence",
      "limit",
      "order_by",
      "top_n",
      "order"
    ],
    "date_range_params": [],
    "date_ranges": [],
    "filters": [
      "as_of",
      "vintage_year",
      "eia_plant_id",
      "generator_id",
      "owner_name",
      "owner_state",
      "state",
      "balancing_authority_code"
    ],
    "group_by": [
      "vintage_year",
      "eia_plant_id",
      "generator_id",
      "owner_name",
      "owner_state",
      "state",
      "balancing_authority_code"
    ],
    "ranking": {
      "no_ranking": "Omit order_by and top_n to return all groups in group-key order.",
      "order": {
        "default": "desc",
        "valid_values": [
          "desc",
          "asc"
        ]
      },
      "order_by": {
        "accepts": "one of output.metrics",
        "note": "Ranks the groups by a metric (a measure). Not a group_by dimension \u2014 rows already come back grouped by each group_by field.",
        "requires": [
          "group_by"
        ],
        "valid_values": [
          "percent_owned",
          "source_record_count",
          "distinct_generator_count",
          "distinct_plant_count"
        ]
      },
      "top_n": {
        "note": "Keeps the top N groups by order_by; the rest fold into one (other) remainder (additive metrics sum into it, non-additive ones are nulled) so the result still reconciles to summary.totals.",
        "requires": [
          "group_by",
          "order_by"
        ],
        "type": "positive integer"
      }
    }
  },
  "output": {
    "aggregate_citation_fields": [
      "source_id",
      "publisher",
      "source_url",
      "source_file",
      "source_member",
      "raw_file_sha256",
      "as_of",
      "source_rows_count",
      "source_rows_sample",
      "verify",
      "lineage_filter"
    ],
    "citation_fields": [
      "source_id",
      "source_url",
      "source_file",
      "source_member",
      "sheet",
      "source_row",
      "source_col",
      "raw_file_sha256",
      "as_of"
    ],
    "detail_fields": [
      "source_id",
      "record_kind",
      "sheet_name",
      "vintage_year",
      "source_record_key",
      "source_row_number",
      "eia_plant_id",
      "plant_name",
      "generator_id",
      "operator_id",
      "operator_name",
      "owner_id",
      "owner_name",
      "owner_city",
      "owner_state",
      "percent_owned",
      "percent_owned_unit",
      "state",
      "balancing_authority_code",
      "as_of",
      "raw_file_sha256",
      "citation",
      "balancing_authority_citation"
    ],
    "metric_groups": {
      "entities": [
        "distinct_generator_count",
        "distinct_plant_count"
      ],
      "ownership": [
        "percent_owned"
      ],
      "records": [
        "source_record_count"
      ]
    },
    "metric_metadata": {
      "distinct_generator_count": {
        "additive_across_groups": false,
        "aggregation": "count_distinct",
        "authoritative_total_path": "summary.totals.distinct_generator_count",
        "category": "entities",
        "definition": "Distinct EIA plant ID plus generator ID keys represented by Owner rows.",
        "display_name": "Distinct generator count",
        "display_precision": "Integer.",
        "grain": "result scope",
        "null_handling": "Always an integer count.",
        "rollup_behavior": "distinct_entity_count_not_additive",
        "row_metric_path": "rows[].metrics.distinct_generator_count",
        "source_fields": [
          "eia_plant_id",
          "generator_id"
        ],
        "unit": "count"
      },
      "distinct_plant_count": {
        "additive_across_groups": false,
        "aggregation": "count_distinct",
        "authoritative_total_path": "summary.totals.distinct_plant_count",
        "category": "entities",
        "definition": "Distinct EIA plant IDs represented by Owner rows.",
        "display_name": "Distinct plant count",
        "display_precision": "Integer.",
        "grain": "result scope",
        "null_handling": "Always an integer count.",
        "rollup_behavior": "distinct_entity_count_not_additive",
        "row_metric_path": "rows[].metrics.distinct_plant_count",
        "source_fields": [
          "eia_plant_id"
        ],
        "unit": "count"
      },
      "percent_owned": {
        "additive_across_groups": false,
        "aggregation": "single receipt value only",
        "authoritative_total_path": "summary.totals.percent_owned",
        "category": "ownership",
        "definition": "EIA-860 Owner-schedule share preserved as a fraction of one; 1.0 means 100%.",
        "display_name": "Percent owned (raw fraction)",
        "display_precision": "Raw numeric value preserved.",
        "grain": "plant-generator-owner annual row",
        "null_handling": "Present on reported Owner rows; never fabricated for the operator-default convention.",
        "rollup_behavior": "non_additive_measure",
        "row_metric_path": "rows[].metrics.percent_owned",
        "source_fields": [
          "Percent Owned"
        ],
        "unit": "fraction of one"
      },
      "source_record_count": {
        "additive_across_groups": true,
        "aggregation": "count source records",
        "authoritative_total_path": "summary.totals.source_record_count",
        "category": "records",
        "definition": "Count of EIA-860 Owner rows in scope.",
        "display_name": "Source record count",
        "display_precision": "Integer.",
        "grain": "source row",
        "null_handling": "Always an integer count.",
        "rollup_behavior": "additive_partition_metric",
        "row_metric_path": "rows[].metrics.source_record_count",
        "source_fields": [
          "source_record_key"
        ],
        "unit": "count"
      }
    },
    "metrics": [
      "percent_owned",
      "source_record_count",
      "distinct_generator_count",
      "distinct_plant_count"
    ],
    "ownership_convention": {
      "absent_generator_interpretation": "wholly_owned_by_operator",
      "important": "An absent Owner-schedule row is not unknown ownership. EIA documents that the generator is wholly owned by its operator.",
      "operator_source": "same_vintage_eia860_generator_schedule",
      "owner_schedule_scope": "joint_or_third_party_owned_only"
    },
    "summary_fields": [
      "group_count",
      "totals"
    ]
  },
  "primitive": "query_power_asset_ownership_v1",
  "status": "available"
}