Add capability to advertise the EDR profile supported by a service

[m-burgoyne]

A need has been identified to define profiles for EDR services, e.g. to allow services to advertise that they are using agreed conventions for Parameter ids or Instance representations. Adding link to the links section of a collection with an IANA link-relation of profile would allow clients to easily detect which (if any) profile a collection supports. The link could be used as both a link to documentation for the profile and as a unique identifier.

e.g.
{
"href": "https://reference.server.org/profile/monitoring-station-data
"hreflang": "en",
"rel": "profile",
"title": "monitoring-station-data",
"type": "text/html"
}

[chris-little]

This would be an optional link. It could for example point to a community agreed best practice documentation.
It could also be used in other APIs too.

[chris-little]

Two good examples of useing this mechanism are:
1 a profile for measurement types;
2. to identify NWP model runs and instances for a given collection.

[chris-little]

@ShaneMill1 @solson-nws Having discussed this with @iandruska-ibl , are you happy to put this into V1.1?

[ShaneMill1]

@m-burgoyne I am beginning to attempt to prototype how this would work. Do you have any examples of what the profile payload would look like?

[m-burgoyne]

As a the profile URI should resolve to a template that the service MUST match to be compliant with the named profile an OpenAPI document would be ideal response. The response from the services /api endpoint would describe what the service actually provides and this could be a super set of the profile (if the implementation of EDR server offers more functionality than the base profile requires), but it must contain all of the elements defined by the profile. As this is the description of the EDR server functionality, a user could have confidence that a service provided all of the functionality required.

OpenAPI provides a standard way to define the collection names, queries, response schemas and formats that must be provided.

[tomkralidis]

How do profiles relate to conformance? For example, the WMO Core Metadata Profile 2 is a set of conformance classes (with requirements, recommendations and permissions) which articulate convention/specialization atop OGC API - Records. In this case, we use conformance (an API /conformance endpoint, and the conformsTo in a record payload) to describe the profile.

I suppose one can also use the link rel=profile approach to link to community best practices which 1./ are already built/specified/long standing and/or 2./ not critical path for machine validation/handling?

[chris-little]

@m-burgoyne @tomkralidis I think we should be explicitly stating restrictive profile which automatically gives us API-EDR conformance. So I think that the question is "how to conform to the (restrictive) profile"?

Supporting the ISO definition of a profile that may be an extension may be too ambitious.

[chris-little]

Users will be asked to clarify their requirements.

[m-burgoyne]

@tomkralidis @ShaneMill1 @chris-little @solson-nws @iandruska-ibl @pnovotny-ibl

Suggested approach to allow organisations to define an EDR profile:

Add a conformance class to indicate that the EDR server is an implementation of an EDR profile

If the conformance class is defined the service root response must include a link to the profile definition

that link would be to an OpenAPI definition of the EDR profile

for example:

{
"href": "https://reference.server.org/profile/monitoring-station-data.yml
"hreflang": "en",
"rel": "profile",
"title": "monitoring-station-data",
"type": "application/vnd.oai.openapi"
}

or for a json response:

{
"href": "https://reference.server.org/profile/monitoring-station-data.json
"hreflang": "en",
"rel": "profile",
"title": "monitoring-station-data",
"type": "application/vnd.oai.openapi+json"
}

The profile OpenAPI document in the link would exclude the servers field but would be defined at the level of detail required for the profile usecase. If required an OpenAPI document could define the collections, instances and location identifiers; codify the parameter-name, format and crs values as enumerated lists and provide a definition of the data output schemas (as needed).

The tests to support the conformance class could be written to use the server name from service OpenAPI endpoint but construct test queries based on the details provided in the profile OpenAPI document. This would remove the need to create custom conformance classes for each EDR profile.

Having both OpenAPI documents would allow an EDR service to offer a superset of the profile specification and ensure that a server did not have a dependancy on access to the profile document (as it access would only be needed when a service was being validated against the profile).

This approach could also be used (with another conformance class) for pub/sub profiles using AsyncAPI documents.

[ShaneMill1]

@m-burgoyne This may be a dumb question, but you mention the "profile" being a conformance class and show a dictionary containing href, hreflang, rel, title, and type.

However, when you go to /conformance in EDR, you get this:

{ "conformsTo":[ "http://www.opengis.net/spec/ogcapi-common-1/1.0/conf/core", "http://www.opengis.net/spec/ogcapi-common-2/1.0/conf/collections", "http://www.opengis.net/spec/ogcapi-edr-1/1.0/conf/core", "http://www.opengis.net/spec/ogcapi-edr-1/1.0/conf/oas30", "http://www.opengis.net/spec/ogcapi-edr-1/1.0/conf/html", "http://www.opengis.net/spec/ogcapi-edr-1/1.0/conf/geojson", "http://www.opengis.net/spec/ogcapi-edr-1/1.0/conf/coveragejson", "http://www.opengis.net/spec/ogcapi-edr-1/1.0/conf/wkt" ] }

Basically a dictionary with the conformsTo key, and the values being a list of schemas that EDR conformsTo.

How does your example fit with the /conformance endpoint? Could you provide an example of the full response?

[m-burgoyne]

@ShaneMill1 It's not a dumb question as I only included examples of the new link entries to the profile definition for the EDR root in the example above. The concept is there will be three changes to the EDR specification to allow a service to advertise that it supports a particular EDR profile.

1. Add a new conformance class to allow a service to advertise that it implements supports the concept of an EDR profile

{
   "conformsTo":[
      "http://www.opengis.net/spec/ogcapi-common-1/1.0/conf/core",
      "http://www.opengis.net/spec/ogcapi-common-2/1.0/conf/collections",
      "http://www.opengis.net/spec/ogcapi-edr-1/1.0/conf/core",
      "http://www.opengis.net/spec/ogcapi-edr-1/1.0/conf/oas30",
      "http://www.opengis.net/spec/ogcapi-edr-1/1.0/conf/html",
      "http://www.opengis.net/spec/ogcapi-edr-1/1.0/conf/geojson",
      "http://www.opengis.net/spec/ogcapi-edr-1/1.0/conf/coveragejson",
      "http://www.opengis.net/spec/ogcapi-edr-1/1.0/conf/wkt",
      "http://www.opengis.net/spec/ogcapi-edr-1/1.0/conf/profiles"
   ]
}

The corresponding tests for this conformance class, would be to check that a link definition exists at the EDR root for an OpenAPI document that describes the functionality required to be compliant and interoperable and to run tests driven by the contents of that OpenAPI document.

2. Add a new link to the links section of the EDR root end point which is the location of the OpenAPI definition for the profile

{
    "title": "Environmental Data Retrevial API example",
    "description": "Example EDR API",
    "keywords": [
        "position",
        "area",
        "cube",
        "trajectory",
        "weather",
        "data",
        "api"
    ],
    "terms_of_service": "None",
    "provider": {
        "name": "Organization Name",
        "url": "https://example.org"
    },
    "contact": {
        "email": "[email protected]",
        "phone": "+xx-xxx-xxx-xxxx",
        "fax": "+xx-xxx-xxx-xxxx",
        "hours": "Hours of Service",
        "instructions": "During hours of service.  Off on weekends.",
        "address": "Mailing Address",
        "postalcode": "Zip or Postal Code",
        "city": "City",
        "stateorprovince": "Administrative Area",
        "country": "Country"
    },
    "links": [
        {
            "href": "https://example.org/edr/api",
            "hreflang": "en",
            "rel": "service-desc",
            "type": "application/vnd.oai.openapi+json;version=3.0",
            "title": "OpenAPI document"
        },
        {
            "href": "https://example.org/edr/asyncapi",
            "hreflang": "en",
            "rel": "service-desc",
            "type": "application/vnd.aai.asyncapi+yaml;version=2.0.0",
            "title": "AsyncAPI document"
        },
        {
            "href": "https://example.org/edr/conformance",
            "hreflang": "en",
            "rel": "conformance",
            "type": "application/json",
            "title": "Conformance document"
        },
        {
            "href": "https://example.org/edr/collections",
            "hreflang": "en",
            "rel": "data",
            "type": "application/json",
            "title": "Collections document"
        },
        {
            "href": "https://reference.server.org/profile/demo.json",
            "hreflang": "en",
            "rel": "profile",
            "title": "Demo service OpenAPI profile",
            "type": "application/vnd.oai.openapi+json"
        }        
    ]
}

3. Create an OpenAPI definition (https://reference.server.org/profile/demo.json in the example above). This can be defined to the level of detail required to ensure interoperability, i.e. it could just identify which EDR queries are required to be interoperable, or it could be used to define collection, parameter, CRS and format names and schemas that must be supported to ensure compliance. The advantage of this approach is that it would allow groups to have control over creating and advertising new EDR profiles required for interoperability in their use case.

[ShaneMill1]

@m-burgoyne Thanks a lot for the examples, this really brought it together for me and I agree with the approach