164 update GitHub for LSP publication (#165)

* update GitHub with edits sent to LSP for publication #164 * minor edits * Apply suggestions from code review add MQTT links * Apply suggestions from code review fix MQTT links again * fix table * Update standard/sections/clause_7_normative_text.adoc add space * Update standard/sections/clause_7_normative_text.adoc add space * Update standard/requirements/core/REQ_centre-id.adoc Co-authored-by: Tom Kralidis <[email protected]> * Update standard/sections/clause_7_normative_text.adoc Co-authored-by: Tom Kralidis <[email protected]> --------- Co-authored-by: Tom Kralidis <[email protected]>
wmo-im · Aug 5, 2024 · 4fce473 · 4fce473
1 parent d855a2b
commit 4fce473
Show file tree

Hide file tree

Showing 12 changed files with 111 additions and 29 deletions.
diff --git a/standard/recommendations/core/PER_centre-id.adoc b/standard/recommendations/core/PER_centre-id.adoc
@@ -7,3 +7,4 @@
 ^|C |A centre providing a WIS service MAY further qualify the function within the ``centre-name`` component (for example, ``int-org1-global-cache``).
 ^|D |Organizations wishing to test their WIS2 Node or Global Service MAY provide the ``-test`` suffix to their centre identifier (for example, ``int-org1-test``).
 |===
+//per2
diff --git a/standard/recommendations/core/PER_publishing.adoc b/standard/recommendations/core/PER_publishing.adoc
@@ -5,3 +5,4 @@
 ^|A |Metadata MAY be published at any level at or below the notification type (``metadata``).
 ^|B |Data MAY be published with the ``experimental`` topic and include any sub-discipline topics which are not yet approved.
 |===
+//per1
diff --git a/standard/recommendations/core/REC_centre-id.adoc b/standard/recommendations/core/REC_centre-id.adoc
@@ -5,3 +5,4 @@
 ^|A |Organizations operating with a ``gov`` or similar TLD SHOULD use the TLD based on their country to define the TLD component of their centre identifier.
 ^|B |International organizations operating with ``int``, ``org`` or similar TLD SHOULD reuse these to define the TLD component of their centre identifier.
 |===
+//rec2
diff --git a/standard/recommendations/core/REC_publishing.adoc b/standard/recommendations/core/REC_publishing.adoc
@@ -4,3 +4,4 @@
 ^|*Recommendation {counter:rec-id}* |*/rec/core/publishing*
 ^|A |The topic ``experimental`` SHOULD be used as a temporary approach until a given sub-discipline topic is approved.
 |===
+//rec1
diff --git a/standard/requirements/core/REQ_centre-id.adoc b/standard/requirements/core/REQ_centre-id.adoc
@@ -6,8 +6,9 @@
 ^|B
 a|A centre identifier SHALL be formatted as ``tld-centre-name``, where:
 
-- `tld` is based on TLD as defined by IANAfootnote:[https://data.iana.org/TLD] for the relevant country or international organization
-- `centre-name` is based on a centre name 
+- `tld` is based on TLD as defined by link:https://data.iana.org/TLD[IANA] for the relevant country or international organization;
+- `centre-name` is based on a centre name.
 ^|C | The `test` TLD SHALL be used only for WIS internal system testing purposes.
 
 |===
+//req6
diff --git a/standard/requirements/core/REQ_conventions.adoc b/standard/requirements/core/REQ_conventions.adoc
@@ -3,9 +3,10 @@
 |===
 ^|*Requirement {counter:req-id}* |*/req/core/conventions*
 ^|A |Topic level definitions SHALL be lowercase.
-^|B |Topic level definitions SHALL be encoded in IRA T.50footnote:[https://www.itu.int/rec/T-REC-T.50].
+^|B |Topic level definitions SHALL be encoded in link:https://www.itu.int/rec/T-REC-T.50[IRA T.50].
 ^|C |Topic level definitions SHALL NOT utilize dots (``.``).
 ^|D |Topic level definitions SHALL utilize dashes (``-``) to separate words (such as ``sea-ice``).
 ^|E |All topic level definitions at a given level SHALL be unique.
 ^|F |The topic structure levels imply a fixed sequence and SHALL NOT be re-ordered.
 |===
+//req5
diff --git a/standard/requirements/core/REQ_management.adoc b/standard/requirements/core/REQ_management.adoc
@@ -7,3 +7,4 @@
 ^|C |Sub-discipline topics (level 8 and beyond) SHALL be defined using a hierarchical approach.
 ^|D |Sub-discipline topics (level 8 and beyond) SHALL be coordinated and integrated by WMO.
 |===
+//req2
diff --git a/standard/requirements/core/REQ_publishing.adoc b/standard/requirements/core/REQ_publishing.adoc
@@ -6,3 +6,4 @@
 ^|B |Data SHALL be published to at least the level of the sub-discipline topic (level 8 or beyond).
 ^|C |Metadata SHALL be published to at least the level of the notification type (``metadata``).
 |===
+//req1
diff --git a/standard/requirements/core/REQ_releasing.adoc b/standard/requirements/core/REQ_releasing.adoc
@@ -2,8 +2,9 @@
 [width="90%",cols="2,6a"]
 |===
 ^|*Requirement {counter:req-id}* |*/req/core/releasing*
-^|A |The addition of a new centre identifier SHALL trigger an **immediate** stable release of WTH updates, which is not required to align with the WMO fast-track approval procedure.
-^|B |Immediate stable releases SHALL only contain changes resulting from a new value in the [centre-id] topic.
+^|A |The addition of a new centre identifier SHALL trigger an immediate stable release of WTH updates, which is not required to align with the WMO fast-track approval procedure.
+^|B |Immediate stable releases SHALL only contain changes resulting from a new value in the ``centre-id`` topic.
 ^|C |Updates to the primary levels and other major revisions will go through the WMO standard procedure.
 ^|D |Updates to the sub-discipline topics (level 8 and beyond) will go through the WMO fast-track approval procedure.footnote:[https://community.wmo.int/en/activity-areas/wis/amendment-processes-wis-manuals-and-guides]
 |===
+//req3
diff --git a/standard/requirements/core/REQ_versioning.adoc b/standard/requirements/core/REQ_versioning.adoc
@@ -11,3 +11,4 @@
 ^|G |A new topic SHALL NOT result in any version update.
 ^|H |A new centre identifier SHALL NOT result in any version update.
 |===
+//req4
diff --git a/standard/requirements/requirements_class_core.adoc b/standard/requirements/requirements_class_core.adoc
@@ -1,11 +1,9 @@
 [[rc_core]]
 [cols="1,4",width="90%"]
 |===
-2+|*Requirements Class*
-2+|http://wis.wmo.int/spec/wth/1/req/core
-|Target type |Topic Classification
-|Dependency |<<MQTT5, MQTT v5.0>>
-|Dependency |<<MQTT3, MQTT v3.1.1>>
-|Pre-conditions |
-Topics conform to Topic Name requirements of MQTT
+|URI|http://wis.wmo.int/spec/wth/1/req/core
+|Target type |Topic classification
+|Dependency |link:https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html[MQTT v5.0]
+|Dependency |link:https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html[MQTT v3.1.1]
+|Pre-conditions | Topics conform to the Topic Name requirements of MQTT
 |===
diff --git a/standard/sections/clause_7_normative_text.adoc b/standard/sections/clause_7_normative_text.adoc
@@ -1,12 +1,15 @@
-== The WIS2 Topic Hierarchy
+== WIS2 Topic Hierarchy
+Note: This section of working draft document is the same as Appendix D in the https://library.wmo.int/idurl/4/68731[_Manual on the WMO Information System_] (WMO-No. 1060), Volume II.
 
-The WIS2 Topic Hierarchy provides a mechanism for users to subscribe to and receive data or metadata notifications. It is documented in discovery metadata records and leveraged by WIS2 brokers.
+The WIS2 Topic Hierarchy (WTH) provides a mechanism for users to subscribe to and receive data or metadata notifications. It is documented in discovery metadata records and leveraged by WIS2 brokers.
 
-=== Requirements Class Core
+The normative provisions in this standard are denoted by the ``http://wis.wmo.int/spec/wth/1`` URI. All requirements in this document are denoted by partial Uniform Resource Identifiers (URIs) which are relative to this base and examples are represented with ``shaded text``.
 
-==== Overview
+:sectnums!:
 
-This Core Requirements Class provides requirements for the definition and management of the WIS2 Topic Hierarchy.
+=== 1. Requirements Class Core
+
+==== 1.1 Overview
 
 include::../requirements/requirements_class_core.adoc[]
 
@@ -16,7 +19,17 @@ The primary topics apply to all data and resources in WIS.  They are relational,
 
 The sub-discipline topics are proposed by domain experts and user communities.  These levels are a hierarchical representation of the dataset and the number of levels in this part may vary according to the requirements of various domains.
 
-The representation is encoded as a simple text string of values in each topic level separated by a ``/``. For example, ``origin/a/wis2/ca-eccc-msc/data/core/weather/surface-based-observations/synop`` or ``origin/a/wis2/ca-eccc-msc/data/recommended/atmospheric-composition/experimental/space-based-observation/geostationary/solar-flares``.
+The representation is encoded as a simple text string of values in each topic level separated by a slash (``/``). 
+
+Examples:
+
+``origin/a/wis2/ca-eccc-msc/data/core/weather/surface-based-observations/synop``
+
+``cache/a/wis2/ca-eccc-msc/data/core/weather/prediction/forecast/medium-range/probabilistic/global``
+
+``origin/a/wis2/ca-eccc-msc/data/core/weather/surface-based-observations/synop``
+
+ ``origin/a/wis2/ca-eccc-msc/data/recommended/atmospheric-composition/experimental/space-based-observation/geostationary/solar-flares``
 
 The table below provides an overview of the primary topic levels.
 
@@ -26,7 +39,7 @@ The table below provides an overview of the primary topic levels.
 
 |1
 |channel
-|Location of where the data originates from (data providers are ``origin`` and global services ``cache``)
+|Location of where the data originates from (data providers are ``origin`` and Global Services are ``cache``)
 
 |2
 |version
@@ -38,51 +51,112 @@ The table below provides an overview of the primary topic levels.
 
 |4
 |centre-id
-|Acronym proposed by member and endorsed by WMO Secretariat
+|Acronym proposed by Member and endorsed by WMO Secretariat
 
 |5
 |notification-type
 |WIS2 notification types (``data`` or ``metadata``)
 
 |6
 |data-policy
-|Data policy as defined by the WMO Unified Data Policy (``core`` and ``recommended``)
+|Data policy as defined by the WMO Data Policy (Resolution 1 (Cg-Ext(2021)))footnote:[Resolution 1 (Cg-Ext(2021)) – WMO Unified Policy for the International Exchange of Earth System Data (World Meteorological Congress: Abridged Final Report of the Extraordinary Session (WMO-No. 1281))] (``core`` and ``recommended``)
 
 |7
 |earth-system-discipline
-|Seven high-level categories as defined by the WMO Unified Data Policy, Annex 1: (``atmospheric-composition``, ``climate``, ``cryosphere``, ``hydrology``, ``ocean``, ``space-weather``, or ``weather``)
+|Seven high-level categories as defined by the WMO Data Policy (Resolution 1 (Cg-Ext(2021))) - Annex 1: (``atmospheric-composition``, ``climate``, ``cryosphere``, ``hydrology``, ``ocean``, ``space-weather``, or ``weather``)
 |===
 
-==== Publishing guidelines
+==== 1.2 Publishing
 
 For maximum utility and efficient management of topics, it is recommended that ``data`` and ``metadata`` are published to a detailed level of the topic hierarchy. This helps  avoid the "pollution" of messages under the primary topics.  Note that each discipline has a sub-discipline topic named ``experimental`` for publication to provisional topics.
 
 include::../requirements/core/REQ_publishing.adoc[]
 include::../recommendations/core/REC_publishing.adoc[]
 include::../recommendations/core/PER_publishing.adoc[]
 
-==== Management
+==== 1.3 Management
 The primary levels and sub-discipline specific levels are managed differently to maintain stability and allow for flexibility.
 
 include::../requirements/core/REQ_management.adoc[]
 include::../requirements/core/REQ_releasing.adoc[]
 
-==== Versioning
+==== 1.4 Versioning
 
 The topic hierarchy version helps data providers and data consumers with change management and transition in relation to updates.
 
 include::../requirements/core/REQ_versioning.adoc[]
 
-==== Conventions
+==== 1.5 Conventions
 
 All levels of the topic hierarchy are defined in a consistent manner to support a normalized and predictable structure.
 
 include::../requirements/core/REQ_conventions.adoc[]
 
-==== Centre identification
-
-The centre identifier (``centre-id``) is an acronym as specified by the WIS Centre and endorsed by WMO Secretariat.  It is a single identifier comprised of a top-level domain (TLD) and centre name. It represents the data publisher, distributor or issuing centre of a given dataset, data product, data granule or other resource.
+==== 1.6 Centre identification
+//specified by WIS Centre or Member?
+The centre identifier (``centre-id``) is an acronym as proposed by the Member and endorsed by the WMO Secretariat.  It is a single identifier comprised of a top-level domain (TLD) and centre name. It represents the data publisher, distributor or issuing centre of a given dataset, data product, data granule or other resource.
 
 include::../requirements/core/REQ_centre-id.adoc[]
 include::../recommendations/core/REC_centre-id.adoc[]
 include::../recommendations/core/PER_centre-id.adoc[]
+
+=== 2. WIS2 Topic Hierarchy resources
+==== 2.1 WMO Codes Registry
+
+|===
+|Level|Topic|URI
+
+|1
+|channel
+|https://codes.wmo.int/wis/topic-hierarchy/channel
+
+|2
+|version
+|https://codes.wmo.int/wis/topic-hierarchy/version
+
+|3
+|system
+|https://codes.wmo.int/wis/topic-hierarchy/system
+
+|4
+|centre-id
+|https://codes.wmo.int/wis/topic-hierarchy/centre-id
+
+|5
+|notification-type
+|https://codes.wmo.int/wis/topic-hierarchy/notification-type
+
+|6
+|data-policy
+|https://codes.wmo.int/wis/topic-hierarchy/data-policy
+
+|7
+|earth-system-discipline
+|https://codes.wmo.int/wis/topic-hierarchy/earth-system-discipline
+
+.7+|8
+|atmospheric-composition
+|https://codes.wmo.int/wis/topic-hierarchy/earth-system-discipline/atmospheric-composition
+
+|climate
+|https://codes.wmo.int/wis/topic-hierarchy/earth-system-discipline/climate
+
+|cryosphere
+|https://codes.wmo.int/wis/topic-hierarchy/earth-system-discipline/cryosphere
+
+|hydrology
+|https://codes.wmo.int/wis/topic-hierarchy/earth-system-discipline/hydrology
+
+|ocean
+|https://codes.wmo.int/wis/topic-hierarchy/earth-system-discipline/ocean
+
+|space-weather
+|https://codes.wmo.int/wis/topic-hierarchy/earth-system-discipline/space-weather
+
+|weather
+|https://codes.wmo.int/wis/topic-hierarchy/earth-system-discipline/weather
+
+|===
+
+==== 2.2 WMO schemas server
+A zipped directory of all topics is published at https://schemas.wmo.int/wth/a. This bundle can be used by tools and applications wishing to browse or validate topic structures.
-Original file line number
+Diff line change
@@ Expand Up / @@ -7,3 +7,4 @@ @@
     ^|C |A centre providing a WIS service MAY further qualify the function within the ``centre-name`` component (for example, ``int-org1-global-cache``).
     ^|D |Organizations wishing to test their WIS2 Node or Global Service MAY provide the ``-test`` suffix to their centre identifier (for example, ``int-org1-test``).
     |===
+    //per2