Fixes for #564 (full alignment of outputs / inputs schemas with maxOccurs) by jerstlouis · Pull Request #566 · opengeospatial/ogcapi-processes

jerstlouis · 2026-03-27T06:54:56Z

This implements the proposed fixes for #564

(please focus on the last commit c426de7 , as this PR is otherwise based on #561 which fixes the validation of the OpenAPI definition)

- Fixed references to non-existing files (e.g., files were renamed to remove "input", rWorkflowNotFound.yaml was never added) - Updated processes-workflows to reflect capabilities now included in Part 1 - Core (Version 2) - pExecution: Part 1 now supports collection output - Adding workflow definitions in schemas - The default example has workflows enabled, and this fixes Swagger Editor errors - NOTE: Additional fixes are needed for `swagger-cli validate` and SwaggerUI to work properly

- This fixes "properties members must be schemas" errors in Swagger Editor - Including CWL definition in schemas (fixes swagger-cli bundle issues in Swagger Editor)

- Referencing online JSON Schema is likely not compatible with OpenAPI 3.0 and causing 'swagger-cli validate' to fail. - Including schema.yaml from https://schemas.opengis.net/ogcapi/dggs/1.0/core/schemas/dggs-json/schema.yaml although we could also go back to the version that was removed in aa202c0 - The $comment is causing Swagger validation to fail - Changing top-level CQL2-JSON to be an arbitrary object (couldn't a CQL2 expression be a function returning bool?) -- also args should have been an array - The examples was causing validation to fail - contentEncoding was causing validation to fail - Additional fixes are needed to avoid errors in Swagger Editor / UI

- The use of $defs in CQL2 schema was causing these Swagger Editor errors: '$ref' value must be an RFC3986-compliant URI reference (now using cql2defs instead of $defs) - With this, Swagger Editor now only reports warnings, but Swagger UI still shows 'invalid' with these errors, related to: - CWL and CQL2 using $schema, $author, $id, $defs, $dynamicAnchors and cql2defs - DRU pDeploy.yaml and pProcessListDeploy.yaml wrongly directly including the processSummary.yaml schema where a response is expected (I'll file a separate issue about this -- it should use an response to be added to responses/processes-dru/ if one does not already exist) { "messages": [ "attribute components.schemas.CWL.$schema is unexpected", "attribute components.schemas.CWL.$author is unexpected", "attribute components.schemas.CWL.$id is unexpected", "attribute components.schemas.CWL.$defs is unexpected", "attribute components.schemas.CQL2.$schema is unexpected", "attribute components.schemas.CQL2.$dynamicAnchor is unexpected", "attribute components.schemas.CQL2.cql2Defs is unexpected", "paths.'/processes'(post).responses.201.$ref target #/components/schemas/processSummary is not of expected type Response" ], "schemaValidationMessages": [ { "level": "error", "domain": "validation", "keyword": "oneOf", "message": "instance failed to match exactly one schema (matched 0 out of 2)", "schema": { "loadingURI": "#", "pointer": "/definitions/Components/properties/schemas/patternProperties/^[a-zA-Z0-9\\.\\-_]+$" }, "instance": { "pointer": "/components/schemas/CQL2" } }, { "level": "error", "domain": "validation", "keyword": "oneOf", "message": "instance failed to match exactly one schema (matched 0 out of 2)", "schema": { "loadingURI": "#", "pointer": "/definitions/Components/properties/schemas/patternProperties/^[a-zA-Z0-9\\.\\-_]+$" }, "instance": { "pointer": "/components/schemas/CWL" } } ] }

…schema

- Fixes #562

pvretano · 2026-03-27T07:07:34Z

As a native speaker of English I can tell you that the name "occurrencesHolder.yaml" is a meaningless name. Please rename the file to "inputOrResultValue.yaml".

jerstlouis · 2026-03-27T07:21:47Z

@pvretano We can discuss what the proper name is, but this name was intended to carry the meaning of "something that holds occurrences" (of an input or result output value) :) Just like a cup holder holds a cup ;)

@fmigneault was strongly objecting to the use of input in the name...

I still think using value in the name is confusing because it might be multiple values (multiple occurrences), and all of the other YAML files with value in the filename are about individual value occurrences (not the holder / shell / input / output / result)

pvretano · 2026-03-27T07:28:32Z

@jerstlouis change the name. It is meaningless and the term occurrence is not used once in the standard. If it can be one or more values then use the plural "values".

jerstlouis · 2026-03-27T07:36:43Z

@pvretano

change the name.

What to? inputOrResultValues.yaml ?

the term occurrence is not used once in the standard.

