{"$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":{}}}}}