Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Pubsub dp bootstrap smill #14

Merged
merged 7 commits into from
Jan 26, 2023
Merged

Pubsub dp bootstrap smill #14

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
93c16cc
Added an additional paragraph for scope, grammar and spelling changes
ShaneMill1 Jan 20, 2023
5948100
Added an example AsyncAPI document in Annex A
m-burgoyne Jan 25, 2023
61fb570
Update clause_5_conventions.adoc
tomkralidis Jan 26, 2023
fc75342
Update annex-a.adoc
tomkralidis Jan 26, 2023
fd2fb05
Update annex-a.adoc
tomkralidis Jan 26, 2023
65dec32
Update annex-a.adoc
tomkralidis Jan 26, 2023
7005e15
Update annex-a.adoc
tomkralidis Jan 26, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
271 changes: 256 additions & 15 deletions PubSub_Draft/sections/annex-a.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,263 @@
[appendix]
== Conformance Class Abstract Test Suite (Normative)
[appendix,obligation="informative"]
== Examples (Informative)

[NOTE]
Ensure that there is a conformance class for each requirements class and a test for each requirement (identified by requirement name and number)
[[async-examples]]
=== PubSub API Description Example

=== Conformance Class A
The API is described using the https://www.asyncapi.com/[AysncAPI 2.5.0 specification] and an example response can be found below:

==== Requirement 1
[requirement,type="pseudocode",label="/req/req-class-a/req-name-1"]
=====
====
[source,yaml]
----
asyncapi: '2.5.0'
info:
title: AsyncAPI demo
version: '0.0.1'
description: |
AsyncAPI description of the proposed PubSub functionality
contact:
name: Contact Name
email: you@example.org

[verification,label="/conf/conf-class-a/req-name-1"]
======
Test purpose:: Verify that...
servers:
mqtt_prod:
url: example.org
protocol: mqtt
description: MQTT endpoint
security:
- user-password: []
defaultContentType: application/json

Test method:: Inspect...
======
channels:
collections:
subscribe:
message:
$ref: '#/components/messages/collection_msg'
collections/wthr_stn:
subscribe:
message:
$ref: '#/components/messages/collection_msg'
collections/stream_gage:
subscribe:
message:
$ref: '#/components/messages/collection_msg'
collections/wthr_stn/items:
subscribe:
message:
$ref: '#/components/messages/wthr_stn_msg'
collections/stream_gage/items:
subscribe:
message:
$ref: '#/components/messages/stream_gage_msg'

=====
components:
messages:
collection_msg:
description: collection updated notification
payload:
type: object
required:
- id
- href
properties:
id:
type: string
description: collection name
time:
type: string
format: date-time
description: time collection changed
href:
type: string
format: uri
description: URL of the changed collection
wthr_stn_msg:
description: An observation formatted as GeoJSON
payload:
type: object
additionalProperties: false
properties:
id:
type: string
type:
type: string
geometry:
type: object
properties:
type:
type: string
coordinates:
type: array
items:
type: number
format: float
properties:
type: object
properties:
time:
type: string
format: date-time
id:
type: string
wind_direction:
type: number
format: float
wind_speed:
type: number
format: float
wind_gust:
type: number
format: float
visibility:
type: number
format: float
air_temperature:
type: number
format: float
dew_point:
type: number
format: float
mean_sea_level_pressure:
type: number
format: float
stream_gage_msg:
description: Monitoring station data formatted as GeoJSON
payload:
type: object
additionalProperties: false
properties:
id:
type: string
type:
type: string
geometry:
type: object
properties:
type:
type: string
coordinates:
type: array
items:
type: number
format: float
links:
type: array
items:
type: object
properties:
rel:
type: string
type:
type: string
title:
type: string
href:
type: string
format: uri
properties:
type: object
properties:
datetime:
type: string
format: date-time
label:
type: string
parametername:
type: array
items:
type: string
edrqueryendpoint:
type: string
format: uri
securitySchemes:
user-password:
type: userPassword
----
====

==== Requirement 2
Breaking down into the components:

====
[source,yaml]
----
asyncapi: '2.5.0'
info:
title: AsyncAPI demo
version: '0.0.1'
description: |
AsyncAPI description of the proposed Pub/Sub functionality
contact:
name: Contact Name
email: you@example.org
----
====
* The `asyncapi` field indicates you use the AsyncAPI version 2.5.0.
* The `info` field holds information about the API, such as its name, version, description, and license.

====
[source,yaml]
----
servers:
mqtt_prod:
url: example.org
protocol: mqtt
protocolVersion: 3.1.1
description: MQTT endpoint
security:
- user-password: []

----
====
* Each `server` object provides the following fields:
** `url` URL of the target broker (this may be relative to the API document)
** `protocol` The Pub/Sub protocol supported by the server
** `protocolVersion` The version Pub/Sub protocol supported by the server
** `description` String describing the host
** `security` reference to the supported authentcation types


