General Conformance Class

[cmheazel]

Per the discussion at the SWG meeting this morning:

1. The July 2020 branch has been merged into Master. This will serve as the baseline for the upcoming API Sprints
2. A new August 2020 branch has been created
3. August 2020 introduces the concept of a Web API Module, provides a definition of the term, and adds it as a second standardization target for API-Common.
4. August 2020 separates out the general requirements into a new requirements class. (the ATS has not been updated yet).

A Web API is a full implementation. It includes the landing page, conformance, api definition, and everything else you would want in an operational Web API.
A Web API Module is a reusable software module which can be used to build a Web API. A Python library, for example, may include OGC conformant modules, but in itself is not an API.

Standardization targets:
General: Web API and Web API Modules
Core: Web API
HTML: Web API and Web API Modules
JSON: Web API and Web API Modules
OpenAPI: Web API

Your Python library would have to demonstrate conformance with the General conformance class, but not the core. Your API implementation would have to demonstrate conformance to both.

Conformance with the General requirements class has been added as a requirement for the Core requirements class.

[bradh]

Can you clarify what "library" means here? Does this have client side intent? What does the ETS look like in either server or client side cases, as applicable?

[cmheazel]

A library is packaged source or object code provided to a developer as part of the software development environment. The Java JDK for example. Or GDAL.
A library should contain modules to support both sides of the interface. It's up to the developer to use the library modules which best suite their requirements.
For the server-side ETS, we would need an OGC API test harness into which the module would be installed. Then we would test it the same as an API. Since the test harness is conformant by definition, the tests would focus on the functionality provided by the module.
For the client-side ETS we would need a conformant reference implementation. The client would be exercised against that reference implementation.

[bradh]

I assume the JDK part was meant to be approximate - we wouldn't actually expect an OGC API reference in the JDK distribution. I could see it as something like geotools, where its a jar. However the distinction is subtle, because that jar could be a server or a library. So its really about the intended conformance target.

There is a possible unintended consequence here, where its only possible for a library to be certified if there is an already-compliant test harness. That means that the first test harness language will likely collect all of the reference implementation "slots".

