From 4fce473a522f4d46361df75c75add32b4f90e24d Mon Sep 17 00:00:00 2001 From: Anna Milan Date: Mon, 5 Aug 2024 14:43:06 +0200 Subject: [PATCH] 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 * Update standard/sections/clause_7_normative_text.adoc Co-authored-by: Tom Kralidis --------- Co-authored-by: Tom Kralidis --- .../recommendations/core/PER_centre-id.adoc | 1 + .../recommendations/core/PER_publishing.adoc | 1 + .../recommendations/core/REC_centre-id.adoc | 1 + .../recommendations/core/REC_publishing.adoc | 1 + standard/requirements/core/REQ_centre-id.adoc | 5 +- .../requirements/core/REQ_conventions.adoc | 3 +- .../requirements/core/REQ_management.adoc | 1 + .../requirements/core/REQ_publishing.adoc | 1 + standard/requirements/core/REQ_releasing.adoc | 5 +- .../requirements/core/REQ_versioning.adoc | 1 + .../requirements/requirements_class_core.adoc | 12 +- .../sections/clause_7_normative_text.adoc | 108 +++++++++++++++--- 12 files changed, 111 insertions(+), 29 deletions(-) diff --git a/standard/recommendations/core/PER_centre-id.adoc b/standard/recommendations/core/PER_centre-id.adoc index 78e0061..ce28e93 100644 --- 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 \ No newline at end of file diff --git a/standard/recommendations/core/PER_publishing.adoc b/standard/recommendations/core/PER_publishing.adoc index dc82f70..055d4d4 100644 --- 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 \ No newline at end of file diff --git a/standard/recommendations/core/REC_centre-id.adoc b/standard/recommendations/core/REC_centre-id.adoc index 97baac4..c602ebe 100644 --- 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 \ No newline at end of file diff --git a/standard/recommendations/core/REC_publishing.adoc b/standard/recommendations/core/REC_publishing.adoc index 28ca7f9..aab55c5 100644 --- 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 \ No newline at end of file diff --git a/standard/requirements/core/REQ_centre-id.adoc b/standard/requirements/core/REQ_centre-id.adoc index 96925da..c0c5839 100644 --- 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 \ No newline at end of file diff --git a/standard/requirements/core/REQ_conventions.adoc b/standard/requirements/core/REQ_conventions.adoc index 42e8ccd..4f6164e 100644 --- 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 \ No newline at end of file diff --git a/standard/requirements/core/REQ_management.adoc b/standard/requirements/core/REQ_management.adoc index d30300c..e74427d 100644 --- 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 \ No newline at end of file diff --git a/standard/requirements/core/REQ_publishing.adoc b/standard/requirements/core/REQ_publishing.adoc index 833ee50..d3a9402 100644 --- 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 \ No newline at end of file diff --git a/standard/requirements/core/REQ_releasing.adoc b/standard/requirements/core/REQ_releasing.adoc index 2a0b78d..b463b3b 100644 --- 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 \ No newline at end of file diff --git a/standard/requirements/core/REQ_versioning.adoc b/standard/requirements/core/REQ_versioning.adoc index 47a4d20..db5e748 100644 --- 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 \ No newline at end of file diff --git a/standard/requirements/requirements_class_core.adoc b/standard/requirements/requirements_class_core.adoc index f05a002..1c87394 100644 --- 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 |<> -|Dependency |<> -|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 index b8d433e..dd7d828 100644 --- 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,7 +51,7 @@ 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 @@ -46,14 +59,14 @@ The table below provides an overview of the primary topic levels. |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. @@ -61,28 +74,89 @@ 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.