1.0 - (JSON) Schemas for input and output definitions for

[avillar]

We are looking into how to define schemas as Building Blocks that can be used as part of input / output definitions in OGC API - Processes implementations. The problem is that we’re finding conflicting information on what those schemas should look like:

• The 1.0 spec says that JSON Schema is used for this (the "JSON Schema" link points to Draft 2020-12).
  • But then it goes on to say (Req. 49.B) "The value of the schema parameter SHALL be a JSON fragment that validates according to the JSON Schema: schema.yaml" (see next bullet point).
• The schemas inside https://schemas.opengis.net/ogcapi/processes/ contain their own "meta schema" definition: see how inputDescription.yaml references schema.yaml, which looks a lot like the OpenAPI 3.0 Schema Object definition ("nullable", "readOnly", "writeOnly").

2.0 seems to support Draft 2020-12 completely (the schema $ref even points directly to the 2020-12 meta schema), so this a 1.0 issue only.

Could the spec be amended so that it says something like "an extended subset of JSON Schema" (which is the language OpenAPI 3.0 uses), or schema.yaml extended to include support for Draft 2020-12?

CC: @rob-metalinkage

[jerstlouis]

@avillar I've just updated the 2.0 draft schemas to use an embedded schema.yaml again, while the reference to JSON Schema is commented out.

While conceptually a full JSON Schema is allowed (for both 1.0 and 2.0 I think) in the input and output description:

• we cannot reference the official JSON Schema directly within an OAS 3.0 definition, since it doesn't fully support JSON Schema,
• even an OAS3 subset of JSON Schema might have issues with some tools that don't handle recursive schemas well like SwaggerUI

[rob-metalinkage]

Is this a use case for bundling... something the building blocks can do to provide multiple implementations as required.

What is the actual "ready to use" preferred option?

[jerstlouis]

@rob-metalinkage

What is the actual "ready to use" preferred option?

I think that really depends on how implementers wish to use the building blocks...

In the current way we prepare our own server's API definition combining several OGC APIs, we need the individual paths, parameters, responses, schemas and high level definition that we can then easily combine together and then bundle ourselves, and we're still using OAS 3.0.

From the building blocks registry perspective, you might have some capability to translate things, but I'm not sure what could serve as the backend semantic encodings to describe all of this.

[rob-metalinkage]

We have introduced a "pluggable transform" option - https://ogcincubator.github.io/bblocks-docs/create/transforms

At the moment this is per building block - but we could have a transformer pattern for bundling. Or we could think of bundling as a special case - like validation and transforms. @avillar ?

Building Blocks encapsulate "hard" bundling challenges - primarily this was necessary to deal with the challenges of bundling JSON-LD contexts within the constraints of OGC packaging structures such as GeoJSON and FSON-FG - but it principle could be applied to any bundling logic that could or should be re-used.

So if you have any (or would like to have) scripts for validation, transformation or bundling these could be included in the FAIR Building Blocks documentation support for the specification.

For example there is a schema flattening tool provided by the community here: opengeospatial/bblocks-template#8