Defining a schema

Building Blocks can be defined to reuse existing JSON schemas in a more sophisticated way.

A re-used schema can be:

  1. Profiled (by extension or constraints)
  2. Mapped to a semantic (RDF) model allowing richer specification of constraints.
  3. Tested with examples and test cases.

How to reuse

This is simply a matter of referencing the reused schema in the building block schema(.json .yaml): 
{ 
   "$ref": "http://somestablelocation.org/schema.json"
}

How to reuse a building block with its added components…

This is done in a two-step process:

  1. In the bblocks-config.yaml file, tell the processor which building block registers to import:

     imports:
   - default
   - https://opengeospatial.github.io/ogcapi-sosa/build/register.json

    default refers to the main OGC master register of building blocks. See Setting up imports for the full syntax, including URL resolution rules and local URL mappings for testing.

  2. Use the bblocks://{id} syntax as the value of $ref in your schema.

    This means your building block will inherit all JSON-LD contexts and SHACL shapes from the referenced building block automatically and apply during testing.

Profiling JSON Schemas

Profiling JSON schemas is a complex subject. This document is a placeholder for a description of best practices and support tooling.

Two mechanisms are already available for profiling a building block’s schema:

  • The extends property in bblock.json joins this building block’s schema with a base building block’s schema using allOf, optionally inserting it at a specific property path.
  • Extension points (experimental) let you specialize a base building block by constraining specific building blocks it references — including ones referenced transitively through its imports — to a more specific building block, without hand-editing the base schema.

The rest of this section discusses the broader profiling problem and remaining gaps not covered by those mechanisms.

Why is this challenging?

The JSON Schema specification and tooling landscape is complex. Versions of the OpenAPI Specification (OAS) use different versions of JSON-Schema and tool support varies.

In particular, reuse mechanisms such as $dynamicRef may not be available.

Version-agnostic Building Blocks

The Building Block post-processing tooling can generate an OAS 3.0-compatible schema alongside the OAS 3.1 one. It is recommended to develop new building blocks using improved modularity and reuse support in modern schema versions, and allow the Building Block to create a “down-compiled version”.

This down-compiling is disabled by default and must be explicitly enabled by setting schema-oas30-downcompile: true in bblocks-config.yaml:

schema-oas30-downcompile: true

OAS 3.0 Compatibility

OGC APIs are currently bound to OAS v3.0 which limits JSON schema patterns that can be supported.

The implication is that currently it is typical necessary to recreate complex structural hierarchies and compose into “allOf[]” structures in order to place constraints into a location.

e.g. to make the relatively simple constraints that a “SurveyObservationCollection” is a collection “SurveyObservation” objects, and must declare that some schema for describing “SensorType” is used, a significant portion of the structure must be detailed.


"SurveyVectorObsCollection": {
      "allOf": [
        {
          "$ref": "https://opengeospatial.github.io/ogcapi-sosa/build/annotated/unstable/sosa/features/observationCollection/schema.json"
        },
        {
          "properties": {
            "features": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/SurveyVectorObsFeature"
              }
            },
            "properties": {
              "properties": {
                "madeBySensor": {
                  "$ref": "#/$defs/SensorType"
                }
              },
              "required": [
                "madeBySensor"
              ]
            }
          }
        }
      ]
    }
  }

Future options

A number of strategies are being considered to simplify this. At this stage alternative approaches:

  • define a new constraint language that can be directly compiled from simple statements into the target schema constraint
  • use the most compact form in more recent JSON schema - potentially requiring extension hooks in the base schemas - and compile to legacy forms with full structure replication
  • work with JSON schema community to define new capabilities designed for easier profiling in a future version of JSON
  • create a “wizard” tool to write constraints

All these have significant impact and effort implications.

Follow updates at this issue