Independently of what this file is called, in my opinion it would be very useful in the standard to talk about one or more occurences of values (as per minOccurs / maxOcccurs) in the context of the inputs and result outputs to clarify this lingering confusion between the two, explaining it a bit like I did in this comment (EDIT: Sorry I had linked to the wrong comment). This is certainly confusing readers/implementers, but also ourselves in the SWG (as per the JSON Schema clash issue identified by #564).

I suggest to use this as potential inspiration:

There is the input/output which is:

If maxOcccurs = 1: <occurrence>
If maxOccurs > 1: [ <occurrence>, ... ] (empty array allowed as well unless minOccurs > 0)

Where <occurrence> is one of:

{ "value" : ... }
{ "href" : ... }
{ "bbox" : ... }
{ "collection": ... }
a string
a number
true or false
an array
null

There is no confusion about an object defining a "value" property at the top level. That would always be encoded as:
{ "value" : {"value": 123 } }.

pvretano · 2026-03-27T07:39:21Z

@jerstlouis inputOrResultsValues.yaml.

jerstlouis · 2026-03-27T07:41:13Z

@pvretano Now there is an issue with results having an s and input not having one.

This file is about one or more (or 0) values for an individual input or result.

So I'll rename it to inputOrResultValues with no s at result.

pvretano · 2026-03-27T07:41:42Z

@jerstlouis fine...

jerstlouis · 2026-03-27T07:48:12Z

@pvretano Done. Thanks. See 5a666d0 .

- Synced with latest Common - Part 2

- Related to #562

- The draft only has `[ collection ]` in https://docs.ogc.org/DRAFTS/18-062r3.html#req_collection-output_response-definition[Requirement 62] - If necessary, the results.yaml approach can return multiple output collections, or multiple collections per output

fmigneault · 2026-03-28T00:57:02Z

So is it a good time to say that, including Part 3: Workflows, inputOrResultValues.yaml now is ambiguous, since it should be inputOrResultValues-OrProcess-OrParamerized.yaml because they can be nested?

inputOrResultValues-workflows.yaml is not that much more communicating the variants.

(my reasoning for making it abstract, but I didn't want to bring up too many extra concepts simultaneously until the first batch of renames were addressed)

jerstlouis · 2026-03-28T01:42:34Z

@fmigneault

A nested process or a parameterized input ($input) would still be an input value to the process that receives it, so the name still fits.

The only thing is that inputParameterized and inputOrResultValues-workflows are only used for inputs, not for results, so we could potentially rename that one to simply inputValues-workflows.yaml, or keep like this to more easily see the relationship to the no-workflows version.

fmigneault · 2026-03-28T02:46:39Z

Good point. Fair enough. It highlights even more why they must be the same "value container" structure in this case!

pvretano · 2026-03-28T17:00:25Z

Guys, are you serious now? We don't need long sentence like-file names! Even "inputOrResultValues.yaml" is too long but it is a sight better than "occuranceHolder.yaml" ... What is this? Dungeon & Dragons!?

Just call the file "values.yaml" and let the context dictate whether it is an input value, a result value, a nested value in a workflow or whatever. I want these PR's either merged or discarded on Monday so that I can complete my PRs so that we can get on with the RFC.

fmigneault · 2026-03-29T16:49:21Z

Just call the file "values.yaml" and let the context dictate whether it is an input value, a result value, a nested value

I agree with this. A simple values.yaml is what I've proposed since the start.

jerstlouis · 2026-03-30T01:10:46Z

@fmigneault @pvretano If you both want me to rename inputOrResultValues.yam to values.yaml in this PR and that will help agreeing to merge this PR tomorrow I'm happy to change it.

As long as we all remember (from this epic Dungeons & Dragons adventure ;)) that values.yaml is the shell / holder / container, while all the other files with value in them are for the individual values occurring zero, once, or multiple times inside that container.

pvretano · 2026-03-30T01:16:33Z

@jerstlouis make the change.

jerstlouis · 2026-03-30T01:34:08Z

@fmigneault @pvretano Done. Thanks!

…ecution request - Fixes #564 - This avoids the need to use qualified array elements at a level which clashes with the process description schemas for individual input/output occurrences - Output description can now specify minOccurs / maxOccurs - For outputs where maxOccurs > 1, a single output still needs to be enclosed within [ ] (exactly like inputs) - input.yaml is renamed to values.yaml and used directly by both execution requests input (execute.yaml), and results.yaml outputs - output.yaml is renamed to outputSelection.yaml to clarify that the execution request selects outputs to return and their format and this schema does not define an actual output returned by a process - inputValue.yaml is renamed to value.yaml because it's also for outputs - valueNoObject.yaml is reverted to exactly what it was in 1.0, fixing the clash with the JSON Schema - There are two versions of several of these files depending on whether Part 3: Workflows is used or not (Part 3 allows for additional "$input" placeholder (inputParameterized.yaml) for the purpose of defining a workflow) - This is currently implemented on top of PR #561 fixing validation issues with the OpenAPI definition

pvretano

As a native English speaker I can tell you that the name "occurencesHolder.yaml" is completely meaningless. The term "occurrence" is not used in the text of the standard. Please rename the file to "inputOrResultValue.yaml" (or Values if plural makes more sense).

…currences.yaml

jerstlouis added 11 commits March 19, 2026 01:15

openapi/ogcapppkg.yaml: Fixed broken required

ad8f730

openapi/dru: Changing from GitHub to w3id.org CWL schemas

be056ac

- This fixes "properties members must be schemas" errors in Swagger Editor - Including CWL definition in schemas (fixes swagger-cli bundle issues in Swagger Editor)

openapi: Updated bundled example

8a69bf6

openapi:valueNoObject-workflows: Fixed oneOf -> anyOf

3db1f04

openapi: Attempt to fix SwaggerUI validations errors related to CQL2 …

bfd3f81

…schema

openapi: Embedding CWL JSON Schema to avoid SwaggerUI errors

4d29f01

DRU: Initial fix for processSummary.yaml included directly as response

79a77cc

- Fixes #562

Attempt to port CWL JSON Schema to OAS 3

3be43b8

jerstlouis requested review from gfenoy and pvretano March 27, 2026 06:54

jerstlouis added 2.0 Next development iteration Part 1 (Core) OGC API - Processes - Part 1: Core labels Mar 27, 2026

jerstlouis added this to OGC API Processes - Part 1: Core (editor's draft) Mar 27, 2026

jerstlouis force-pushed the fix564 branch from 102713e to 46416c0 Compare March 27, 2026 07:01

jerstlouis force-pushed the fix564 branch from 46416c0 to 1740200 Compare March 27, 2026 07:13

jerstlouis force-pushed the fix564 branch from 1740200 to 529c7b7 Compare March 27, 2026 07:47

jerstlouis added 3 commits March 27, 2026 03:57

Additional fixes solving CQL2 and Common errors

70e5de2

- Synced with latest Common - Part 2

openapi (DRU): Add dedicated rProcessSummary response

29e924d

- Related to #562

ppenapi: Change version to 2.0rc1

1540ddc

jerstlouis force-pushed the fix564 branch from 529c7b7 to 30858c9 Compare March 27, 2026 07:58

jerstlouis force-pushed the fix564 branch from 30858c9 to 5a666d0 Compare March 27, 2026 08:05

jerstlouis mentioned this pull request Mar 28, 2026

Do we really want to allow qualifying array elements INSIDE an input/output occurrence? #564

Closed

jerstlouis force-pushed the fix564 branch from 5a666d0 to 61da79e Compare March 30, 2026 01:31

jerstlouis force-pushed the fix564 branch from 61da79e to c426de7 Compare March 30, 2026 03:07

pvretano approved these changes Mar 30, 2026

View reviewed changes

openapi: Moving common schema and min/maxOccurs to shared schemaAndOc…

421fd51

…currences.yaml

jerstlouis force-pushed the fix564 branch from 1630cf8 to 421fd51 Compare March 31, 2026 02:03

jerstlouis merged commit 421fd51 into master Mar 31, 2026

Conversation

jerstlouis commented Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pvretano commented Mar 27, 2026

Uh oh!

jerstlouis commented Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pvretano commented Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jerstlouis commented Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pvretano commented Mar 27, 2026

Uh oh!

jerstlouis commented Mar 27, 2026

Uh oh!

pvretano commented Mar 27, 2026

Uh oh!

jerstlouis commented Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fmigneault commented Mar 28, 2026

Uh oh!

jerstlouis commented Mar 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fmigneault commented Mar 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pvretano commented Mar 28, 2026

Uh oh!

fmigneault commented Mar 29, 2026

Uh oh!

jerstlouis commented Mar 30, 2026

Uh oh!

pvretano commented Mar 30, 2026

Uh oh!

jerstlouis commented Mar 30, 2026

Uh oh!

pvretano left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jerstlouis commented Mar 27, 2026 •

edited

Loading

jerstlouis commented Mar 27, 2026 •

edited

Loading

pvretano commented Mar 27, 2026 •

edited

Loading

jerstlouis commented Mar 27, 2026 •

edited

Loading

jerstlouis commented Mar 27, 2026 •

edited

Loading

jerstlouis commented Mar 28, 2026 •

edited

Loading

fmigneault commented Mar 28, 2026 •

edited

Loading