It might also need some clarification of OGC rules on conformance, since this is pushing beyond the traditional "test the server as a product" or "check the output file" approaches that OGC has used in the past. In the GDAL example, if the test harness is in python, then does a "pass" using the python bindings for GDAL mean that the underlying C/C++ implementation is certified? Does that read across to other bindings (e.g. Java, or C#)?

Overall, I think this is a good move forward (closer to reflecting modern software development practice). Its new ground though.

[cportele]

I still do not understand the "module"/"library" concept. If the General requirements are (also) written for a Web API they are written for HTTP and not any other library binding. I look forward to see the text proposal.

[cmheazel]

@cportele I don't understand the question. HTTP is a protocol. It runs over the wire. A library is a software package. It is used by software developers.

[cportele]

@cmheazel Exactly. A requirement that is written for HTTP / a Web API will differ from a requirement written for a software library. These are different standardization targets, so "Web API and Web API Modules" as a standardization target does not make sense to me.

[bradh]

If I understood the intention, then the library would be tested in the same way as the product with all the adaptation done by a test harness.

That would mandate a specific API to be provided by the library under test. Is that the intent?

[cmheazel]

@cportele How about "Web API" and "Web API Modules"? Two different standardization targets.
The ETS would be the same for both. The difference is that a "Web API" is a fully integrated service while a "Web API Module" must be integrated into our API Test Harness. The certification you receive for your product would depend on the standardization target.
@bradh the test harness is the hard bit. Our standards address the protocol between components. There are no plans that I know of to develop software APIs (GeoAPI being the exception). Developing a test harness which is both functional and easy to use will be challenging.

[cportele]

How about "Web API" and "Web API Modules"? Two different standardization targets.

So these are then two separate requirements classes with different requirements, one set for HTTP and one set for XYZ.

I propose we wait with discussing this further until you have a draft that makes it clearer.

[cmheazel]

@cportele That would be the August 2020 branch of API-Common Core.

[cportele]

@cmheazel - I had a look and this confirms my confusion. I do not see how this could work. Let's take one normative statement as an example:

The API SHALL conform to HTTP over TLS.

This works for the standardization target "Web API", but not for "Web API Module". The requirement applies only to an API and a Web API Module is not an API. It is - according to the definition - "a reusable software module which can be used to build an implementation of a Web API", which is something completely different. My JAR file will never be able to conform to this requirement, because I cannot use HTTP to talk to the API.

If there is a need for requirements classes for software libraries

• the requirements need to be phrased differently so that the subject of the requirement is the standardization target (the library) plus they need to be testable for that target, and
• this needs to be a separate requirements class.

I basically see two options for "library" requirements classes:

• Standardize an API each for, say, Java, JavaScript, Phyton, etc.
• Simply require that the library can be used to set up a Web API that conforms to conformance class XYZ.

The second option is what we already have as this is what CITE currently tests, so that is not needed.

The first option is obviously not what you have in mind, if the current August 2020 branch content is meant to clarify the proposal.

So, I am still confused and do not understand the idea of the "Web API Module" target.

[cmheazel]

@cportele So forget the word "library". It only appears once in the spec, and this is in my proposed definition for Web API Module.

Consider the idea of modular Web APIs. To build a Web API, I would start with a foundation consisting only of the common core. I would then add Common-GeospatialData, then Coverages, then Maps, then Tiles, and so on. It would be nice if I could get conformant modules from different sources and just plug them all together. But, while a Map API would include the /api and /conformance resources, a Map API Module would not. So the Map API Module is not conformant with the OGC Web API standards.

We need to define a different standardization target (Web API Module) or every conformant product must be a full Web API. I've made my attempt at defining this beast. I'm open to suggestions.

[cportele]

@cmheazel I do not see the issue or the need for a different standardization target. If a Web API conforms to, say, Tiles Core and Common General, but not to Common Core, it is still a Web API. It may not have a declaration of OGC API conformance classes or an API definition, but the Web API can still conform to other OGC API requirements classes that do not depend on Common Core. There is no need for a "module" concept as far as I can see.

I had a closer look at the current Common General requirements class and would suggest that we do not need it. It has five requirements. One is about CRS84 as a default CRS, which may be more relevant for part 2? Three are about query parameters and the consistency with the API definition, which does not make sense as General does not require an API definition (so this belongs into Core). That leaves us with the requirement to comply with HTTP/HTTPS, which is only really tested and testable through the tests for the more specific requirements. The rest is mainly to text to remind readers of things they should be aware of, like HTTP status codes, caching, headers, cross-origin requests, the general approach to encodings, etc. This could be changed to informative text, I think.

[bradh]

If it isn't possible to evaluate an item (for conformance), then it probably isn't meaningful to define a conformance target for that item. Does a Web API module exist independent of a Web API?

I would agree it exists in a code sense (jar, npm module, python package, etc) but if we can't test it like that, its not going to work.

[joanma747]

This is based on a discussion in the telco 2020/08/10:

Ok, it seems that there is already a "general section" in the current API Core (section 8.4). One approach could be to start with this general part and have it in an independent conformance class. We could revisit the API Guidance to see if we can add something else to that section.
The problem we have is that the requirements class is "void" (http 1.1, error codes and nothing more). CRS84 does not belong here.
In addition, we will have another conformance class for the landing page, conformance and API description.
I wonder if "follow the links" and the "rel types" need to be another requirement somewhere. It is more like a principle.

The two targets ("web api" and "web api module") is difficult to understand by the participants in the call.

After discussing it a bit more, we believe that the "General" is almost void and we do not need it as a n independent conformance class

We recommend:

• to make 8.4 as the the first section (8.1)
• Current section 8.4.1 requires HTTP1.1 it is already explicit in the "dependency" so it is good to have it next to it.
• Current section 8.4.3 Unknown or invalid query parameters may be moved to API definition section. We leave this to the editor criteria.
• Keep API core as a single conformance class

[cmheazel]

The core requirements class has been divided into two sections, General Requirements and Resource Requirements. The General Requirements Class has been deleted.
The HTTP 1.1 requirement has been retained.
The Unknown or invalid query parameter section has remained with the other general requirements.
API Core is a single Conformance Class.

[jerstlouis]

What I believe this was trying to achieve was:

• being able to define a module depending on general OGC API - Common principles, concepts or definitions, e.g. resources linking/relation types, standard query parameters (e.g. bbox subset) and perhaps also having the possibility to be listed in /conformance, while
• being able to conform to such a module without e.g. implementing / or /api

This is especially relevant if other parts of Common (e.g. Part 2: Geospatial data) have a dependency on Core.
Presumably most Core extensions and principles can stand on their own without a landing page or API description being present.

[joanma747]

It seems that there is not much to test in the "General Conformance Class" and the "new" opinion is that it is better to allow OGC API standards to have a dependency to the relevant non-OGC standards for the web instead. e.g.:
|Dependency |<<rfc2616,RFC 2616 (HTTP/1.1)>>
|Dependency |<<rfc2818,RFC 2818 (HTTP over TLS)>>
|Dependency |<<rfc8288,RFC 8288 (Web Linking)>>

We will also allow that OGC Common extensions to do not depend on core. E.g. The BBOX extension could be defined as not needing to depend on core because it can be used independently from core by other standards.
OpenAPI 3.0 conformance class is an example of extension that will depend on OGC Common core.

So in the 2020-08-31 telco we decided to forget about "general" and go back to have only "core". Dependency in Common core is optional and OGC API modules should consider if it is possible to defined them independently of Common Core.

The issue is closed pending updates to part 1 and 2.

[cmheazel]

@joanma747 Not quite. If you don't implement API-Common Part 1 then you are not an OGC Web API. We need to define an additional standardization target for API modules. This is an important distinction for both conformance testing and certification. It's also too big an issue to be resolved by the API Common SWG.

[ghobona]

2020-09-15 OGC API Cross Cutting Issues session during OGC Member Meeting

The following resolution was agreed upon during the session:

• OGC API – Common – Part 1: Core is optional i.e. it’s not mandatory.
• Some OGC API standards may depend on OGC API – Common – Part 2 and not Part 1. This will also be allowed. The reverse is also allowed.

[joanma747]

Action already applied in core.
Application in collections pending.

[jerstlouis]

@joanma747 @cmheazel
RFC 7231 (e.g. content negotiation) from 8.1.6 Encodings is also a requirement which should be considered a dependency for the other modules, if they cannot depend specifically on OGC API - Common - Part 1: Core - 8.1. General Requirements.

[cmheazel]

Note: Core cites both 7231 and 2616 as normative standards. But 7231 obsoletes 2616. so 2616 needs to be replaced with 7230, 7231, 7232, 7233, 7324, 7235

[joanma747]

Make sure that all requirements in core are also included in collections if necessary (it includes the general requirements section)

[cmheazel]

IETF RFC 7230, 7231, 7232, and 7235 have been added to the normative references in Core. IETF RFC 2616 has been removed.

[cmheazel]

The general requirements in API-Common Core have been extracted as separate modules and written to be independent of the associated standard. This will allow this section to be re-used in other standards documents.

[cmheazel]

The general requirements are now shared between core and geodata. A single set of asciidoc files are imported by both standards.