{
  "$id": "https://derpass.org/core/v1.0/schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "DER Passport Core Schema v1.0",
  "description": "Jurisdiction-neutral schema for distributed energy resource (DER) systems: photovoltaics, storage, controllable consumption, and their grid connection. National peculiarities are added through profile schemas that extend this core via allOf.",
  "type": "object",
  "required": [
    "derpass_version",
    "jurisdiction",
    "meta",
    "commissioning"
  ],
  "properties": {
    "derpass_version": {
      "type": "string",
      "pattern": "^\\d+\\.\\d+(\\.\\d+)?$",
      "description": "Version of the core specification this file conforms to. Follows MAJOR.MINOR (and optionally PATCH)."
    },
    "conforms_to": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri"
      },
      "uniqueItems": true,
      "description": "URIs of all profiles (including the core) this file claims to conform to. Validators check the file against each."
    },
    "jurisdiction": {
      "type": "object",
      "required": [
        "primary"
      ],
      "properties": {
        "primary": {
          "type": "string",
          "pattern": "^[A-Z]{2}$",
          "description": "ISO 3166-1 alpha-2 country code of the primary jurisdiction."
        },
        "subdivision": {
          "type": "string",
          "pattern": "^[A-Z]{2}-[A-Z0-9]{1,3}$",
          "description": "ISO 3166-2 subdivision code, e.g. DE-BY."
        },
        "applicable_profiles": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uri"
          },
          "description": "Profiles relevant for this file. Informational; the binding declaration is in 'conforms_to'."
        }
      },
      "additionalProperties": true
    },
    "meta": {
      "type": "object",
      "required": [
        "system_id",
        "name",
        "location",
        "created"
      ],
      "properties": {
        "system_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique identifier within the issuer's domain. Stable across the lifetime of the asset."
        },
        "name": {
          "type": "string",
          "description": "Human-readable name for the system."
        },
        "registry_ids": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/CodedReference"
          },
          "description": "Identifiers in national or regional registries (MaStR, EAN-18, MPAN, EIC, etc.)."
        },
        "owner": {
          "$ref": "#/$defs/Party"
        },
        "operator": {
          "$ref": "#/$defs/Party"
        },
        "installer": {
          "$ref": "#/$defs/Party"
        },
        "location": {
          "$ref": "#/$defs/Location"
        },
        "created": {
          "$ref": "#/$defs/DateString"
        },
        "last_modified": {
          "$ref": "#/$defs/DateString"
        }
      },
      "additionalProperties": true
    },
    "commissioning": {
      "type": "object",
      "required": [
        "commissioning_date",
        "dc_capacity_kwp",
        "ac_capacity_kw"
      ],
      "properties": {
        "commissioning_date": {
          "$ref": "#/$defs/DateString"
        },
        "grid_operator_notification_date": {
          "$ref": "#/$defs/DateString"
        },
        "meter_installation_date": {
          "$ref": "#/$defs/DateString"
        },
        "dc_capacity_kwp": {
          "type": "number",
          "minimum": 0,
          "description": "Installed DC nameplate capacity in kWp (sum of module nameplate ratings)."
        },
        "ac_capacity_kw": {
          "type": "number",
          "minimum": 0,
          "description": "Installed AC capacity in kW (sum of inverter AC nameplate ratings)."
        },
        "module_count": {
          "type": "integer",
          "minimum": 1
        },
        "inverter_count": {
          "type": "integer",
          "minimum": 1
        },
        "acceptance_protocol_url": {
          "type": "string"
        }
      }
    },
    "arrays": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "id",
          "azimuth_deg",
          "tilt_deg",
          "module_count",
          "module_ref"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "azimuth_deg": {
            "type": "number",
            "minimum": 0,
            "exclusiveMaximum": 360,
            "description": "Azimuth in degrees. 0 = North, 90 = East, 180 = South, 270 = West."
          },
          "tilt_deg": {
            "type": "number",
            "minimum": 0,
            "maximum": 90,
            "description": "Tilt from horizontal (0 = horizontal, 90 = vertical)."
          },
          "area_m2": {
            "type": "number",
            "minimum": 0
          },
          "module_count": {
            "type": "integer",
            "minimum": 1
          },
          "module_ref": {
            "type": "string",
            "description": "Reference to modules[].id"
          },
          "mounting_type": {
            "type": "string",
            "enum": [
              "roof_parallel",
              "roof_integrated",
              "ground_mounted",
              "facade",
              "flat_roof_tilted",
              "tracker",
              "other"
            ]
          },
          "shading_notes": {
            "type": "string"
          },
          "horizon_profile_url": {
            "type": "string"
          },
          "lifecycle": {
            "$ref": "#/$defs/Lifecycle"
          }
        }
      }
    },
    "modules": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "id",
          "manufacturer",
          "model",
          "nominal_power_wp"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "manufacturer": {
            "type": "string"
          },
          "model": {
            "type": "string"
          },
          "technology": {
            "type": "string",
            "enum": [
              "mono_perc",
              "mono_topcon",
              "mono_hjt",
              "mono_ibc",
              "polycrystalline",
              "cdte",
              "cigs",
              "amorphous",
              "tandem_perovskite_silicon",
              "other"
            ]
          },
          "nominal_power_wp": {
            "type": "number",
            "minimum": 0
          },
          "voc_v": {
            "type": "number"
          },
          "isc_a": {
            "type": "number"
          },
          "vmp_v": {
            "type": "number"
          },
          "imp_a": {
            "type": "number"
          },
          "efficiency_pct": {
            "type": "number",
            "minimum": 0,
            "maximum": 100
          },
          "temperature_coefficient_pmax_pct_k": {
            "type": "number"
          },
          "temperature_coefficient_voc_pct_k": {
            "type": "number"
          },
          "temperature_coefficient_isc_pct_k": {
            "type": "number"
          },
          "dimensions_mm": {
            "type": "array",
            "items": {
              "type": "number"
            },
            "minItems": 3,
            "maxItems": 3,
            "description": "[length, width, depth] in millimetres."
          },
          "weight_kg": {
            "type": "number",
            "minimum": 0
          },
          "datasheet_url": {
            "type": "string"
          },
          "compliance_certificates": {
            "type": "array",
            "items": {
              "$ref": "#/$defs/CodedReference"
            }
          },
          "lifecycle": {
            "$ref": "#/$defs/Lifecycle"
          },
          "warranties": {
            "type": "array",
            "items": {
              "$ref": "#/$defs/Warranty"
            }
          }
        }
      }
    },
    "strings": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "id",
          "array_ref",
          "module_ref",
          "module_count",
          "inverter_ref",
          "mppt_input"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "array_ref": {
            "type": "string"
          },
          "module_ref": {
            "type": "string"
          },
          "module_count": {
            "type": "integer",
            "minimum": 1
          },
          "inverter_ref": {
            "type": "string"
          },
          "mppt_input": {
            "type": "integer",
            "minimum": 1
          },
          "cable_length_m": {
            "type": "number",
            "minimum": 0
          },
          "cable_cross_section_mm2": {
            "type": "number",
            "minimum": 0
          }
        }
      }
    },
    "inverters": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "id",
          "manufacturer",
          "model",
          "ac_capacity_kw"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "manufacturer": {
            "type": "string"
          },
          "model": {
            "type": "string"
          },
          "serial_number": {
            "type": "string"
          },
          "ac_capacity_kw": {
            "type": "number",
            "minimum": 0
          },
          "max_dc_capacity_kw": {
            "type": "number",
            "minimum": 0
          },
          "mppt_count": {
            "type": "integer",
            "minimum": 1
          },
          "max_dc_voltage_v": {
            "type": "number"
          },
          "euro_efficiency_pct": {
            "type": "number",
            "minimum": 0,
            "maximum": 100
          },
          "datasheet_url": {
            "type": "string"
          },
          "compliance_certificates": {
            "type": "array",
            "items": {
              "$ref": "#/$defs/CodedReference"
            }
          },
          "lifecycle": {
            "$ref": "#/$defs/Lifecycle"
          },
          "warranties": {
            "type": "array",
            "items": {
              "$ref": "#/$defs/Warranty"
            }
          }
        }
      }
    },
    "storage": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "id",
          "manufacturer",
          "model",
          "usable_capacity_kwh"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "manufacturer": {
            "type": "string"
          },
          "model": {
            "type": "string"
          },
          "chemistry": {
            "type": "string",
            "enum": [
              "lfp",
              "nmc",
              "nca",
              "lto",
              "lead_acid",
              "redox_flow",
              "sodium_ion",
              "other"
            ]
          },
          "usable_capacity_kwh": {
            "type": "number",
            "minimum": 0
          },
          "gross_capacity_kwh": {
            "type": "number",
            "minimum": 0
          },
          "max_charge_kw": {
            "type": "number",
            "minimum": 0
          },
          "max_discharge_kw": {
            "type": "number",
            "minimum": 0
          },
          "round_trip_efficiency_pct": {
            "type": "number",
            "minimum": 0,
            "maximum": 100
          },
          "coupling": {
            "type": "string",
            "enum": [
              "dc_coupled",
              "ac_coupled",
              "hybrid"
            ]
          },
          "connected_inverter_ref": {
            "type": "string"
          },
          "lifecycle": {
            "$ref": "#/$defs/Lifecycle"
          },
          "warranties": {
            "type": "array",
            "items": {
              "$ref": "#/$defs/Warranty"
            }
          }
        }
      }
    },
    "construction": {
      "type": "object",
      "properties": {
        "construction_start": {
          "$ref": "#/$defs/DateString"
        },
        "construction_end": {
          "$ref": "#/$defs/DateString"
        },
        "lightning_protection": {
          "type": "boolean"
        },
        "equipotential_bonding": {
          "type": "boolean"
        },
        "string_layout_url": {
          "type": "string"
        },
        "single_line_diagram_url": {
          "type": "string"
        },
        "cable_routes": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "id",
              "from",
              "to"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "from": {
                "type": "string"
              },
              "to": {
                "type": "string"
              },
              "length_m": {
                "type": "number",
                "minimum": 0
              },
              "cable_type": {
                "type": "string"
              },
              "cross_section_mm2": {
                "type": "number",
                "minimum": 0
              },
              "conductor_count": {
                "type": "integer",
                "minimum": 1
              },
              "installation_method": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "metering_concept": {
      "type": "object",
      "required": [
        "type",
        "meters"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "full_feed_in",
            "self_consumption_with_surplus",
            "cascade",
            "island",
            "tenant_supply",
            "community"
          ],
          "description": "Generic metering scheme. National profiles may add concrete numbering (e.g. DE Messkonzept-Nummer)."
        },
        "schematic_url": {
          "type": "string"
        },
        "meters": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "object",
            "required": [
              "id",
              "role"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "role": {
                "type": "string",
                "enum": [
                  "bidirectional",
                  "generation",
                  "consumption_household",
                  "consumption_heat_pump",
                  "consumption_ev_charger",
                  "submeter",
                  "import_export",
                  "other"
                ]
              },
              "meter_number": {
                "type": "string"
              },
              "obis_codes": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "OBIS identifiers per IEC 62056, e.g. 1-0:1.8.0."
              },
              "smgw_id": {
                "type": "string"
              },
              "location": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "grid_connection_point": {
      "type": "object",
      "required": [
        "id",
        "voltage_level",
        "connection_phases",
        "nominal_voltage_v",
        "nominal_frequency_hz",
        "max_export_kw",
        "protection"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "voltage_level": {
          "type": "string",
          "enum": [
            "low_voltage",
            "medium_voltage",
            "high_voltage",
            "extra_high_voltage"
          ]
        },
        "connection_phases": {
          "type": "string",
          "enum": [
            "single_phase",
            "three_phase"
          ]
        },
        "nominal_voltage_v": {
          "type": "number",
          "minimum": 0
        },
        "nominal_frequency_hz": {
          "type": "number",
          "enum": [
            50,
            60
          ]
        },
        "agreed_connection_capacity_kva": {
          "type": "number",
          "minimum": 0
        },
        "max_export_kw": {
          "type": "number",
          "minimum": 0,
          "description": "Contractually agreed maximum active power export."
        },
        "max_import_kw": {
          "type": "number",
          "minimum": 0
        },
        "short_circuit_capacity_sk_kva": {
          "type": "number",
          "minimum": 0
        },
        "grid_impedance_zk_ohm": {
          "type": "number",
          "minimum": 0
        },
        "transformer": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "rated_capacity_kva": {
              "type": "number",
              "minimum": 0
            },
            "line_distance_m": {
              "type": "number",
              "minimum": 0
            }
          }
        },
        "service_entrance": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string"
            },
            "coordinates": {
              "$ref": "#/$defs/Coordinates"
            },
            "main_fuse_a": {
              "type": "number",
              "minimum": 0
            }
          }
        },
        "isolation_point": {
          "type": "string"
        },
        "protection": {
          "type": "object",
          "required": [
            "type",
            "norm"
          ],
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "integrated_in_inverter",
                "central_external",
                "not_required"
              ]
            },
            "norm": {
              "$ref": "#/$defs/CodedReference",
              "description": "Coded reference to the applicable interconnection standard, e.g. {scheme: 'EU-EN-50549'} or {scheme: 'DE-VDE-AR-N', value: '4105:2018-11'}."
            },
            "certificate_url": {
              "type": "string"
            }
          }
        },
        "grid_operator": {
          "type": "object",
          "required": [
            "name"
          ],
          "properties": {
            "name": {
              "type": "string"
            },
            "role": {
              "type": "string",
              "enum": [
                "distribution",
                "transmission",
                "closed_distribution",
                "private"
              ]
            },
            "identifiers": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/CodedReference"
              }
            }
          }
        },
        "single_line_diagram_url": {
          "type": "string"
        },
        "connection_agreement_url": {
          "type": "string"
        }
      }
    },
    "consumption": {
      "type": "object",
      "properties": {
        "annual_consumption_kwh": {
          "type": "number",
          "minimum": 0
        },
        "load_profile_reference_type": {
          "type": "string",
          "description": "Reference profile family used for synthetic load curves. E.g. BDEW-H0, VDI-4655-WP."
        },
        "controllable_devices": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "id",
              "type"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "type": {
                "type": "string",
                "enum": [
                  "heat_pump",
                  "ev_charger",
                  "battery_storage",
                  "electric_boiler",
                  "air_conditioning",
                  "household_general",
                  "industrial_process",
                  "other"
                ]
              },
              "name": {
                "type": "string"
              },
              "rated_power_kw": {
                "type": "number",
                "minimum": 0
              },
              "annual_consumption_kwh": {
                "type": "number",
                "minimum": 0
              },
              "controllable_per_grid_directive": {
                "type": "boolean",
                "description": "True if the device is subject to a grid-operator-controlled curtailment directive (e.g. §14a EnWG, NL netcongestie, UK demand-side response)."
              },
              "framework": {
                "$ref": "#/$defs/CodedReference",
                "description": "Coded reference to the applicable framework, e.g. {scheme: 'DE-EnWG-14a'}."
              },
              "min_uncurtailed_power_kw": {
                "type": "number",
                "minimum": 0,
                "description": "Minimum active power that the device must remain able to draw even under maximum curtailment by the grid operator."
              },
              "control_interface": {
                "type": "object",
                "properties": {
                  "protocol": {
                    "type": "string",
                    "enum": [
                      "smart_meter_gateway",
                      "modbus_tcp",
                      "modbus_rtu",
                      "ocpp",
                      "eebus",
                      "knx",
                      "iec_61850",
                      "proprietary",
                      "none"
                    ]
                  },
                  "endpoint": {
                    "type": "string"
                  },
                  "manufacturer_specific": {
                    "type": "object"
                  }
                }
              },
              "submeter_ref": {
                "type": "string",
                "description": "Reference to metering_concept.meters[].id if separately metered."
              },
              "load_profile_ref": {
                "type": "string",
                "description": "Reference to load_profiles[].id."
              },
              "type_specific": {
                "type": "object",
                "description": "Free-form bag for device-type-specific properties (e.g. heat pump SCOP, EV charger phases). National profiles may constrain this further."
              }
            }
          }
        }
      }
    },
    "load_profiles": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "id",
          "type",
          "reference_point",
          "source",
          "period",
          "resolution_minutes",
          "unit",
          "sign_convention",
          "file",
          "timezone"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "consumption",
              "generation",
              "export",
              "import",
              "residual",
              "storage_soc",
              "storage_power"
            ]
          },
          "reference_point": {
            "type": "string",
            "description": "ID of the entity the time series refers to: a controllable_device, an inverter, storage, or the grid_connection_point."
          },
          "source": {
            "type": "string",
            "enum": [
              "measured",
              "synthetic",
              "simulated",
              "forecast"
            ]
          },
          "measurement_device": {
            "type": "string"
          },
          "period": {
            "type": "array",
            "items": {
              "$ref": "#/$defs/DateString"
            },
            "minItems": 2,
            "maxItems": 2,
            "description": "[start_date, end_date], both inclusive."
          },
          "resolution_minutes": {
            "type": "integer",
            "minimum": 1,
            "description": "Sampling interval in minutes. Common values: 1, 5, 15, 60."
          },
          "unit": {
            "type": "string",
            "enum": [
              "kWh",
              "kW",
              "pct",
              "Wh",
              "W"
            ]
          },
          "sign_convention": {
            "type": "string",
            "enum": [
              "import_positive",
              "generation_positive",
              "import_positive_export_negative",
              "charge_positive_discharge_negative"
            ]
          },
          "file": {
            "type": "string",
            "description": "Relative path to CSV or Parquet file."
          },
          "file_format": {
            "type": "string",
            "enum": [
              "csv",
              "parquet"
            ]
          },
          "timezone": {
            "type": "string",
            "description": "IANA timezone identifier, e.g. Europe/Berlin."
          },
          "key_figures": {
            "type": "object",
            "description": "Pre-computed aggregates for quick consumption without parsing the file.",
            "additionalProperties": true
          }
        }
      }
    },
    "compensation": {
      "type": "object",
      "required": [
        "scheme"
      ],
      "properties": {
        "scheme": {
          "type": "string",
          "enum": [
            "feed_in_tariff",
            "market_premium",
            "power_purchase_agreement",
            "net_metering",
            "net_billing",
            "self_consumption_only",
            "community_energy",
            "auction_award"
          ]
        },
        "tariff": {
          "type": "object",
          "properties": {
            "rate_value": {
              "type": "number"
            },
            "rate_currency": {
              "type": "string",
              "pattern": "^[A-Z]{3}$"
            },
            "rate_unit": {
              "type": "string",
              "enum": [
                "per_kwh",
                "per_mwh",
                "per_month",
                "per_year"
              ]
            },
            "valid_from": {
              "$ref": "#/$defs/DateString"
            },
            "valid_until": {
              "$ref": "#/$defs/DateString"
            }
          }
        },
        "direct_marketer": {
          "type": [
            "string",
            "null"
          ]
        },
        "ppa_counterparty": {
          "type": "string"
        },
        "supply_contract": {
          "type": "object",
          "properties": {
            "supplier": {
              "type": "string"
            },
            "tariff_name": {
              "type": "string"
            },
            "energy_price_value": {
              "type": "number"
            },
            "energy_price_currency": {
              "type": "string",
              "pattern": "^[A-Z]{3}$"
            },
            "energy_price_unit": {
              "type": "string"
            },
            "base_fee_value": {
              "type": "number"
            },
            "base_fee_currency": {
              "type": "string",
              "pattern": "^[A-Z]{3}$"
            },
            "base_fee_unit": {
              "type": "string"
            },
            "contract_end": {
              "$ref": "#/$defs/DateString"
            },
            "dynamic_pricing": {
              "type": "boolean"
            },
            "dynamic_pricing_source": {
              "type": "string"
            }
          }
        }
      }
    },
    "external_control": {
      "type": "object",
      "properties": {
        "remote_control_active": {
          "type": "boolean"
        },
        "curtailment_type": {
          "type": "string",
          "enum": [
            "none",
            "fixed_cap",
            "dynamic",
            "redispatch",
            "direct_marketer",
            "national_specific"
          ]
        },
        "interface_protocol": {
          "type": "string",
          "enum": [
            "modbus_tcp",
            "modbus_rtu",
            "sunspec",
            "iec_61850",
            "eebus",
            "ripple_control_receiver",
            "proprietary"
          ]
        },
        "endpoint": {
          "type": "string"
        },
        "max_active_power_setpoint_kw": {
          "type": "number",
          "minimum": 0
        },
        "reactive_power_control": {
          "type": "string",
          "enum": [
            "none",
            "fixed_cos_phi",
            "cos_phi_p",
            "q_u",
            "fixed_q"
          ]
        },
        "cos_phi_setpoint": {
          "type": "number",
          "minimum": -1,
          "maximum": 1
        },
        "energy_management_system": {
          "type": "object",
          "properties": {
            "manufacturer": {
              "type": "string"
            },
            "version": {
              "type": "string"
            },
            "role": {
              "type": "string",
              "enum": [
                "local_ems",
                "cloud_ems",
                "none"
              ]
            }
          }
        }
      }
    },
    "generation_data": {
      "type": "object",
      "properties": {
        "expected_annual_yield_kwh": {
          "type": "number",
          "minimum": 0
        },
        "specific_yield_kwh_per_kwp": {
          "type": "number",
          "minimum": 0
        },
        "performance_ratio": {
          "type": "number",
          "minimum": 0,
          "maximum": 1.5
        },
        "monthly_summary": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "month"
            ],
            "properties": {
              "month": {
                "type": "string",
                "pattern": "^\\d{4}-(0[1-9]|1[0-2])$"
              },
              "yield_kwh": {
                "type": "number",
                "minimum": 0
              },
              "self_consumption_kwh": {
                "type": "number",
                "minimum": 0
              },
              "export_kwh": {
                "type": "number",
                "minimum": 0
              },
              "import_kwh": {
                "type": "number",
                "minimum": 0
              }
            }
          }
        }
      }
    },
    "documents": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "type",
          "url"
        ],
        "properties": {
          "type": {
            "type": "string",
            "description": "Document category. Common values: module_datasheet, inverter_datasheet, storage_datasheet, unit_certificate, plant_certificate, string_layout, single_line_diagram, metering_concept, connection_agreement, registry_filing, commissioning_report, controllable_device_agreement, direct_marketing_agreement, insurance_policy, maintenance_agreement, ownership_proof, other."
          },
          "ref": {
            "type": "string",
            "description": "Optional reference to the entity the document concerns (e.g. an inverter id)."
          },
          "url": {
            "type": "string"
          },
          "issued_date": {
            "$ref": "#/$defs/DateString"
          },
          "valid_until": {
            "$ref": "#/$defs/DateString"
          }
        }
      }
    },
    "national": {
      "type": "object",
      "patternProperties": {
        "^[A-Z]{2}$": {
          "type": "object",
          "additionalProperties": true
        }
      },
      "additionalProperties": false,
      "description": "Country-specific extensions, keyed by ISO 3166-1 alpha-2 code. The structure within each country block is governed by the national profile schema."
    },
    "events": {
      "type": "array",
      "description": "Append-only log of significant events in the asset's life. Forms the 'service book' of the DER Passport. Should be ordered chronologically (ascending timestamp).",
      "items": {
        "$ref": "#/$defs/Event"
      }
    },
    "revisions": {
      "type": "array",
      "description": "History of this DER Passport file itself (not the asset). Each revision links to the previous one via a content hash, enabling an integrity chain across handovers.",
      "items": {
        "type": "object",
        "required": [
          "revision",
          "issued_at",
          "issued_by"
        ],
        "properties": {
          "revision": {
            "type": "integer",
            "minimum": 1,
            "description": "Monotonically increasing revision number, starting at 1."
          },
          "issued_at": {
            "$ref": "#/$defs/TimestampString"
          },
          "issued_by": {
            "$ref": "#/$defs/Party"
          },
          "summary": {
            "type": "string"
          },
          "previous_hash": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^(sha256:[0-9a-f]{64}|sha512:[0-9a-f]{128})$",
            "description": "Content hash of the previous revision file. Null for revision 1. Format 'sha256:<hex>' or 'sha512:<hex>'."
          },
          "archive_url": {
            "type": "string",
            "description": "Pointer to where the previous revision file is archived (HTTPS, IPFS, etc.)."
          },
          "signatures": {
            "type": "array",
            "items": {
              "$ref": "#/$defs/Signature"
            },
            "description": "Cryptographic signatures over the revision content. Multiple parties may co-sign."
          }
        },
        "additionalProperties": true
      }
    },
    "insurance": {
      "type": "array",
      "description": "Insurance policies covering the asset.",
      "items": {
        "type": "object",
        "required": [
          "id",
          "type",
          "insurer"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "property_all_risk",
              "property_named_perils",
              "liability",
              "business_interruption",
              "extended_warranty",
              "performance_guarantee",
              "other"
            ]
          },
          "insurer": {
            "$ref": "#/$defs/Party"
          },
          "policy_number": {
            "type": "string"
          },
          "valid_from": {
            "$ref": "#/$defs/DateString"
          },
          "valid_until": {
            "$ref": "#/$defs/DateString"
          },
          "coverage_amount": {
            "$ref": "#/$defs/Money"
          },
          "premium": {
            "$ref": "#/$defs/Money"
          },
          "deductible": {
            "$ref": "#/$defs/Money"
          },
          "covered_components": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "References to entity IDs covered by this policy. Empty or omitted means the whole asset."
          },
          "policy_url": {
            "type": "string"
          }
        },
        "additionalProperties": true
      }
    },
    "maintenance_contracts": {
      "type": "array",
      "description": "Active or historical maintenance and service contracts.",
      "items": {
        "type": "object",
        "required": [
          "id",
          "provider"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "provider": {
            "$ref": "#/$defs/Party"
          },
          "contract_type": {
            "type": "string",
            "enum": [
              "full_service",
              "inspection_only",
              "on_call",
              "monitoring_only",
              "performance_guarantee",
              "other"
            ]
          },
          "interval": {
            "type": "string",
            "enum": [
              "monthly",
              "quarterly",
              "biannual",
              "annual",
              "biennial",
              "triennial",
              "ad_hoc"
            ]
          },
          "valid_from": {
            "$ref": "#/$defs/DateString"
          },
          "valid_until": {
            "$ref": "#/$defs/DateString"
          },
          "next_due": {
            "$ref": "#/$defs/DateString"
          },
          "cost": {
            "$ref": "#/$defs/Money"
          },
          "covered_components": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "contract_url": {
            "type": "string"
          }
        },
        "additionalProperties": true
      }
    },
    "alerts": {
      "type": "array",
      "description": "Operational alerts and notices about the asset. Displayed prominently by viewers.",
      "items": {
        "type": "object",
        "required": [
          "id",
          "severity",
          "title"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "severity": {
            "type": "string",
            "enum": [
              "trivia",
              "info",
              "warning",
              "danger"
            ],
            "description": "Severity level. trivia = curious/historical; info = noteworthy; warning = needs attention; danger = active hazard."
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "affects": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "References to entity IDs the alert pertains to."
          },
          "created_at": {
            "$ref": "#/$defs/TimestampString"
          },
          "created_by": {
            "$ref": "#/$defs/Party"
          },
          "expires_at": {
            "$ref": "#/$defs/TimestampString"
          },
          "acknowledged_at": {
            "$ref": "#/$defs/TimestampString"
          },
          "category": {
            "type": "string",
            "description": "Free-form category tag for grouping (e.g. 'safety', 'regulatory', 'maintenance', 'historical')."
          }
        },
        "additionalProperties": true
      }
    },
    "site_access": {
      "type": "object",
      "description": "Physical access information for visiting the site: instructions, contacts, required PPE, hazards.",
      "properties": {
        "access_instructions": {
          "type": "string",
          "description": "Free-form description of how to reach the site and the equipment."
        },
        "entry_contact": {
          "$ref": "#/$defs/Party"
        },
        "approach_notes": {
          "type": "string",
          "description": "Anything special about the approach: dirt road, narrow access, dogs at the gate, etc."
        },
        "gate_credentials": {
          "type": "object",
          "description": "Gate or door credentials. Storing the literal code is discouraged; reference an external secret store.",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "keypad_code",
                "physical_key",
                "rfid_card",
                "biometric",
                "key_box",
                "none"
              ]
            },
            "credential_reference": {
              "type": "string",
              "description": "Pointer to an external secret store entry (e.g. '1Password://...', 'KeePass://...'). Avoid literal codes here."
            }
          }
        },
        "required_ppe": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "hard_hat",
              "safety_shoes",
              "safety_glasses",
              "high_visibility_vest",
              "insulating_gloves",
              "fall_protection",
              "fire_resistant_clothing"
            ]
          }
        },
        "hazards": {
          "type": "array",
          "description": "Known hazards on site.",
          "items": {
            "type": "object",
            "required": [
              "type"
            ],
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "high_voltage",
                  "battery_chemical",
                  "fall_height",
                  "moving_machinery",
                  "livestock",
                  "guard_dog",
                  "rough_terrain",
                  "remote_location",
                  "confined_space",
                  "hot_surface",
                  "noise",
                  "other"
                ]
              },
              "description": {
                "type": "string"
              },
              "location": {
                "type": "string"
              }
            }
          }
        },
        "permits_required": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "operating_hours": {
          "type": "string",
          "description": "When access is normally possible (e.g. 'business hours Mo-Fr 08:00-17:00')."
        },
        "notes": {
          "type": "string"
        }
      },
      "additionalProperties": true
    },
    "remote_access": {
      "type": "array",
      "description": "Network-level remote access endpoints (VPN, API, monitoring portals). Credentials MUST NOT be stored as plaintext; use 'encrypted_credentials' (JWE) or reference external secret stores.",
      "items": {
        "type": "object",
        "required": [
          "id",
          "purpose",
          "protocol"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "purpose": {
            "type": "string",
            "enum": [
              "monitoring",
              "control",
              "direct_marketing",
              "maintenance",
              "billing_data",
              "regulatory_reporting",
              "owner_dashboard",
              "other"
            ]
          },
          "protocol": {
            "type": "string",
            "enum": [
              "vpn_wireguard",
              "vpn_openvpn",
              "vpn_ipsec",
              "vpn_l2tp",
              "https_api",
              "https_dashboard",
              "ssh",
              "modbus_tcp",
              "ocpp",
              "iec_61850_mms",
              "mqtt",
              "iec_60870_104",
              "other"
            ]
          },
          "endpoint": {
            "type": "string",
            "description": "Hostname, URL, or address:port of the endpoint."
          },
          "username": {
            "type": "string",
            "description": "Username if not sensitive. Never store passwords here."
          },
          "intended_recipient": {
            "$ref": "#/$defs/Party"
          },
          "encrypted_credentials": {
            "type": "object",
            "description": "Optional JWE (RFC 7516) encrypted blob containing credentials, decryptable only by the intended recipient's private key.",
            "properties": {
              "jwe": {
                "type": "string",
                "description": "Compact-serialised JWE string."
              },
              "recipient_kid": {
                "type": "string"
              }
            }
          },
          "credential_reference": {
            "type": "string",
            "description": "Pointer to an external secret store (preferred over inline encryption for most cases)."
          },
          "valid_from": {
            "$ref": "#/$defs/DateString"
          },
          "valid_until": {
            "$ref": "#/$defs/DateString"
          },
          "notes": {
            "type": "string"
          }
        },
        "additionalProperties": true
      }
    }
  },
  "$defs": {
    "CodedReference": {
      "type": "object",
      "required": [
        "scheme"
      ],
      "properties": {
        "scheme": {
          "type": "string",
          "description": "Identifier of the coding system, e.g. DE-MaStR, NL-EAN-18, EU-EN-50549."
        },
        "value": {
          "type": "string",
          "description": "The actual identifier or code under the named scheme. Optional for pure conformance references where only the scheme itself is meaningful (e.g. 'complies with IEC 61215')."
        },
        "version": {
          "type": "string",
          "description": "Optional version of the scheme, e.g. '4105:2018-11' for VDE-AR-N."
        }
      },
      "additionalProperties": false,
      "examples": [
        {
          "scheme": "DE-MaStR",
          "value": "SEE901234567890"
        },
        {
          "scheme": "NL-EAN-18",
          "value": "871685900012345678"
        },
        {
          "scheme": "DE-VDE-AR-N",
          "value": "4105",
          "version": "2018-11"
        },
        {
          "scheme": "IEC-61215"
        }
      ]
    },
    "Party": {
      "type": "object",
      "required": [
        "name"
      ],
      "properties": {
        "name": {
          "type": "string"
        },
        "company": {
          "type": "string"
        },
        "contact": {
          "type": "string",
          "description": "Free-form contact information (email, phone, or address)."
        },
        "role": {
          "type": "string"
        },
        "identifiers": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/CodedReference"
          },
          "description": "E.g. installer registry numbers."
        }
      },
      "additionalProperties": true
    },
    "Location": {
      "type": "object",
      "required": [
        "country",
        "latitude",
        "longitude"
      ],
      "properties": {
        "address": {
          "type": "string"
        },
        "country": {
          "type": "string",
          "pattern": "^[A-Z]{2}$",
          "description": "ISO 3166-1 alpha-2 country code."
        },
        "subdivision": {
          "type": "string",
          "pattern": "^[A-Z]{2}-[A-Z0-9]{1,3}$"
        },
        "postal_code": {
          "type": "string"
        },
        "city": {
          "type": "string"
        },
        "latitude": {
          "type": "number",
          "minimum": -90,
          "maximum": 90
        },
        "longitude": {
          "type": "number",
          "minimum": -180,
          "maximum": 180
        },
        "elevation_m": {
          "type": "number"
        },
        "timezone": {
          "type": "string",
          "description": "IANA timezone identifier, e.g. Europe/Berlin."
        },
        "cadastral_reference": {
          "type": "string",
          "description": "Free-form cadastral or land registry reference."
        }
      },
      "additionalProperties": true
    },
    "Coordinates": {
      "type": "object",
      "required": [
        "latitude",
        "longitude"
      ],
      "properties": {
        "latitude": {
          "type": "number",
          "minimum": -90,
          "maximum": 90
        },
        "longitude": {
          "type": "number",
          "minimum": -180,
          "maximum": 180
        }
      },
      "additionalProperties": false
    },
    "DateString": {
      "type": "string",
      "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$",
      "description": "ISO 8601 calendar date, YYYY-MM-DD."
    },
    "TimestampString": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp with timezone offset or Z."
    },
    "Money": {
      "type": "object",
      "required": [
        "value",
        "currency"
      ],
      "properties": {
        "value": {
          "type": "number"
        },
        "currency": {
          "type": "string",
          "pattern": "^[A-Z]{3}$",
          "description": "ISO 4217 currency code (EUR, GBP, USD)."
        },
        "unit": {
          "type": "string",
          "enum": [
            "per_kwh",
            "per_mwh",
            "per_month",
            "per_year",
            "per_event",
            "total"
          ],
          "description": "Optional unit specifying the basis of the amount. Omit for one-off amounts."
        }
      },
      "additionalProperties": false
    },
    "Lifecycle": {
      "type": "object",
      "description": "Operational lifecycle of an entity. Optional; omit for entities without a recorded lifecycle.",
      "properties": {
        "installed_at": {
          "$ref": "#/$defs/DateString"
        },
        "decommissioned_at": {
          "$ref": "#/$defs/DateString"
        },
        "decommissioning_reason": {
          "type": "string",
          "enum": [
            "end_of_life",
            "defect",
            "upgrade",
            "damage",
            "regulatory",
            "other"
          ]
        },
        "replaces": {
          "type": "string",
          "description": "ID of the entity this one replaced."
        },
        "replaced_by": {
          "type": "string",
          "description": "ID of the entity that replaced this one."
        },
        "current_status": {
          "type": "string",
          "enum": [
            "planned",
            "operational",
            "fault",
            "decommissioned",
            "removed",
            "in_storage"
          ]
        }
      },
      "additionalProperties": false
    },
    "Warranty": {
      "type": "object",
      "description": "A warranty covering an entity. Multiple warranties may apply to a single component (e.g. product + performance for modules).",
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "product",
            "performance",
            "linear_performance",
            "labor",
            "system",
            "other"
          ]
        },
        "duration_years": {
          "type": "number",
          "minimum": 0
        },
        "start_date": {
          "$ref": "#/$defs/DateString"
        },
        "end_date": {
          "$ref": "#/$defs/DateString"
        },
        "provider": {
          "type": "string",
          "description": "Manufacturer, installer, or third-party warranty provider name."
        },
        "coverage_description": {
          "type": "string"
        },
        "performance_threshold_pct": {
          "type": "number",
          "minimum": 0,
          "maximum": 100,
          "description": "For 'performance' warranties: minimum guaranteed output as a percentage of nameplate at end of warranty period."
        },
        "annual_degradation_pct": {
          "type": "number",
          "description": "For 'linear_performance' warranties: maximum guaranteed annual degradation rate."
        },
        "document_url": {
          "type": "string"
        }
      },
      "additionalProperties": true
    },
    "Event": {
      "type": "object",
      "required": [
        "id",
        "timestamp",
        "type"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique event identifier within the events array."
        },
        "timestamp": {
          "anyOf": [
            {
              "$ref": "#/$defs/DateString"
            },
            {
              "$ref": "#/$defs/TimestampString"
            }
          ],
          "description": "Event date or timestamp. Date-only (YYYY-MM-DD) is acceptable when time is unknown; otherwise full ISO 8601 with timezone."
        },
        "type": {
          "type": "string",
          "enum": [
            "commissioning",
            "recommissioning",
            "component_install",
            "component_replacement",
            "component_decommission",
            "maintenance",
            "repair",
            "inspection",
            "damage",
            "insurance_claim",
            "firmware_update",
            "configuration_change",
            "owner_change",
            "operator_change",
            "contract_change",
            "regulatory_change",
            "registry_update",
            "performance_test",
            "outage",
            "curtailment_event",
            "decommissioning",
            "dismantling",
            "repowering",
            "other"
          ]
        },
        "actor": {
          "$ref": "#/$defs/Party"
        },
        "summary": {
          "type": "string"
        },
        "affects": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "IDs of entities affected by this event (e.g. inverter-1, array-2)."
        },
        "data": {
          "type": "object",
          "description": "Event-type-specific payload. Free-form for v1.0; profiles may constrain per type."
        },
        "documents": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "References to documents[].type or to URLs; free-form."
        },
        "signatures": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Signature"
          },
          "description": "Optional cryptographic signatures attesting to the event. Typically signed by the actor."
        }
      },
      "additionalProperties": true
    },
    "Signature": {
      "type": "object",
      "required": [
        "algorithm",
        "signer",
        "signed_at",
        "signature"
      ],
      "properties": {
        "algorithm": {
          "type": "string",
          "enum": [
            "RS256",
            "RS384",
            "RS512",
            "ES256",
            "ES384",
            "ES512",
            "EdDSA",
            "PS256"
          ],
          "description": "JWS algorithm identifier (RFC 7518)."
        },
        "key_id": {
          "type": "string",
          "description": "Identifier of the signing key (kid)."
        },
        "signer": {
          "$ref": "#/$defs/Party"
        },
        "signer_role": {
          "type": "string",
          "description": "Role under which the signer attests, e.g. installer, certifier, owner, notary, dso."
        },
        "signed_at": {
          "$ref": "#/$defs/TimestampString"
        },
        "signature": {
          "type": "string",
          "description": "Base64url-encoded detached JWS signature value over the canonical form (RFC 8785) of the signed payload (the enclosing object minus its 'signatures' field)."
        },
        "public_key": {
          "type": "object",
          "description": "JWK (RFC 7517) of the public key, OR a reference URL to it.",
          "properties": {
            "jwk": {
              "type": "object"
            },
            "url": {
              "type": "string"
            },
            "x5c_url": {
              "type": "string",
              "description": "URL to X.509 certificate chain."
            }
          }
        }
      },
      "additionalProperties": false
    }
  }
}