Issues with process definition input/output models

[Jarrett Keifer]

I brought up some aspects of this issue during the recent sprint, but we've run into some issues with the jsonschema models specified for the process definition input/output schemas. A non-exhaustive list of problems I've had:

• no $ properties allowed, beyond $ref: think things like $defs for internal references
• latest jsonschema features like prefixItems and additionalItems not supported
• inability to use an array of types

In short, it seems that the schema model is intended to allow jsonschema models, but isn't actually consistent with the jsonschema meta-schema. And what is supported is not sufficient to model our input payload objects (if you're curious what our models might look like, we have a yaml example here: https://github.com/Element84/swoop/blob/main/swoop-config.yml#L78).

I've been able to work around these problems using references instead of embedding the schemas into the process definition response. It turns out I like this solution better in our case, because we now have the input and output schemas at dedicated endpoints, so we can also reference them from other locations.

That said, I still wanted to create this issue because it seems like the models are artificially limiting by failing to actually express what is allowed by jsonschema. It seems a little bit silly to me to try to maintain a jsonschema meta-schema as part of these API specs, as the maintenance burden seems high.

I wonder if it would be possible to reference some external models from some other source dedicated to maintaining such a meta-schema. Or maybe such a project doesn't exist, it might be better to move the jsonschema models out of this spec and into OGC Common to get more eyes on it and support reuse (and a shared maintenance burden) across specs? Or perhaps it would be better to push people to use references, and add a conformance class for endpoints to retrieve the schemas simply saying that the responses from those endpoints should be type application/schema+json, thus leaving it up to the client to worry about what to do with those responses.

Just some thoughts. Like I said, I've worked around my issues, so if nothing else perhaps this issue is just a helpful suggestion for anyone else ending up in a similar situation as me.

[Francis Charette-Migneault]

As a temporary workaround, $schema: https://json-schema.org/draft/2019-09/schema# should be added at the top of https://github.com/opengeospatial/ogcapi-processes/blob/master/openapi/schemas/processes-core/schema.yaml to make it explicit about which features are currently supported. Features prefixItems and additionalItems are introduced in 2020-12.

Even better would be to completely remove https://github.com/opengeospatial/ogcapi-processes/blob/master/openapi/schemas/processes-core/schema.yaml and use the reference JSON-schema directly to avoid reimplementing the existing specification.

The current definition is still not valid in some cases (see #371).

[Panagiotis (Peter) A. Vretanos]

@fmigneault is this issue resolved by #371 ?

[Francis Charette-Migneault]

I don't think it is completely resolved.
Each schema should define $schema: ... to indicate what features they support/embed.
We could provide a spec-wide "default" for $schema.
There is also the case of inputs[*].schema, which could themselves include a $schema with more specific features.