{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "bps/urban-energy",
  "title": "Urban-Scale Energy Schema",
  "description": "Urban scale energy parameters: aggregate energy demand, renewable energy potential, and city-level energy systems.",
  "$defs": {
    "_IdentifiedObject": {
      "type": "object",
      "properties": {
        "identifier": {
          "type": "string",
          "pattern": "^[.A-Za-z0-9_-]+$",
          "minLength": 1,
          "maxLength": 100
        },
        "display_name": {
          "type": [
            "string",
            "null"
          ]
        },
        "user_data": {
          "type": [
            "object",
            "null"
          ]
        }
      },
      "required": [
        "identifier"
      ]
    },
    "UrbanEnergyDemand": {
      "type": "object",
      "allOf": [
        {
          "$ref": "#/$defs/_IdentifiedObject"
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "const": "UrbanEnergyDemand"
            },
            "land_use_ref": {
              "type": "string",
              "description": "Reference to LandUse identifier"
            },
            "annual_heating_demand": {
              "type": "number",
              "minimum": 0,
              "description": "kWh per year"
            },
            "annual_cooling_demand": {
              "type": "number",
              "minimum": 0,
              "description": "kWh per year"
            },
            "annual_lighting_demand": {
              "type": "number",
              "minimum": 0,
              "description": "kWh per year"
            },
            "annual_equipment_demand": {
              "type": "number",
              "minimum": 0,
              "description": "kWh per year"
            },
            "peak_heating_demand": {
              "type": "number",
              "minimum": 0,
              "description": "kW"
            },
            "peak_cooling_demand": {
              "type": "number",
              "minimum": 0,
              "description": "kW"
            },
            "demand_density": {
              "type": "number",
              "minimum": 0,
              "description": "kWh per square meter per year"
            }
          },
          "required": [
            "type"
          ],
          "additionalProperties": false
        }
      ]
    },
    "RenewablePotential": {
      "type": "object",
      "allOf": [
        {
          "$ref": "#/$defs/_IdentifiedObject"
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "const": "RenewablePotential"
            },
            "land_use_ref": {
              "type": "string"
            },
            "solar_roof_potential": {
              "type": "number",
              "minimum": 0,
              "description": "kWh per year from rooftop PV"
            },
            "solar_facade_potential": {
              "type": "number",
              "minimum": 0,
              "description": "kWh per year from facade BIPV"
            },
            "solar_ground_potential": {
              "type": "number",
              "minimum": 0,
              "description": "kWh per year from ground-mounted PV"
            },
            "geothermal_potential": {
              "type": "number",
              "minimum": 0,
              "description": "kWh per year from ground source"
            },
            "wind_potential": {
              "type": "number",
              "minimum": 0,
              "description": "kWh per year from small wind turbines"
            },
            "available_roof_area": {
              "type": "number",
              "minimum": 0,
              "description": "square meters suitable for PV"
            },
            "suitable_facade_area": {
              "type": "number",
              "minimum": 0,
              "description": "square meters suitable for BIPV"
            }
          },
          "required": [
            "type"
          ],
          "additionalProperties": false
        }
      ]
    },
    "UrbanEnergyBalance": {
      "type": "object",
      "allOf": [
        {
          "$ref": "#/$defs/_IdentifiedObject"
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "const": "UrbanEnergyBalance"
            },
            "annual_total_demand": {
              "type": "number",
              "minimum": 0,
              "description": "kWh per year"
            },
            "annual_total_renewable_generation": {
              "type": "number",
              "minimum": 0,
              "description": "kWh per year"
            },
            "renewable_self_sufficiency_ratio": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "annual_co2_emissions": {
              "type": "number",
              "description": "tonnes CO2 per year"
            },
            "carbon_intensity": {
              "type": "number",
              "description": "kg CO2 per kWh"
            },
            "energy_use_intensity": {
              "type": "number",
              "minimum": 0,
              "description": "kWh per square meter per year"
            }
          },
          "required": [
            "type"
          ],
          "additionalProperties": false
        }
      ]
    },
    "UrbanEnergyProperties": {
      "type": "object",
      "allOf": [
        {
          "$ref": "#/$defs/_IdentifiedObject"
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "const": "UrbanEnergyProperties"
            },
            "demands": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/UrbanEnergyDemand"
              }
            },
            "renewable_potentials": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/RenewablePotential"
              }
            },
            "energy_balance": {
              "$ref": "#/$defs/UrbanEnergyBalance"
            }
          },
          "required": [
            "type"
          ],
          "additionalProperties": false
        }
      ]
    }
  }
}