FT2025-2

guide/sections/part1/data-consumer.adoc

@@ -12,7 +12,7 @@ The Global Discovery Catalogue is accessible via an API and provides a low-barri
 
 ==== 1.2.2 How to subscribe to notifications about the availability of new data
 
-WIS2 provides notifications about updates to datasets, for example, a notification may indicate that a new observation record from an automatic weather station has been added to a dataset of surface observations. These notifications are published on Message Brokers. Where data consumers need to use data rapidly once they have been published (for example, as inputs to a weather prediction model), they should subscribe to one or more Global Brokers to get notification messages using Message Queuing Telemetry Transport (MQTT) protocol.footnote[Subscribing to notifications about newly available data ensures that the data consumers do not need to continually to poll the data server to check for updates.]
+WIS2 provides notifications about updates to datasets, for example, a notification may indicate that a new observation record from an automatic weather station has been added to a dataset of surface observations. These notifications are published on Message Brokers. Where data consumers need to use data rapidly once they have been published (for example, as inputs to a weather prediction model), they should subscribe to one or more Global Brokers to get notification messages using Message Queuing Telemetry Transport (MQTT) protocol.footnote:[Subscribing to notifications about newly available data ensures that the data consumers do not need to continually to poll the data server to check for updates.]
 
 In WIS2, notifications are republished by Global Brokers to ensure resilient distribution. Consequently, there will be multiple places where one can subscribe. Data consumers requiring real-time notifications must subscribe to Global Brokers. Data consumers should subscribe to more than one Global Broker to ensure that notifications continue to be received if a Global Broker instance fails.
 

guide/sections/part1/data-publisher.adoc

@@ -27,16 +27,18 @@ Copies of all discovery metadata records from WIS2 are held in the Global Discov
 Depending on local arrangements, your GISC may be able to assist in transferring discovery metadata record(s) to the Global Discovery Catalogues. If this is not the case, data publishers will need to publish the discovery metadata record(s) themselvesfootnote:[In the future, WIS2 may provide metadata publication services (for example, through a WIS2 metadata management portal) to assist with this task. However, such services are not currently available.] using one of two methods:
 
 * The simplest method is to encode the discovery metadata record as a file and publish it to an HTTP server, where it can be accessed with a URL. 
-* Alternatively, a data publisher may operate a local metadata catalogue through which discovery metadata records can be shared using an API (for example, OGC API – Recordsfootnote:[See OGC API - Records - Part 1: Core: https://docs.ogc.org/DRAFTS/20-004.html.]). Each discovery metadata record (for instance, an item that is part of the discovery metadata catalogue) can be accessed with a unique URL via the API .
+* Alternatively, a data publisher may operate a local metadata catalogue through which discovery metadata records can be shared using an API (for example, OGC API – Records). Each discovery metadata record (for instance, an item that is part of the discovery metadata catalogue) can be accessed with a unique URL via the API.
 
-In both cases, a notification message needs to be published on a Message Broker that tells WIS2 that there is a new discovery metadata record to upload and that it can be accessed at the specified URL.footnote:[Both data and metadata are published using the same notification message mechanism to announce the availability of new resources.] Notification messages shall conform to the specification given in the _Manual on WIS_, Volume II - Appendix E. WIS2 Notification Message. They must also be published on a topic that conforms to the specification given in the _Manual on WIS_, Volume II - Appendix D. WIS2 Topic Hierarchy. For example, metadata published by Deutscher Wetterdienst would use the following topic: ``origin/a/wis2/de-dwd/metadata/core``.
+In both cases, a notification message needs to be published on a Message Broker that tells WIS2 that there is a new discovery metadata record to upload and that it can be accessed at the specified URL.footnote:[Both data and metadata are published using the same notification message mechanism to announce the availability of new resources.] Notification messages shall conform to the specification given in the _Manual on WIS_, Volume II - Appendix E. WIS2 Notification Message. They must also be published on a topic that conforms to the specification given in the _Manual on WIS_, Volume II - Appendix D. WIS2 Topic Hierarchy. For example, metadata published by Deutscher Wetterdienst would use the following topic: ``origin/a/wis2/de-dwd/metadata``.
 
 These discovery metadata records are then propagated through the Global Service components into the Global Discovery Catalogue, where data consumers can search and browse for datasets of interest.
 
 Upon receipt of a new discovery metadata record, a Global Discovery Catalogue (see <<_2_4_4_global_discovery_catalogue>>) will validate, assess, ingest, and publish the record. Validation ensures compliance with the specification, while the assessment evaluates the discovery record against good practices. The Global Discovery Catalogue will notify the data publisher if the discovery metadata record fails validation and provide recommendations for improvements. 
 
 Discovery metadata must be published in the Global Discovery Catalogues before the data are published.
 
+Discovery metadata should be re-published on a daily basis.
+
 ==== 1.3.3 How to provide data to WIS2
 
 WIS2 is based on the web architecture.footnote:[See Architecture of the World Wide Web, Volume One: https://www.w3.org/TR/webarch/.] As such it is _resource oriented_. Datasets are resources; the "granules" of data grouped in a dataset are resources; and the discovery metadata records that describe datasets are resources. In web architecture, every resource has a unique identifier (such as a URIfootnote:[See RFC 3986 - Uniform Resource Identifier (URI) - Generic Syntax: https://datatracker.ietf.org/doc/html/rfc3986.]), which can be used to resolve the identified resource and interact with it (for example, to download a representation of the resource over an open-standard protocol such as HTTP).

guide/sections/part2/global-services.adoc

@@ -5,9 +5,9 @@ The successful operation of WIS2 depends on a set of Global Services running wel
 
 Depending on the nature of the Global Service, the following are the minimum capabilities needed to ensure that the level of service as a whole reaches 100% (or very close):
 
-*	Three Global Brokers, with each Global Broker connected to at least two other Global Brokers;
-*	Three Global Caches, with each Global Cache connected to at least two Global Brokers and capable of downloading data from all WIS2 Nodes providing core data;
-*	Two Global Discovery Catalogues, with each Global Discovery Catalogue connected to at least one Global Broker;
+* Three Global Brokers, with each Global Broker connected to at least two other Global Brokers;
+* Three Global Caches, with each Global Cache connected to at least two Global Brokers and capable of downloading data from all WIS2 Nodes providing core data;
+* Two Global Discovery Catalogues, with each Global Discovery Catalogue connected to at least one Global Broker;
 * Two Global Monitors - each Global Monitor should scrape the metrics from all other Global Services
 
 In addition to the above, WIS architecture can accommodate adding (or removing) Global Services. Candidate WIS centres should inform their WIS NFP and contact the WMO Secretariat to discuss their offer to provide a Global Service.
@@ -36,11 +36,10 @@ WIS2 Global Services (Global Brokers, Global Caches, and Global Discovery Catalo
 
 There is no requirement for WIS2 Nodes to provide monitoring metrics. However their WIS2 interfaces may be queried remotely by Global Services, which can then provide metrics on the availability of WIS2 Nodes.
 
-Metrics for WIS2 monitoring should follow the naming convention ``wmo_<program>_<name>``, where ``<program>`` is the name of the responsible WMO programme and ``<name>`` is the name of the metric. Examples of WIS2 metrics include:
+Metrics for WIS2 monitoring should follow the naming convention ``wmo_<program>_<name>``, where ``<program>`` is the name of the responsible WMO programme and ``<name>`` is the name of the metric. Examples of WIS2 metrics include (but are not limited to):
 
-  ``wmo_wis2_gc_downloaded_total``, and
-
-  ``wmo_wis2_gb_messages_invalid_total``.
+*  ``wmo_wis2_gc_downloaded_total``
+*  ``wmo_wis2_gb_messages_invalid_total``
 
 The full set of the WIS2 monitoring metrics is given in WMO: WIS2 Metric Hierarchy footnote:[See https://github.com/wmo-im/wis2-metric-hierarchy.]
 
@@ -83,6 +82,7 @@ In the following sections, and for each Global Service, a set of metrics is defi
 ** An off the shelf broker implementing both MQTT 3.1.1 and MQTT 5.0 in a highly available setup, typically in a cluster mode. Tools such as EMQX, HiveMQ, VerneMQ, RabbitMQ (in its latest versions) are compliant with these requirements. The open source version of Mosquitto cannot be clustered and therefore should not be used as part of a Global Broker.
 ** Additional features, including anti-loop detection, notification message format compliance, validation of the published topic, and metrics provision.
 
+* When connected to a local WIS centre broker or a Global Service broker, the metric ``wmo_wis2_gb_connected_flag`` will be equal to 1. When the connection cannot be established or is interrupted the metric ``wmo_wis2_gb_connected_flag`` will be equal to 0.
 * When receiving a message from a local WIS centre broker or a Global Service broker, the metric ``wmo_wis2_gb_messages_received_total`` will be increased by 1.
 * A Global Broker will check if a discovery metadata record exists corresponding to the topic on which a message has been published. If there is no corresponding discovery metadata record, the Global Broker will discard non-compliant messages and will raise an alert. The metric ``wmo_wis2_gb_messages_no_metadata_total`` will be increased by 1. The Global Broker should not request information from a Global Discovery Catalogue for each notification message but should keep a cache of all valid topics for every ``centre-id``.
 * A Global Broker will check that the topic on which the message is received is valid. If the topic is invalid, the Global Broker will discard non-compliant messages and will raise an alert. The metric ``wmo_wis2_gb_invalid_topic_total`` will be increased by 1.
@@ -91,7 +91,7 @@ In the following sections, and for each Global Service, a set of metrics is defi
 * A Global Broker will republish a message only once. It will record the message identifier (``id``) (as defined in the WIS2 Notification Message) of messages already published and will discard subsequent identical messages (those with the same message ``id``). This is the anti-loop feature of the Global Broker.
 * When publishing a message to the local broker, the metric ``wmo_wis2_gb_messages_published_total`` will be increased by 1.
 * All above-defined metrics will be made available on HTTPS endpoints that the Global Monitor will ingest from regularly.
-* As a convention, the Global Broker centre-id will be ``tld-{centre-name}-global-broker``.
+* As a convention, the Global Broker centre-id will be ``{tld}-{centre-name}-global-broker``.
 * A Global Broker should operate with a fixed IP address so that WIS2 Nodes can permit access to download resources based on IP address filtering. A Global Broker should also operate with a publicly resolvable Domain Name System (DNS) name pointing to that IP address. The WMO Secretariat must be informed of the IP address and/or hostname and any subsequent changes.
 
 ==== 2.7.4 Global Cache
@@ -120,7 +120,7 @@ In WIS2, Global Caches provide access to WMO core data for data consumers. This
 * If core data are not cached on a Global Cache (that is, if the data are flagged as ``"cache": false`` or if the Global Cache decides not to cache these data), the Global Cache shall nevertheless republish the WIS2 Notification Message to the ``cache/a/wis2/...`` topic. In this case, the message id will be changed, and the rest of the message will not be modified.
 * A Global Cache should operate with a fixed IP address so that WIS2 Nodes can permit access to download resources based on IP address filtering. A Global Cache should also operate with a publicly resolvable DNS name pointing to that IP address. The WMO Secretariat must be informed of the IP address and/or hostname, and any subsequent changes.
 * A Global Cache should validate the integrity of the resources it caches and only accept data that match the integrity value from the WIS2 Notification Message. If the WIS2 Notification Message does not contain an integrity value, the Global Cache should accept the data as valid. In this case, the Global Cache may add an integrity value to the message it republishes.
-* As a convention, the Global Cache centre-id will be ``tld-{centre-name}-global-cache``.
+* As a convention, the Global Cache centre-id will be ``{tld}-{centre-name}-global-cache``.
 
 ===== 2.7.4.2 Practices and procedures
 
@@ -138,6 +138,7 @@ In WIS2, Global Caches provide access to WMO core data for data consumers. This
 **** If the message contains an integrity value for the data, verify the integrity of the data;
 **** If data is downloaded successfully,  move the data to the HTTP endpoint of the Global Cache;
 **** Wait until the data becomes available at the endpoint;
+**** Add the property ``properties.global-cache`` with the value of the centre identifier of the Global Cache to identify the origin of the data source downloaded by downstream applications;
 **** Modify the message identifier and the canonical link's ``href`` of the received message and leave all other fields untouched;
 **** Republish the modified message to topic ``cache/a/wis2/...`` ,matching the ``+/a/wis2/...`` where the original message has been received;
 **** The metric ``wmo_wis2_gc_downloaded_total`` will be increased by 1; The metric ``wmo_wis2_gc_dataserver_last_download_timestamp_seconds`` will be updated with the timestamp (in seconds) of the last successful download from the WIS2 Node or Global Cache;
@@ -156,12 +157,12 @@ In WIS2, Global Caches provide access to WMO core data for data consumers. This
 ===== 2.7.5.1 Technical considerations
 
 * The Global Discovery Catalogue provides data consumers with a mechanism for discovering and searching for datasets of interest as well as learning how to interact with and find out more information about those datasets.
-* The Global Discovery Catalogue implements the OGC API – Records – Part 1: Core standardfootnote:[See OGC-API Records - Part 1 https://docs.ogc.org/DRAFTS/20-004.html.], adhering to the following conformance classes and their dependencies:
+* The Global Discovery Catalogue implements the OGC API – Records – Part 1: Core standardfootnote:[See OGC-API Records - Part 1 https://docs.ogc.org/is/20-004r1/20-004r1.html.], adhering to the following conformance classes and their dependencies:
 ** Searchable Catalog (Deployment);
 ** Searchable Catalog - Sorting (Deployment);
 ** Searchable Catalog - Filtering (Deployment);
-** JSON (Building Block);
-** HTML (Building Block).
+** JSON (Common Component);
+** HTML (Common Component).
 * The Global Discovery Catalogue will make discovery metadata available via the collection identifier `wis2-discovery-metadata`.
 * The Global Discovery Catalogue advertises the availability of datasets and how to access them or subscribe to updates.
 * The Global Discovery Catalogue does not advertise or list the availability of individual data objects that comprise a dataset (that is, data files).
@@ -181,13 +182,13 @@ In WIS2, Global Caches provide access to WMO core data for data consumers. This
 * A Global Discovery Catalogue will generate and store a zip file of all WCMP2 records once a day; this file will be made be accessible via HTTP. The zipfile will include a directory named after the centre-id of the Global Discovery Catalogue containing all WCMP2 records.
 * A Global Discovery Catalogue will publish a WIS2 Notification Message of its zip file of all WCMP2 records on its centre-id's +metadata+ topic (for example, `origin/a/wis2/centre-id/metadata`, where `centre-id` is the centre identifier of the Global Discovery Catalogue).
 * A Global Discovery Catalogue may initialize itself (cold start) from a zip file of all WCMP2 records published.
-* As a convention, a Global Discovery Catalogue's centre-id will be ``tld-{centre-name}-global-discovery-catalogue``.
+* As a convention, a Global Discovery Catalogue's centre-id will be ``{tld}-{centre-name}-global-discovery-catalogue``.
 
-===== 2.7.5.2 Global Discovery Catalogue reference implementation: wis2-gdc
+===== 2.7.5.2 Global Discovery Catalogue Reference Implementation: wis2-gdc
 
 To provide a Global Discovery Catalogue, Members may use whichever software components they consider most appropriate to comply with the WIS2 technical regulations.
 
-To assist Members in participating in WIS2, a free and open-source Global Discovery Catalogue reference implementation, wis2-gdc, is available for download and use. wis2-gdc builds on mature and robust free and open-source software components that are widely adopted for operational use.
+To assist Members in participating in WIS2, a free and open-source Global Discovery Catalogue Reference Implementation, wis2-gdc, is available for download and use. wis2-gdc builds on mature and robust free and open-source software components that are widely adopted for operational use.
 
 wis2-gdc provides the functionality required for the Global Discovery Catalogue, including the following technical functions:
 
@@ -210,5 +211,5 @@ wis2-gdc is managed as a free and open source project. Source code, issue tracki
 * The Global Monitor will collect metrics as defined in the OpenMetrics standard.
 * The Global Monitor will monitor the "health" (that is, the performance) of components at NCs/DCPCs, as well as Global Services.
 * The Global Monitor will provide a web-based dashboard that displays the WIS2 system performance and data availability.
-* As a convention, the Global Monitor centre-id will be ``tld-{centre-name}-global-monitor``.
+* As a convention, the Global Monitor centre-id will be ``{tld}-{centre-name}-global-monitor``.
 * The main task of the Global Monitor will be to regularly query the metrics provided by the relevant WIS2 entities, aggregate and process the data and then provide the results to the end user in a suitable presentation. 

guide/sections/part2/operations.adoc

@@ -277,7 +277,7 @@ harvest and merge these catalogues, creating a global map of the ocean
 data. IODE harvests all metadata shared by ODIS partners, combines 
 these metadata and creates a knowledge graph, and processes these metadata to export derivative 
 products (for example, diagnostic reports and cloud-optimized data products). 
-The Ocean InfoHub (OIH) system is IODE's reference implementation of a 
+The Ocean InfoHub (OIH) system is IODE's Reference Implementation of a
 discovery system leveraging ODIS. ODIS architecture and tools are
 free and open-source software (FOSS), with regular releases published for the
 community.