Issues with process definition input/output models
jkeifer opened this issue · comments
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
andadditionalItems
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.
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).
@fmigneault is this issue resolved by #371 ?
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.