Validation of a CityJSON file
Table of contents
Validation of a CityJSON dataset means that one must ensure that it respects the standardised specifications and definitions as given in the specifications.
Schema validation (is the syntax of the file OK?)
The JSON schemas of CityJSON can be downloaded, for each version, at https://www.cityjson.org/schemas/. These are based on the JSON Schema project.
To validate a given file you can use any software listed here. However, it is rather tricky to stitch all the schemas together, and the handling of Extensions will not work.
The “official validator” for CityJSON is cjval, which is available as a web-app and with cjio.
To validate the file twobuildings.city.json, simply drag it to https://validator.cityjson.org:
Or alternatively type
cjio twobuildings.city.json validate
Observe that not only the schema was tested, but also the internal consistency of the file was tested. The following were tested:
- JSON syntax
- CityJSON schemas
- Extension schemas
It is possible that the validation returns warnings, eg when there are duplicate vertices, those are not considered errors and thus only a warning is raised.
Now download the invalid file twobuildings_invalid.city.json, and try to validate it. You should get an error that
"CityObjects" is a required property, and that it is missing from the file:
Fixing this is rather easy: remove the space between “City” and “Objects” at line 16 and then the file should be valid.
Geometry (are the geometric primitives valid?)
CityJSON, as is the case for GML, use the ISO 19107 geometric primitives for representing the geometry of its objects: a 0D primitive is a
GM_Point, a 1D a
GM_Curve, a 2D a
GM_Surface, and a 3D a
GM_Solid. A d-dimensional primitive is built with (d-1)-dimensional primitives, e.g. a
GM_Solid is formed by several
GM_Surfaces, which are formed of several
GM_Curves, which are themselves formed of
GM_Point. While the ISO19107 primitives do not need to be linear or planar, i.e. curves defined by mathematical functions are allowed, CityGML uses a subset of ISO19107, with the following two restrictions: (1)
GM_Curves can only be linear (thus only
LinearRings are used); (2)
GM_Surfaces can only be planar (thus
Polygons are used).
Geometric primitives can be combined into either aggregates or composites. An aggregate is an arbitrary collection of primitives of the same dimensionality that is simply used to bundle together geometries, it does not prescribe any topological relationships between the primitives. The
Multi* in CityGML are an example. A composite of dimension d is a collection of d-dimensional primitives that form a d-manifold, which is a topological space that is locally like a d-dimensional Euclidean space. The most relevant example is
CompositeSurface: it is a 2-manifold, or, in other words, a surface embedded in 3D space.
A valid primitive of dimension 3 means that all the lower-dimensional primitives used to represent the primitives are also valid.
To validate the geometric primitives in a CityJSON file, we recommend using val3dity, which is ISO 19017 compliant, free, and open-source.
It suffices to download its latest binary, open a console/terminal/shell and type:
This will read the file and validate one-by-one each of the geometric primitives in the file and produce a summary. If the file twobuildings.city.json is used, then the following should be obtained:
It can be seen that one of the 2 buildings is not valid, because it has duplicate vertices. To know the details, you can produce a report (called
val3dity myfile.json --report myreport.json
Drag this file to the online report browser, and we obtain: