add requirements/recommendations/permissions setup (#35) (#25) (#57)

standard/abstract_tests/ATS_class_core.adoc

@@ -0,0 +1,7 @@
+[[ats_core]]
+====
+[%metadata]
+label:: http://www.wmo.int/spec/wth/1/conf/core
+subject:: Requirements Class "core"
+classification:: Target Type:Topic Classification
+====

standard/index.adoc

@@ -34,4 +34,26 @@
 toc::[]
 <<<
 
-include::clause_main.adoc[]
+include::sections/clause_0_front_material.adoc[]
+
+include::sections/clause_1_scope.adoc[]
+
+include::sections/clause_2_conformance.adoc[]
+
+include::sections/clause_3_references.adoc[]
+
+include::sections/clause_4_terms_and_definitions.adoc[]
+
+include::sections/clause_5_conventions.adoc[]
+
+include::sections/clause_6_informative_text.adoc[]
+
+include::sections/clause_7_normative_text.adoc[]
+
+include::sections/annex_a_ats.adoc[]
+
+include::sections/annex_b_examples.adoc[]
+
+include::sections/annex_c_bibliography.adoc[]
+
+include::sections/annex_d_revision_history.adoc[]

standard/requirements/core/REQ_conventions.adoc

@@ -0,0 +1,11 @@
+[[req_core_conventions]]
+[width="90%",cols="2,6a"]
+|===
+^|*Requirement {counter:req-id}* |*/req/core/conventions*
+^|A |All topic level definitions SHALL be lowercase.
+^|B |All topic level definitions SHALL following ASCII T.50.
+^|C |All topic level definitions SHALL NOT utilize dots (``.``).
+^|D |All topic level definitions SHALL utilize dashes (``-``).
+^|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.
+|===

standard/requirements/core/REQ_management.adoc

@@ -0,0 +1,18 @@
+[[req_core_management]]
+[width="90%",cols="2,6a"]
+|===
+^|*Requirement {counter:req-id}* |*/req/core/management*
+^|A |Primary levels 1-8 SHALL be determined by the WMO Task Team on WIS Metadata.
+^|B |Domain specific levels (level 9 and beyond) SHALL be determined by domain experts and user communities.
+^|C |Domain specific levels (level 9 and beyond) SHALL be coordinated and integrated by the WMO Task Team on WIS Metadata.
+^|D
+a|Domain specific level updates SHALL be implemented using the following steps:
+
+- domain specific teams submit proposals to TT-WISMD
+
+- TT-WISMD performs a review of the proposal and curates the content for consistency.  Discussion and clarifications on the proposal are performed as required
+
+- once consensus is reached, TT-WISMD approves the proposal for inclusion into the next release of WTH
+
+- Final approval of the WTH updates will go through the WMO fast-track amendment process.footnote:[https://community.wmo.int/en/activity-areas/wis/amendment-processes-wis-manuals-and-guides]
+|===

standard/requirements/core/REQ_publishing.adoc

@@ -0,0 +1,8 @@
+[[req_core_publishing]]
+[width="90%",cols="2,6a"]
+|===
+^|*Requirement {counter:req-id}* |*/req/core/publishing*
+^|A |Data SHALL be published to at least the level of the Earth system discipline subcategory.
+^|B |Metadata SHALL be published to at least the level of the notification type (``metadata``).
+^|C |Reports SHALL be published to at least the level of the notification type (``reports``).
+|===

standard/requirements/core/REQ_versioning.adoc

@@ -0,0 +1,11 @@
+[[req_core_versioning]]
+[width="90%",cols="2,6a"]
+|===
+^|*Requirement {counter:req-id}* |*/req/core/versioning*
+^|A |A removal of a topic at any level SHALL result in a major version update.
+^|B |A renaming of a topic at any level SHALL result in a major version update.
+^|C |A change in structure of the topic hierarchy SHALL result in a major version update.
+^|D |A new topic SHALL NOT result in any version update.
+^|E |A major version SHALL result in a change / bump to the version level (i.e. ``a`` -> ``b``).
+^|F |A minor version SHALL NOT result in any changes to the version level.
+|===

standard/requirements/requirements_class_core.adoc

@@ -0,0 +1,11 @@
+[[rc_core]]
+[cols="1,4",width="90%"]
+|===
+2+|*Requirements Class*
+2+|http://www.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
+|===

standard/sections/annex_a_ats.adoc

@@ -0,0 +1,8 @@
+[appendix]
+:appendix-caption: Annex
+== Conformance Class Abstract Test Suite (Normative)
+
+=== Conformance Class: Core
+
+include::../abstract_tests/ATS_class_core.adoc[]
+

standard/sections/annex_b_examples.adoc

@@ -0,0 +1,18 @@
+[[examples]]
+[appendix]
+:appendix-caption: Annex
+== Examples (Informative)
+
+=== WIS2 Topic Hierarchy 
+
+.Example: WIS Node data publishing (surface weather observations) from Environment and Climate Change Canada, Meteorological Service of Canada
+[source,text]
+----
+origin/a/wis2/can/eccc-msc/data/core/weather/surface-based-observations/synop
+----
+
+.Example: WIS Node metadata publishing from Deutscher Wetterdienst
+[source,text]
+----
+cache/a/wis2/deu/dwd/metadata/core/wcmp2
+----

standard/sections/annex_c_bibliography.adoc

@@ -0,0 +1,9 @@
+[appendix]
+:appendix-caption: Annex
+[[Bibliography]]
+= Bibliography
+
+* [[OASIS-mqtt5]] OASIS: MQTT Version 5.0 (2019) footnote:[https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html]
+* [[OASIS-mqtt311]] OASIS: MQTT Version 3.1.1 (2014) footnote:[http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html]
+* [[Wikipedia-PubSub]] Wikipedia: Publish-subscribe pattern (2023) footnote:[https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern]
+* [[ITU-T50]] International Telecommunications Union (ITU): T.50 : International Reference Alphabet (IRA) (Formerly International Alphabet No. 5 or IA5) - Information technology - 7-bit coded character set for information interchange footnote:[https://www.itu.int/rec/T-REC-T.50]

standard/sections/annex_d_revision_history.adoc

@@ -0,0 +1,9 @@
+[appendix]
+:appendix-caption: Annex
+== Revision History
+
+[cols="12,18,12,12,46",options="header"]
+|===
+|Date |Release |Editor | Primary clauses modified |Description
+|2023-09-25 | Template | Tom Kralidis |all | initial revision
+|===

standard/sections/clause_0_front_material.adoc

@@ -0,0 +1,25 @@
+[big]*i.     Abstract*
+
+WIS2 real-time data sharing is based on a message queuing protocol (MQP) supporting a
+publication/subscription (PubSub) mechanism.  A user can subscribe to an MQP broker to receive
+real-time notifications of the existence of new data.
+
+WIS2 brokers offer a range of topics organised in a hierarchy. Users can select their topics of interest and
+subscribe to them to receive notifications and download data relevant to their work.
+
+The standard notification message format ensures that the WIS2 ecosystem (data publisher, data
+user, and global services) is a robust, effective, and unified exchange platform for weather,
+climate, and water data.
+
+This document defines the structure of the WIS Topic Hierarchy.  Topics are utilized by WIS Nodes, Global
+Broker services, and data/metadata subscribers.
+
+The following are keywords to be used by search engines and document catalogues.
+
+wmo, wis 2.0, weather, climate, water, topic hierarchy, metadata, pubsub, mqp, message queuing protocol
+
+[big]*iii.    Security Considerations*
+
+Based on the WMO Unified Data Policy for the International Exchange of Earth System Data (Resolution 1 (Cg-Ext(2021) footnote:[https://library.wmo.int/doc_num.php?explnum_id=11113#page=9], exchanged data are classified as `+core+` or `+recommended+`.  Core data is considered fully open and unrestricted with no security considerations.  Recommended data may have access control defined.
+
+No security considerations have been made for this standard.

standard/sections/clause_1_scope.adoc

@@ -0,0 +1,7 @@
+== Scope
+
+This document defines the topic hierarchy used by WIS message brokers to manage message delivery to subscribers and / or recipients.
+
+This specification defines the conformance requirements for the WIS2 Topic Hierarchy.  Annex A defines the abstract test suite.
+
+All other topic structure specifications are not in scope.

standard/sections/clause_2_conformance.adoc

@@ -0,0 +1,14 @@
+== Conformance
+
+Conformance with this standard shall be checked using the tests specified in Annex A (normative) of this document.
+
+WIS Global Brokers and Nodes are required to comply with all conformance classes of this specification in support
+of providing MQP services in alignment with the defined topic structure.
+
+WMO shall publish guidance material to assist WIS Global Brokers and Nodes in constructing valid topic structures.
+
+This standard identifies one Conformance Class which defines the functional requirements.
+
+The mandatory Conformance Class for this specification is:
+
+* "WIS2 Topic Hierarchy Core"

standard/sections/clause_3_references.adoc

@@ -0,0 +1,6 @@
+== References
+
+* OASIS: MQTT Version 5.0 (2019) footnote:[https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html]
+* OASIS: MQTT Version 3.1.1 (2014) footnote:[http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html]
+* Wikipedia: Publish-subscribe pattern (2023) footnote:[https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern]
+* International Telecommunications Union (ITU): T.50 : International Reference Alphabet (IRA) (Formerly International Alphabet No. 5 or IA5) - Information technology - 7-bit coded character set for information interchange footnote:[https://www.itu.int/rec/T-REC-T.50]