{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://opencitytwin.org/schema/city-model/v0.json",
  "title": "OpenCityTwin City Semantic Model",
  "description": "Lightweight, open, evidence-first representation of a city. Transforms documents, open data and maps into entities and relations that can be placed on a map and queried by AI. Every important fact is traceable to a source. JSON-LD compatible (see @context).",
  "version": "0.1.0",
  "type": "object",
  "required": ["model_version", "city", "sources", "entities"],
  "additionalProperties": false,
  "properties": {
    "@context": {
      "description": "Optional JSON-LD context for interoperability. Default points at the OpenCityTwin vocabulary.",
      "type": ["string", "object"],
      "default": "https://opencitytwin.org/context/v0.jsonld"
    },
    "model_version": {
      "description": "Version of the City Semantic Model spec this instance conforms to.",
      "type": "string",
      "const": "0.1.0"
    },
    "city": { "$ref": "#/$defs/City" },
    "sources": {
      "description": "Registry of every source feeding the model. Entities cite these by id. This is the backbone of the evidence-first principle.",
      "type": "array",
      "items": { "$ref": "#/$defs/Source" }
    },
    "entities": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "zones": { "type": "array", "items": { "$ref": "#/$defs/Zone" } },
        "projects": { "type": "array", "items": { "$ref": "#/$defs/Project" } },
        "services": { "type": "array", "items": { "$ref": "#/$defs/PublicService" } },
        "problems": { "type": "array", "items": { "$ref": "#/$defs/UrbanProblem" } },
        "indicators": { "type": "array", "items": { "$ref": "#/$defs/Indicator" } }
      }
    },
    "layers": {
      "description": "Thematic / modeling layers (traffic flow, accessibility, bike network, etc.) as GeoJSON FeatureCollections. This is how modeling outputs are carried and rendered on the map.",
      "type": "array",
      "items": { "$ref": "#/$defs/ThematicLayer" }
    },
    "generated": { "$ref": "#/$defs/GenerationMeta" }
  },

  "$defs": {
    "ThematicLayer": {
      "description": "A modeling / thematic layer: a GeoJSON FeatureCollection plus how to read and render it.",
      "type": "object",
      "required": ["id", "kind", "name", "geojson"],
      "additionalProperties": false,
      "properties": {
        "id": { "$ref": "#/$defs/Id" },
        "kind": {
          "type": "string",
          "enum": ["traffic_flow", "accessibility", "bike_network", "pedestrian_zone",
                    "transit_network", "parking", "safety", "emissions", "other"]
        },
        "name": { "type": "string" },
        "description": { "type": ["string", "null"] },
        "value_field": {
          "type": ["string", "null"],
          "description": "Feature property holding the magnitude used for styling (e.g. 'flow', 'minutes')."
        },
        "unit": { "type": ["string", "null"] },
        "provenance": { "$ref": "#/$defs/Provenance" },
        "geojson": {
          "description": "A GeoJSON FeatureCollection (WGS84). Kept permissive on purpose.",
          "type": "object",
          "required": ["type", "features"],
          "properties": {
            "type": { "const": "FeatureCollection" },
            "features": { "type": "array" }
          }
        }
      }
    },

    "City": {
      "type": "object",
      "required": ["id", "name"],
      "additionalProperties": false,
      "properties": {
        "id": { "$ref": "#/$defs/Id" },
        "name": { "type": "string" },
        "country": { "type": "string", "description": "ISO 3166-1 alpha-2, e.g. RO." },
        "admin_level": { "type": "string", "description": "e.g. municipality, town, commune." },
        "population": { "type": ["integer", "null"], "minimum": 0 },
        "centroid": { "$ref": "#/$defs/Point" },
        "bbox": {
          "description": "[minLon, minLat, maxLon, maxLat] (WGS84).",
          "type": "array",
          "items": { "type": "number" },
          "minItems": 4,
          "maxItems": 4
        },
        "crs": { "type": "string", "default": "EPSG:4326" },
        "provenance": { "$ref": "#/$defs/Provenance" }
      }
    },

    "Source": {
      "description": "A document, dataset or map layer the model was built from.",
      "type": "object",
      "required": ["id", "type", "title"],
      "additionalProperties": false,
      "properties": {
        "id": { "$ref": "#/$defs/Id" },
        "type": {
          "type": "string",
          "enum": ["document", "open_data", "map_layer", "api", "manual", "other"]
        },
        "title": { "type": "string" },
        "url": { "type": ["string", "null"], "format": "uri" },
        "publisher": { "type": ["string", "null"] },
        "published": { "type": ["string", "null"], "description": "ISO date or year." },
        "retrieved": { "type": ["string", "null"], "format": "date" },
        "license": { "type": ["string", "null"] },
        "format": { "type": ["string", "null"], "description": "e.g. pdf, geojson, csv, wms." }
      }
    },

    "Zone": {
      "description": "An urban zone: neighbourhood, district, sector or any area unit.",
      "type": "object",
      "required": ["id", "type", "name"],
      "additionalProperties": false,
      "properties": {
        "id": { "$ref": "#/$defs/Id" },
        "type": { "const": "zone" },
        "name": { "type": "string" },
        "geometry": { "$ref": "#/$defs/Geometry" },
        "tags": { "type": "array", "items": { "type": "string" } },
        "provenance": { "$ref": "#/$defs/Provenance" },
        "zone_type": {
          "type": ["string", "null"],
          "description": "e.g. residential, industrial, historic, mixed, green."
        },
        "population": { "type": ["integer", "null"], "minimum": 0 },
        "risk_level": { "$ref": "#/$defs/Severity" },
        "relations": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "contains_projects": { "$ref": "#/$defs/IdList" },
            "has_problems": { "$ref": "#/$defs/IdList" },
            "has_services": { "$ref": "#/$defs/IdList" },
            "measured_by_indicators": { "$ref": "#/$defs/IdList" }
          }
        }
      }
    },

    "Project": {
      "description": "A planned or ongoing urban project. Not a paragraph in a PDF, but a structured entity.",
      "type": "object",
      "required": ["id", "type", "name"],
      "additionalProperties": false,
      "properties": {
        "id": { "$ref": "#/$defs/Id" },
        "type": { "const": "project" },
        "name": { "type": "string" },
        "geometry": { "$ref": "#/$defs/Geometry" },
        "tags": { "type": "array", "items": { "type": "string" } },
        "provenance": { "$ref": "#/$defs/Provenance" },
        "status": {
          "type": ["string", "null"],
          "enum": ["proposed", "planned", "in_progress", "completed", "cancelled", null]
        },
        "budget": { "$ref": "#/$defs/Money" },
        "deadline": { "type": ["string", "null"], "description": "ISO date or free text term." },
        "objectives": { "type": "array", "items": { "type": "string" } },
        "relations": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "affects_zones": { "$ref": "#/$defs/IdList" },
            "addresses_problems": { "$ref": "#/$defs/IdList" }
          }
        }
      }
    },

    "PublicService": {
      "description": "A public service facility: school, clinic, transport stop, utility, etc.",
      "type": "object",
      "required": ["id", "type", "name"],
      "additionalProperties": false,
      "properties": {
        "id": { "$ref": "#/$defs/Id" },
        "type": { "const": "service" },
        "name": { "type": "string" },
        "geometry": { "$ref": "#/$defs/Geometry" },
        "tags": { "type": "array", "items": { "type": "string" } },
        "provenance": { "$ref": "#/$defs/Provenance" },
        "service_type": {
          "type": ["string", "null"],
          "description": "e.g. education, health, transport, water, energy, waste, green."
        },
        "capacity": { "type": ["number", "null"] },
        "capacity_unit": { "type": ["string", "null"] },
        "address": { "type": ["string", "null"] },
        "has_deficit": { "type": ["boolean", "null"] },
        "relations": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "serves_zones": { "$ref": "#/$defs/IdList" }
          }
        }
      }
    },

    "UrbanProblem": {
      "description": "An identified urban problem, pressure or risk.",
      "type": "object",
      "required": ["id", "type", "name"],
      "additionalProperties": false,
      "properties": {
        "id": { "$ref": "#/$defs/Id" },
        "type": { "const": "problem" },
        "name": { "type": "string" },
        "geometry": { "$ref": "#/$defs/Geometry" },
        "tags": { "type": "array", "items": { "type": "string" } },
        "provenance": { "$ref": "#/$defs/Provenance" },
        "category": {
          "type": ["string", "null"],
          "description": "e.g. mobility, climate, services, housing, environment, safety."
        },
        "severity": { "$ref": "#/$defs/Severity" },
        "relations": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "affects_zones": { "$ref": "#/$defs/IdList" },
            "addressed_by_projects": { "$ref": "#/$defs/IdList" }
          }
        }
      }
    },

    "Indicator": {
      "description": "A measured value that characterises a zone or the city and justifies decisions.",
      "type": "object",
      "required": ["id", "type", "name"],
      "additionalProperties": false,
      "properties": {
        "id": { "$ref": "#/$defs/Id" },
        "type": { "const": "indicator" },
        "name": { "type": "string" },
        "geometry": { "$ref": "#/$defs/Geometry" },
        "tags": { "type": "array", "items": { "type": "string" } },
        "provenance": { "$ref": "#/$defs/Provenance" },
        "value": { "type": ["number", "string", "null"] },
        "unit": { "type": ["string", "null"] },
        "period": { "type": ["string", "null"], "description": "ISO date, year or range." },
        "relations": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "measures_zones": { "$ref": "#/$defs/IdList" }
          }
        }
      }
    },

    "Provenance": {
      "description": "Links a fact to its sources, separates fact from assumption, and records confidence. Core of evidence-first AI.",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "sources": {
          "description": "Ids of Source entries supporting this entity/fact.",
          "$ref": "#/$defs/IdList"
        },
        "excerpts": {
          "description": "Optional verbatim snippets (with source id) that ground the extraction.",
          "type": "array",
          "items": {
            "type": "object",
            "required": ["source", "text"],
            "additionalProperties": false,
            "properties": {
              "source": { "$ref": "#/$defs/Id" },
              "text": { "type": "string" },
              "locator": { "type": ["string", "null"], "description": "e.g. page 12, section 3.2." }
            }
          }
        },
        "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
        "is_assumption": {
          "type": "boolean",
          "default": false,
          "description": "True when the value is inferred by AI rather than stated in a source."
        },
        "note": { "type": ["string", "null"] }
      }
    },

    "GenerationMeta": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "generator": { "type": "string", "description": "Tool/model that produced this model." },
        "generated_at": { "type": ["string", "null"], "format": "date-time" },
        "data_gaps": {
          "description": "Explicit list of what is missing. A first-class citizen, not a footnote.",
          "type": "array",
          "items": { "type": "string" }
        },
        "quality_score": {
          "type": ["number", "null"],
          "minimum": 0,
          "maximum": 1,
          "description": "Overall data-quality / completeness score for this twin."
        }
      }
    },

    "Id": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9_-]*:[a-z0-9][a-z0-9_-]*$",
      "description": "Namespaced, human-readable identifier: <kind>:<slug>, e.g. zone:centru-istoric, project:pietonalizare-cetate, src:osm."
    },
    "IdList": { "type": "array", "items": { "$ref": "#/$defs/Id" } },

    "Severity": {
      "type": ["string", "null"],
      "enum": ["low", "medium", "high", "critical", null]
    },

    "Money": {
      "type": ["object", "null"],
      "required": ["amount", "currency"],
      "additionalProperties": false,
      "properties": {
        "amount": { "type": "number", "minimum": 0 },
        "currency": { "type": "string", "description": "ISO 4217, e.g. EUR, RON." }
      }
    },

    "Point": {
      "type": ["object", "null"],
      "required": ["type", "coordinates"],
      "additionalProperties": false,
      "properties": {
        "type": { "const": "Point" },
        "coordinates": {
          "type": "array",
          "items": { "type": "number" },
          "minItems": 2,
          "maxItems": 2,
          "description": "[longitude, latitude] (WGS84)."
        }
      }
    },

    "Geometry": {
      "description": "Subset of GeoJSON geometry (WGS84). null when an entity has no spatial footprint yet.",
      "type": ["object", "null"],
      "required": ["type", "coordinates"],
      "properties": {
        "type": {
          "type": "string",
          "enum": ["Point", "LineString", "Polygon", "MultiPoint", "MultiLineString", "MultiPolygon"]
        },
        "coordinates": {}
      }
    }
  }
}