CityJSON/ciutyGML Joins Smart Data Models: 33 Candidate Models for 3D City Objects

Smart Data Models’ Candidates repository now includes a new candidate standard, cityjson-v2, translated from CityJSON v2.0.2 — a JSON encoding of a subset of the OGC CityGML data model for 3D city models. All 33 core City Object types defined in cityjson/specs‘ schemas/cityobjects.schema.json now have an NGSI-LD / NGSI-v2 representation.

What’s in it

Every model ships the full set of Candidates artifacts: a JSON Schema, an NGSI-LD @context, and all four example serializations (NGSI-v2 and NGSI-LD, key-values and normalized) — each validated against its own schema.

Built from real JSON Schema, mechanically — attributes included

Unlike some other Candidates translations that had to work from prose documentation pages, CityJSON ships genuine machine-readable JSON Schema files (schemas/cityjson.schema.json, cityobjects.schema.json, geomprimitives.schema.json, …). This translation parsed those directly, which surfaced a structural fact worth calling out: CityJSON’s own schema deliberately leaves attributes open on every City Object type ({"type": "object"}, no fixed sub-schema) — it defers attribute content to convention rather than declaring it.

That convention is CityGML’s own data model, so this candidate goes one step further and cross-references the actual OGC CityGML 3.0 XML Schema to promote real, typed, documented properties in place of the open bag: coded classification fields (class, function, usage, roofType), storey counts and heights, a qualified height structure (CityGML 3.0’s structured replacement for the classic flat measuredHeight), vegetation attributes (species, trunkDiameter, crownDiameter, …), and three real closed enumerations resolved directly from the XSD (conditionOfConstruction, height[].status, trafficDirection). Every model keeps a residual genericAttributes property too — but that maps to CityGML’s own formal generic-attribute extension mechanism, not an invented catch-all.

Three modeling decisions were made deliberately, not incidentally:

• Geometry is flattened per Level of Detail. CityJSON stores vertices once in a document-level shared array and each Geometry entry references them by index, with an independent LoD per entry (a City Object can carry several simultaneously). Each model exposes up to four GeoProperties — geometryLoD0 through geometryLoD3 — holding real, dereferenced GeoJSON coordinates for whichever LoD the source data provides. Solid/MultiSolid primitives (CityJSON’s 3D volumes) are simplified to GeoJSON MultiPolygon, since GeoJSON has no native 3D solid type; surface semantics, material, and texture metadata is not carried into the GeoProperty.
• No invented RDF vocabulary. CityJSON, unlike an OWL ontology, doesn’t publish per-property IRIs. Structural context.jsonld entries (geometry, parents/children, …) mint IRIs under CityJSON’s own schema $id namespace; the newly-promoted typed attributes mint IRIs under each model’s real CityGML 3.0 module XML namespace instead — both documented as conventions, not presented as something either spec formally declares at that exact granularity.
• Coded values stay open. gml:CodeType attributes (class, function, usage, roofType, species) are typically drawn from OGC-published code lists; those lists weren’t resolved to closed enums in this pass, so these remain open strings with a note — a documented follow-up, not a silent gap.

Note on scope

This candidate covers CityJSON, which is explicitly documented as “a subset of the OGC CityGML data model” — not the full CityGML standard (a separate XML/GML/UML specification with its own ADE extension mechanism and modules CityJSON doesn’t carry). If full CityGML fidelity is needed, that’s a distinct, larger translation task from a different source spec.

Try it, and tell us what’s missing

This is a Candidate — a first, carefully-sourced translation, not yet promoted to an official Smart Data Models subject. Before that step:

• Overlap with existing Smart Data Models building-related subjects hasn’t been checked in detail.
• License terms (CC0-1.0 per the specs repo’s own LICENSE file) should be reconfirmed for the specific release before promotion.
• CityGML’s own code lists (schemas.opengis.net/citygml/codelists/) aren’t cross-referenced yet — resolving them would turn the remaining open class/function/usage/roofType/species strings into real closed enums, the same way conditionOfConstruction/trafficDirection already are.

Browse the models, open an issue, or send a PR: 👉 https://github.com/smart-data-models/Candidates/tree/master/standards/cityjson-v2