Brief review of parts 1 and 2

[cportele]

Comments from a quick review of the current drafts, if they are ready for the next step:

• Both parts
  • [x] The Normative references section lists specifications that are no a dependency in a requirements class. These should be moved to the bibliography. Resolution - trim down the references to only the essential ones - those that an implementer MUST read.
  • [x] Both drafts sometime uses the term "OGC Web API" for an API, but there is no such thing as an OGC Web API. OGC only specifies OGC API standards that Web APIs may choose to conform to. Those sentences should be reworded. Resolution - Add definition - A Web API that implements one or more conformance classes from an OGC API Standard.
• Part 1
  • [x] Link object: Should we allow for the use of (safe) CURIEs in rel values? See [the related OGC-NA proposal] (https://github.com/opengeospatial/NamingAuthority/issues/92#issuecomment-888186821)? - Resolution - since there is not yet an OGC policy, defer this update to a future version.
  • [x] 6.6.3 is misleading since Common uses JSON Schema draft v7 to normatively define schemas, not OpenAPI 3.0 schema objects. It is also inconsistent to use v7 schemas in an "openapi" path as done in the beta schemas. Either use JSON Schema consistently (but in this case, why the old draft v7 and not 2020-12 which will also be used in OpenAPI 3.1?) or use OpenAPI 3.0 schemas consistent with the text and the OpenAPI 3.0 req class. - Resolution - Update the schema to conform to OAS 3.0 schema. Note: schema repository needs to be updated as well. Also, replace JSON schema in the document with YAML.
  • [x] Table 3 lists /api as the path of the API definition, but there should not be a fixed path for the API definition. The API definition does not have to be a resource of the API and can be an external resource. The only requirement is that there is a link to the API definition. Remove the row. - Resolution - remove the URI column from Table 3 - make sure any other use of these URIs are cleaned up.
  • [x] Recommendation 9B recommends to provide a service-meta link, but there is not guidance what the target should contain and why. There is a link to the guide, but that has not information either. This recommendation should be deleted. - Resolution - remove recommendation 9 and section 11.5. Add service-metadata to link relation types.
  • [x] There is some detail in the OpenAPI 3.0 requirements class, but it is unclear why a copy of the info object should be linked as a separate resource. Clients can access the OpenAPI document and get the relevant information. Delete? - Resolution - see previous issue.
  • [x] The ATS has tests for clients, but clients are not a standardization target of the requirements classes. These assertions should be deleted or moved to informative text. - Resolution - Restructure ATS client requirements to be server-centric. OAB issue - how do we handle coupled client-server requirements.
  • [x] Test 12 requires that servers support, e.g. inf as a value for all numeric query parameters. However,
  • inf is not a valid numeric value and
  • servers should not be required to support these values for all numeric query parameters.
  • Resolution: make requirement 12 a recommendation - drop ATS 12.
  • [x] Requirement 22B seems to imply that all API resources that support a media type application/json MUST have a JSON Schema. This is should not be a requirement. For example, an OpenAPI 3.0 schema object should be ok, too, which is not a JSON Schema. - Resolution - bring in alignment with features.
• Part 2
  • [x] Section 6.3.2: Features does not use ISO 19108 as the basis, it uses RFC 3339, ISO 8601 and OWL-Time. ISO 19108 is no longer consistent with the OGC Abstract Specs, in particular Topic 2 / ISO 19111.
  • [x] Section 6.5 should not state UTC as the default timezone, all timestamps must include a timezone. Otherwise Common does not conform to RFC 3339.
  • [x] Requirement 6/7/8 will break existing servers which will return an error, which I also consider as the correct response (consistent with Part 1).
  • [x] The bbox schema is not up-to-date with the definition in the editor's draft of Features.
  • [x] Recommendation 6 is not a recommendation for the standardization target and needs to be changed to informative text.
  • [x] I do not understand the motivation for req 23. It is also in conflict with req 24B.
  • [x] Clause 3 lists a subsetting req class that does not exist. The line should be removed.

[cmheazel]

RE: Part 1 section 6.6.3 - Changed text to refer to the included schema as OpenAPI Schema. The included schema are OpenAPI schema fragments. Also added non-normative references to the JSON schema on the repository. These schema are consistent with the OAS schema. Note that none of these schema are normative except when used in the JSON or OAS conformance classes.

Created an OAS document for Common Part 1. Created an example OAS document which references the Part 1 document.

Converted all examples to yaml.

[cmheazel]

RE: Part 2 Requirement 23 - the purpose of this requirement is to make the point that a server should inform the client if the entire result set is not being returned. Changing this to a recommendation achieves this goal while avoiding the conflict with requirement 24B.

[cmheazel]

Requirements 6, 7, and 8, - The requirements governing query parameters are documented in Part 1 - Core, sections 8.3 and 8.8. We can delete requirements 6, 7, and 8 in deference to the requirements in core.