Merge Core, Collections (and Queries?) requirements classes

[jerstlouis]

Suggesting to merge those two conformance classes as "Core", since both Core and Collections requirements classes are said to be mandatory. From either an implementation or compliance perspective, it serves no purpose to have them as separate conformance classes.

Expressing a dependency on EDR is currently made more difficult by requiring two dependencies instead of only one.

[chris-little]

@jerstlouis The two conformance classesr are expressing the dependencies on API Common Parts 1 and 2. There are also views expressed in other APIs that there should not be a mandatory dependence on API Common Part 1, so that "building blocks" could sit upon a non-OGC root.
Until there is clarity on the strategic direction, and actual implementations, across a number of OGC APIs, I propose that we leave the two conformance classes as they are now.
Core is meant to refer to the API Common Part 1: Core, not an API EDR core.

[jerstlouis]

Thanks @chris-little.

Core is meant to refer to the API Common Part 1: Core, not an API EDR core.

Ah, that was not clear to me, because both Core and Collections show up in the Mandatory Conformance Classes section, with nothing else. (EDIT: I might have misundestood this, because the Mandatory Conformance class section does say that EDR/Core and EDR/Collections extend the Common conformance classes)

So in a sense our implementation that conforms to Common Part 1: Core's Core conformance class and Part 2: Geospatial Data's Collections conformance class, but does not yet implement EDR queries, could be said to conform to all mandatory conformance classes of EDR, and therefore conform to EDR? That would seem problematic... (EDIT: Probably not true, because there are at least additional requirements for the Collection description document. Yet that alone would not provide any useful EDR capabiliy)

So the only other conformance class in EDR, other than the OpenAPI 3.0 for the API definition, and the encodings (HTML, GeoJSON, CoverageJSON), is the Queries conformance class (and at least one type of query is required)?

So it seems to me that the "EDR Core" conformance class that I meant to refer to from Processes - Part 3 should then be http://www.opengis.net/spec/ogcapi-edr-1/1.0/conf/queries ?

It is a bit confusing because http://www.opengis.net/spec/ogcapi-edr-1/1.0/conf/core appears in the document, and references http://www.opengis.net/spec/ogcapi-edr-1/1.0/req/core, but that is not described with its own requirement but instead it is mapped to http://www.opengis.net/spec/ogcapi-common-1/1.0/req/core, yet the conformance class also still depends on http://www.opengis.net/spec/ogcapi-common-1/1.0/conf/core.

So if I understand correctly, there are EDR Core and Collections conformance classes, but they both depend on and map to Common Core and Collections? (EDIT: And they specify additional requirements, that at least for Collections have implications for the /collections/{collectionId} response)

There are also views expressed in other APIs that there should not be a mandatory dependence on API Common Part 1, so that "building blocks" could sit upon a non-OGC root.

We did this in Tiles. Specific optional conformance classes express a dependency on Part 1-Core (Dataset TileSets) and Part 2-Collections (GeoData aka Collection TileSets).

The main issue I see (assuming I understand things correctly, which may well not be the case) is that currently EDR does not have a mandatory conformance class besides those from Common.
I would have expected "Queries" to be a mandatory conformance class. And to follow the pattern in most of the APIs, Queries would be the "EDR Core" conformance class, with or without a dependency on OGC API - Common - Part 1: Core's Core and/or a dependency on OGC API - Common - Part 2: Geospatial Data's Collecitons.

To follow the OGC API - Tiles pattern, there could be optional conformance classes called "Dataset Queries" that depends on Common-Part 1, and a "Collection Queries" that depends on Common - Part 2.

Until there is clarity on the strategic direction, and actual implementations, across a number of OGC APIs, I propose that we leave the two conformance classes as they are now.

Agreed, I think the main point is to build that clarity and strategic direction by comparing and building a consensus on a consistent approach.

[jerstlouis]

Sorry I think I was confused both by:

Core is meant to refer to the API Common Part 1: Core, not an API EDR core.

