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 “official validator” for CityJSON is cjio with the operator
If you installed cjio, then the schemas are built-in and can be used readily.
To validate the file twobuilding.json, simply
cjio twobuildings.json validate
Observe that not only the schema was tested, but also the internal consistency of the file was tested. The following were tested:
- Vertex indices coherent
- Specific for CityGroups
- Semantic arrays coherent with geometry
- Root properties
- Empty geometries
- Duplicate vertices
- Orphan vertices
- CityGML attributes
It is possible that the validation returns warnings, eg when an attribute is not an “official” one in the CityGML dataset. It is not considered an error and thus only a warning is raised.
Now download the invalid file twobuilding_invalid.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 14 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
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
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.
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 twobuilding.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: