Skip to content

Commit

Permalink
update based on latest discussion at EDR SWG
Browse files Browse the repository at this point in the history
  • Loading branch information
tomkralidis committed Jun 17, 2024
1 parent a077821 commit 2efeb58
Show file tree
Hide file tree
Showing 10 changed files with 10 additions and 85 deletions.

This file was deleted.

This file was deleted.

This file was deleted.

This file was deleted.

6 changes: 0 additions & 6 deletions extensions/pubsub/standard/sections/annex-a.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -7,12 +7,6 @@ include::../abstract_tests/ATS_class_pubsub.adoc[]

include::../abstract_tests//pubsub/ATS_test_api.adoc[]

=== Conformance Class Publish-Subscribe (Pub/Sub) Channels

include::../abstract_tests/ATS_class_pubsub_channels.adoc[]

include::../abstract_tests/pubsub-channels/ATS_test_channels.adoc[]

=== Conformance Class Publish-Subscribe (Pub/Sub) Message Payloads

include::../abstract_tests/ATS_class_pubsub_notification_message_payload.adoc[]
Expand Down
24 changes: 1 addition & 23 deletions extensions/pubsub/standard/sections/annex-pubsub.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ Breaking down into the components:
----
====

* The `asyncapi` field indicates you use the AsyncAPI version 3.0.0.
* The `asyncapi` field indicates you use the AsyncAPI version 3.0.
* The `info` field holds information about the API, such as its name, version, description, and license.

====
Expand Down Expand Up @@ -91,42 +91,22 @@ Different Pub/Sub protocols are supported as additional server objects, and can
channels:
notify-collections:
address: collections
x-ogc-api-link:
rel: data
type: application/json
href: https://example.org/collections
message:
$ref: '#/components/messages/collection_msg'
notify-collections/wthr_stn:
address: collections/wthr_stn
x-ogc-api-link:
rel: collection
type: application/json
href: https://example.org/collections/wthr_stn
messages:
$ref: '#/components/messages/collection_msg'
notify-collections-stream_gage:
address: collections/stream_gage
x-ogc-api-link:
rel: collection
type: application/json
href: https://example.org/collections/stream_gage
messages:
$ref: '#/components/messages/collection_msg'
notify-collections-wthr_stn-items:
address: collections/wthr_stn/items
x-ogc-api-link:
rel: items
type: application/json
href: https://example.org/collections/stream_gage/items
messages:
$ref: '#/components/messages/wthr_stn_msg'
collections-stream_gage-items:
address: collections/stream_gage/items
x-ogc-api-link:
rel: items
type: application/json
href: https://example.org/collections/stream_gage/items
messages:
$ref: '#/components/messages/stream_gage_msg'
----
Expand All @@ -142,8 +122,6 @@ Different Pub/Sub protocols are supported as additional server objects, and can
** `collections/wthr_stn/items`
** `collections/stream_gage/items`

The use of `x-ogc-api-link` demonstrates the capability to cross reference an AsyncAPI to an OGC API resource.

====
[source,yaml]
----
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -65,3 +65,7 @@ All questions regarding this submission should be directed to the editor or the
|Shane Mill |NOAA/NWS

|===

== Acknowledgements

Thanks to the members of the Meteorology and Oceanography Domain Working Group of the OGC as well as Clemeens Portele and all contributors of change requests and comments.
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ The following https://www.iana.org/assignments/link-relations/link-relations.xht
In addition, the following link relation types are used for which no applicable registered link relation type could be identified.

* **items**: Refers to a resource that is comprised of members of the collection represented by this context.
* **http://www.opengis.net/def/rel/ogc/1.0/pubsub**: Refers to a resource that is accessible via an event driven is comprised of members of the collection represented by the link's context.

Each resource representation includes an array of links. Implementations are free to add additional links for all resources provided by the API. For example, an enclosure link could reference a bulk download of a collection. Or a related link on a record could reference a related record.

Expand Down
11 changes: 4 additions & 7 deletions extensions/pubsub/standard/sections/clause_7_pubsub.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -53,14 +53,13 @@ The links array could also provide references to the Pub/Sub capabilities availa

NOTE: In the OGC API Suite of Standards, a https://docs.ogc.org/DRAFTS/20-024.html#collection-description[collection] is a geospatial https://docs.ogc.org/DRAFTS/20-024.html#resource-definition[resource] (such as a dataset) that may be available as one or more sub-resource https://docs.ogc.org/DRAFTS/20-024.html#distribution-definition[distributions] that conform to one or more OGC API standards. See https://docs.ogc.org/DRAFTS/20-024.html#rc-collections-section[OGC API-Common: Part 2]

A link object could contain a `channel` property which provides the relevant channel or topic that a client can subscribe to after connecting to a Pub/Sub endpoint. The value and syntax of the `channel` property is bound to the Pub/Sub protocol identified in the `type` property.
Communicating event driven workflow from a link object is made via the `+http://www.opengis.net/def/rel/ogc/1.0/pubsub+` link relation. This link relation communicates that the link represents a Publish-Subscribe workflow defined by a Pub/Sub protocol in the `href` property as well as a `channel` property. The `channel` property provides the relevant addressable topic that a client can subscribe to after connecting to a Pub/Sub endpoint. The value and syntax of the `channel` property is bound to the Pub/Sub protocol identified in the `href` property.

.Example of OGC API Pub/Sub link to new collection notifications
[source,json]
----
{
"rel": "collection",
"type": "application/json",
"rel": "http://www.opengis.net/def/rel/ogc/1.0/pubsub",
"title": "Data notifications",
"href": "mqtt://example.org:8883",
"channel": "collections"
Expand All @@ -77,8 +76,7 @@ An OGC API - Features example
[source,json]
----
{
"rel": "items",
"type": "application/json",
"rel": "http://www.opengis.net/def/rel/ogc/1.0/pubsub",
"title": "Data notifications",
"href": "mqtt://example.org:8883",
"channel": "collections/surface-weather-observations"
Expand All @@ -91,8 +89,7 @@ An OGC API - EDR example
[source,json]
----
{
"rel": "items",
"type": "application/json",
"rel": "http://www.opengis.net/def/rel/ogc/1.0/pubsub",
"title": "Data notifications",
"href": "mqtt://example.org:8883",
"channel": "collections/surface-weather-observations/items"
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,3 @@ The OGC API service endpoint specified by a URL path of resources and sub-resour
For example, users could use a subscription to metadata records, which are usually small compared to the source data, and are therefore more transportable. This informs and notifies the user of changes prior to requesting the possibly large source data, especially when bandwidth is at a premium.

Using the OGC API service endpoints of the URL path of resource and sub-resources provides the key benefit that developers implementing OGC API Standards do not need to learn a different, additional approach or resource path for Pub/Sub (same content, additional interface).

While AsyncAPI does not have native OpenAPI integration, in order to cross-reference a given AsyncAPI channel against its associated OGC API resource, the `+x-ogc-api-link+` object can be used. The structure of this object is defined in OGC API - Common - Part 1: Core, Section 6.3.

include::../requirements/pubsub-channels/REQ_rc-channels.adoc[]

0 comments on commit 2efeb58

Please sign in to comment.