====
[source,yaml]
----
channels:
collections:
subscribe:
message:
$ref: '#/components/messages/collection_msg'
collections/wthr_stn:
subscribe:
message:
$ref: '#/components/messages/collection_msg'
collections/stream_gage:
subscribe:
message:
$ref: '#/components/messages/collection_msg'
collections/wthr_stn/items:
subscribe:
message:
$ref: '#/components/messages/wthr_stn_msg'
collections/stream_gage/items:
subscribe:
message:
$ref: '#/components/messages/stream_gage_msg'
----
====

* The `channels` section lists the events a user can subscribe to and can provide a schema for the message payloads.

* In the example the following events can be subscribed to:

** `collections`
** `collections/wthr_stn`
** `collections/stream_gage`
** `collections/wthr_stn/items`
** `collections/stream_gage/items`

====
[source,yaml]
----
components:
----
====

* As in the OpenAPI specification the `components` section is used to define reusable objects for different aspects of the AsyncAPI specification.
4 changes: 4 additions & 0 deletions PubSub_Draft/sections/annex-history.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,4 +6,8 @@
|Date |Release |Editor | Primary clauses modified |Description
|2022-11-22 |0.1 |S. Olson|all |initial version
|2023-01-15 |0.2 |T. Kralidis|all |bootstrap
|2023-01-18 |0.2.1 |C. Little|all | editorial changes
|2023-01-19 |0.2.2 |M. Burgoyne|all | editorial changes
|2023-01-21 |0.2.3 |S. Olson/S. Mill|all | editorial changes
|2023-01-25 |0.3 |M. Burgoyne|all | added annex
|===
4 changes: 3 additions & 1 deletion PubSub_Draft/sections/clause_1_scope.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,2 +1,4 @@
== Scope
This Discussion Paper provides insight into the ongoing work within the OGC MetOcean Domain Working Group (MetOceanDWG) and related activities (World Meteorological Organization Information System version 2 [WIS2])) regarding Publish-Subscribe architecture. This paper makes a case for a Publish-Subscribe standard in the OGC API ecosysrtem.
This Discussion Paper provides insight into the ongoing work within the OGC MetOcean Domain Working Group (MetOceanDWG) and related activities (World Meteorological Organization Information System version 2 [WIS2])) regarding Publish-Subscribe architecture. This paper makes a case for a Publish-Subscribe standard in the OGC API ecosystem.

One of the cases we would like to make in the OGC API - EDR Pub/Sub work is the broader appeal for the larger set of OGC API’s. The basis for this is our choice for the Pub/Sub channel structure to match the OGC API “collections” structure. The overall benefit is that the building blocks of the RESTful API endpoint structure would be crosswalked as Pub/Sub channels with the only difference in syntax being dot notation for channels rather than “/” notation. This allows for a parallel access pattern between the RESTful API and Pub/Sub access.
2 changes: 1 addition & 1 deletion PubSub_Draft/sections/clause_4_terms_and_definitions.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ An entity that creates a subscription to a Publisher.

A container within which data (such as JSON, XML, binary data, or other content) is transported. Messages may include additional information beyond data, including headers or other metadata used for routing or security purposes.

=== Topic
=== Channel

A term (string) used to filter messages from a Broker.

Expand Down
2 changes: 1 addition & 1 deletion PubSub_Draft/sections/clause_5_conventions.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
== Conventions

This sections provides details and examples for any conventions used in the document. Examples of conventions are symbols, abbreviations, use of XML schema, or special notes regarding how to read the document.
This section provides details and examples for any conventions used in the document. Examples of conventions are symbols, abbreviations, use of XML schema, or special notes regarding how to read the document.

=== Identifiers
The normative provisions in this document are denoted by the URI
Expand Down
6 changes: 3 additions & 3 deletions PubSub_Draft/sections/clause_6_discussion.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,11 +78,11 @@ A link to the PubSub definition document for the service MUST be provided on the

=== Protocols and Interoperability

An OGC API - PubSub standard SHOULD not proscribe a protocol, AsyncAPI (or equivalent technology) would be utilised to describe the interfaces supported by a service in order to enable interoperability.
An OGC API - PubSub standard SHOULD not prescribe a protocol, AsyncAPI (or equivalent technology) would be utilized to describe the interfaces supported by a service in order to enable interoperability.

=== Message payloads

OGC API - PubSub standard SHOULD not proscribe a message payload, but all payload formats/schemas MUST be defined by the advertised definition API
OGC API - PubSub standard SHOULD not prescribe a message payload, but all payload formats/schemas MUST be defined by the advertised definition API

=== Channel descriptions

Expand All @@ -94,7 +94,7 @@ TODO: expand
* Protocol: any protocol (MQTT, AMQP, etc.)
* Message payload: GeoJSON as metadata, or actual data
* AsyncAPI: link object in OGC API landing page response ``links`` section
* Topic hierarchy / OGC API integration: use OGC API endpoints as channels, link objects and rels in collection metadata
* Topic hierarchy / OGC API integration: use the OGC API endpoint structure as channels, link objects and rels in collection metadata

== WMO WIS2 implementation

Expand Down