Avoiding duplications for the JSON schema and implementations
javagl opened this issue · 5 comments
The 3D Metadata Specification describes a standard format for metadata. This specification itself does not define a certain serialization format for the metadata schema. This is left to the implementations of the 3D Metadata Specification.
Currently, there are two implementations:
These JSON schemas essentially define the same structure (and intentionally so!). The only difference is that the first one refers to TilesetProperty and the second one refers to glTFProperty as the "root" object (but these, in turn, are also equal except for their name).
The result of this duplication is that clients may be forced to maintain different implementations of the same thing. For example, the code generator that generates the structures for cesium-native from the JSON schema currently generates a Property class in the Cesium3DTiles namespace, and a ClassProperty in the CesiumGltf namespace. (Differences in these classes are due to the use of different states of the schema - that's exactly the point...)
We should try to find a solution that avoids this duplication. There are, roughly speaking, three options:
- Define these strucures only in
3DTILES_metadata, and letEXT_structural_metadatadepend on that - Define these strucures only in
EXT_structural_metadata, let3DTILES_metadatadepend on that - Define these structures independently, and let
EXT_structural_metadataand3DTILES_metadatadepend on that.
For now, this mostly refers to the part of the schema that defines the schema/class/property structures. But there are further duplications on the schema level. For example, the 3DTILES_implicit_tiling propertyTable definition is the same as the EXT_structural_metadata propertyTable definition. This part, in turn, is independent of the schema/class/property part. The trade-off becomes obvious: In order to avoid "all" duplication, it would be necessary to break the specifications down into "atomic building blocks". But maybe we can strike a sensible balance that allows us to specify the respective parts cleanly and without unnecessary duplications and dependencies.
- Define these structures independently, and let
EXT_structural_metadataand3DTILES_metadatadepend on that.
I like this approach the most. Is there precedence for this in the glTF ecosystem? Do any extensions do this?
Also, I assume these schemas would need to be versioned. If the 3D Metadata spec receives a major breaking change update for 3D Tiles 2.0 then 3DTILES_metadata would need to refer to the previous version.
As far as building blocks go, I think the two you identified — schema and property table — are good first candidates.
@javagl I'm thinking about this directory structure for metadata.
- Encodings
- PropertyTable - referenced by Implicit Tiling in 1.1,
3DTILES_implicit_tiling, andEXT_structural_metadata - Should the JSON encoding be a subfolder too? It would simply be
metadataEntity.schema.json
- PropertyTable - referenced by Implicit Tiling in 1.1,
- Schema - referenced by metadata in 1.1,
3DTILES_metadata, andEXT_structural_metadata - Semantics - 3D Metadata Semantics Reference (no change)
- Specification - 3D Metadata Specification (moved from
MetadatatoMetadata/Specification) - Statistics - referenced by metadata in 1.1,
3DTILES_metadata
I think this is a good separation of the metadata building blocks. Each folder would have a README that describes the concept in more detail. The main README would give an overview and link to these other READMEs.
Details about how metadata is actually assigned and used would go in the main 3D Tiles spec.
@javagl and I spoke offline and came up with a new directory structure
specificationREADME.md- includes tileset/tile/content metadata and statistics and references to other foldersMetadataREADME.md- 3D Metadata SpecificationSemanticsReference Implementation(name TBD)PropertyTableSchema
TileFormatsImplicitTilingStyling