and the fact that all requirements are gathered together in Annex A, which is not the Abstract Tests ( that is Annex B ).

The Mandatory section does mention that EDR Core and EDR Collections conformance classes extend the Common Core and Collections with additional requirements.

What is still not clear to me is what Core, Collections, and Queries each require, and why they are separate conformance classes if conformance to all three is required by an implementation to provide useful functionality (considering that Core and Collections are said to be mandatory).

The structure of the standard makes this difficult for me to figure this out, because all requirements are grouped together in Annex A without context, and there is no dedicated section or sub-section for each conformance class: EDR/Core, EDR/Collections, EDR/Queries.

A lot of the requirements in the "EDR Core" requirements define query parameters and response patterns that are then applied to specific queries of the Queries conformance class. e.g., the z parameter definition and response is defined in EDR Core, but does it apply to anything besides queries defined in Queries conformance class? If not, then would it not be better to have it together with the Queries conformance class?
Yet the abstract test for it is part of B.10. Conformance Class Queries.

I also see some of the abstract tests (like /conf/edr/rc-z-definition) start with /conf/edr and associated requirements by /req/edr/ (while EDR is not a conformance/requirements class), and some like /conf/trajectory do not follow the /conf/{conformanceClass}/{test} TestID pattern.

There are multiple Abstract Tests with both the same ID and same requirement (they at least should have different Test IDs).

What I am hoping to clarify is whether there is any additional new resources defined by the Core and Collections conformance classes, or what additional behavior are required for the resources defined in Common.
e.g., I see that Requirement A.43 requires conformance to a collections.yaml that requires additional members like parameter_names, and A.46 J further emphasizes that specifically.

Something else I notice is that MUST is used in several places in the document (including within requirement text) despite 4. Terms and Definitions saying:

In particular, the word “shall” (not “must”) is the verb form used to indicate a requirement to be strictly followed to conform to this document

wondering where there is a particular reason behind that, or that would just be something correct in a future revision?`

Sorry if I am misunderstand something (or several things) or sounding critical, just hoping to help improve the correctness, clarity and useability of the spec from an implementer's perspective.

Thank you.

cc. @ghobona

[chris-little]

@jerstlouis It's a bit late in the day for me but the key point is that the Query conformance class only requires at least one query, but none are mandatory. So someone could implement a collection that only supported Area queries, and another collection only supported Point queries. Both would be valid API EDR.

The Musts were almost certainly missed typos. In the process of moving from ASCIIDoc to the Metanorma Content Management System, some merged PRs were lost, There may be other typos that we missed.

[jerstlouis]

@chris-little Sorry to stretch your day. To try to summarize the issues and suggestions I described:

Issues

• The Tests, Requirements and Conformance classes identifiers need to be reviewed and corrected, and should be ensured to be within the right conformance/requirements classes. There are several cases where they are not correct.
• MUSTs should be SHALLs
• If the Queries conformance class is necessary to do anything useful with an EDR API, EDR/Queries should be mandatory, and EDR/Core and EDR/Collections should be folded into "EDR/Queries" (the ModSpec actually requires a single mandatory core conformance class)

Suggestions

• It would be extremely useful (in my opinion necessary for procuring EDR implementations in an interoperable manner) to add optional conformance classes that specifically require each particular type of queries
• Dependencies on Common-1 Core and Common-2 Collections could be moved to new optional conformance classes "DataSet Queries" and "Collection Queries", respectively, allowing to use Queries with a non-OGC API root when declaring conformance only to Queries, and not to these.

cc. @m-burgoyne @ghobona

[chris-little]

@jerstlouis We discussed this at the EDR API SWG 87, and we decided not to change at this time. Each collection describes which queries it supports, so we think the extra editorial complication of multiple conformance classes is not helpful to implementors.
The issue of merging Common Core and Common Collection/Geodata conformance classes is a wider cross-API issue, so again we would rather focus on improved functionality rather than "editorial" work.