bps-schema/schema-community-energy.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "bps/community-energy",
  "title": "Community-Scale Energy Schema",
  "description": "District energy system parameters for community scale. Covers plants, networks, pipes, building connections, and community-level energy demand aggregation.",
  "$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"]
    },
    "PlantType": {
      "type": "string",
      "enum": [
        "CHP", "GasBoiler", "ElectricBoiler",
        "GroundSourceHeatPump", "AirSourceHeatPump",
        "Chiller", "CoolingTower",
        "ThermalStorage", "SolarThermal", "PV"
      ]
    },
    "NetworkType": {
      "type": "string",
      "enum": ["CHW", "HW", "Steam", "Electricity"]
    },
    "Plant": {
      "type": "object",
      "allOf": [
        { "$ref": "#/$defs/_IdentifiedObject" },
        {
          "type": "object",
          "properties": {
            "type": { "const": "Plant" },
            "plant_type": { "$ref": "#/$defs/PlantType" },
            "rated_capacity": { "type": "number", "exclusiveMinimum": 0, "description": "kW" },
            "cop": { "type": "number", "exclusiveMinimum": 0 },
            "fuel_type": { "type": "string", "default": "natural_gas" },
            "location": {
              "type": "array", "items": { "type": "number" },
              "minItems": 3, "maxItems": 3
            }
          },
          "required": ["type", "plant_type", "rated_capacity"],
          "additionalProperties": false
        }
      ]
    },
    "Pipe": {
      "type": "object",
      "allOf": [
        { "$ref": "#/$defs/_IdentifiedObject" },
        {
          "type": "object",
          "properties": {
            "type": { "const": "Pipe" },
            "start_node": { "type": "string" },
            "end_node": { "type": "string" },
            "length": { "type": "number", "exclusiveMinimum": 0, "description": "m" },
            "diameter": { "type": "number", "exclusiveMinimum": 0, "description": "m" },
            "insulation_thickness": { "type": "number", "minimum": 0, "default": 0 },
            "insulation_conductivity": { "type": "number", "exclusiveMinimum": 0, "default": 0.04 }
          },
          "required": ["type", "start_node", "end_node", "length", "diameter"],
          "additionalProperties": false
        }
      ]
    },
    "Network": {
      "type": "object",
      "allOf": [
        { "$ref": "#/$defs/_IdentifiedObject" },
        {
          "type": "object",
          "properties": {
            "type": { "const": "Network" },
            "network_type": { "$ref": "#/$defs/NetworkType" },
            "supply_temperature": { "type": "number", "description": "Celsius" },
            "return_temperature": { "type": "number", "description": "Celsius" },
            "pipes": {
              "type": "array",
              "items": { "$ref": "#/$defs/Pipe" }
            }
          },
          "required": ["type", "network_type", "pipes"],
          "additionalProperties": false
        }
      ]
    },
    "BuildingConnection": {
      "type": "object",
      "allOf": [
        { "$ref": "#/$defs/_IdentifiedObject" },
        {
          "type": "object",
          "properties": {
            "type": { "const": "BuildingConnection" },
            "building_ref": { "type": "string" },
            "network_ref": { "type": "string" },
            "design_flow_rate": { "type": "number", "exclusiveMinimum": 0 }
          },
          "required": ["type", "building_ref", "network_ref"],
          "additionalProperties": false
        }
      ]
    },

    "BuildingEnergyDemand": {
      "type": "object",
      "properties": {
        "building_ref": {
          "type": "string",
          "description": "对应 schema-community.json 中 BuildingRef.ref 的标识符"
        },
        "gross_floor_area_m2": { "type": "number" },
        "conditioned_floor_area_m2": { "type": "number" },
        "annual": {
          "type": "object",
          "properties": {
            "heating_mwh": { "type": "number" },
            "cooling_mwh": { "type": "number" },
            "electricity_mwh": { "type": "number" },
            "dhw_mwh": { "type": "number" },
            "total_mwh": { "type": "number" }
          },
          "required": ["heating_mwh", "cooling_mwh", "electricity_mwh", "dhw_mwh"]
        },
        "peak_heating_kw": { "type": "number" },
        "peak_cooling_kw": { "type": "number" }
      },
      "required": ["building_ref", "annual"],
      "additionalProperties": false
    },

    "AggregatedEnergyDemand": {
      "type": "object",
      "properties": {
        "total_buildings": { "type": "integer", "minimum": 0 },
        "total_gfa_m2": { "type": "number" },
        "total_conditioned_m2": { "type": "number" },
        "total_heating_mwh": { "type": "number" },
        "total_cooling_mwh": { "type": "number" },
        "total_electricity_mwh": { "type": "number" },
        "total_dhw_mwh": { "type": "number" },
        "total_energy_mwh": { "type": "number" },
        "energy_use_intensity_kwh_m2": { "type": "number" }
      },
      "required": ["total_buildings", "total_energy_mwh"],
      "additionalProperties": false
    },

    "CommunityEnergyDemand": {
      "type": "object",
      "allOf": [
        { "$ref": "#/$defs/_IdentifiedObject" },
        {
          "type": "object",
          "properties": {
            "type": { "const": "CommunityEnergyDemand" },
            "buildings": {
              "type": "array",
              "items": { "$ref": "#/$defs/BuildingEnergyDemand" },
              "description": "每栋建筑的年度用能需求明细"
            },
            "aggregated": {
              "$ref": "#/$defs/AggregatedEnergyDemand",
              "description": "社区聚合指标"
            }
          },
          "required": ["type"],
          "additionalProperties": false
        }
      ]
    },

    "DistrictEnergy": {
      "type": "object",
      "allOf": [
        { "$ref": "#/$defs/_IdentifiedObject" },
        {
          "type": "object",
          "properties": {
            "type": { "const": "DistrictEnergy" },
            "plants": {
              "type": "array",
              "items": { "$ref": "#/$defs/Plant" }
            },
            "networks": {
              "type": "array",
              "items": { "$ref": "#/$defs/Network" }
            },
            "connections": {
              "type": "array",
              "items": { "$ref": "#/$defs/BuildingConnection" }
            },
            "demand": {
              "$ref": "#/$defs/CommunityEnergyDemand",
              "description": "区域能源系统的负荷输入（来自建筑需求模拟）"
            },
            "supply_temperature_hw_c": {
              "type": "number",
              "description": "供热管网设计供温"
            },
            "return_temperature_hw_c": {
              "type": "number",
              "description": "供热管网设计回温"
            },
            "supply_temperature_chw_c": {
              "type": "number",
              "description": "供冷管网设计供温"
            },
            "return_temperature_chw_c": {
              "type": "number",
              "description": "供冷管网设计回温"
            }
          },
          "required": ["type"],
          "additionalProperties": false
        }
      ]
    }
  }
}