World Meteorological Organization

Date: 2024-10-23

Version: 1.0.0

Document location: TBD

Document status: DRAFT

Standing Committee on Information Management and Technology (SC-IMT)[1]

Commission for Observation, Infrastructure and Information Systems (INFCOM)[2]

Copyright © 2024 World Meteorological Organization (WMO)

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. The notification message received from the MQP broker contains a URL to download the data. In addition, the MQP broker offers a range of topics organised in a hierarchy. The 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 content, structure, and encoding for the WIS2 Notification Message Encoding. This standard is an extension of the OGC API - Features standard [3]. WIS2 Notification Message documents are provided as MQP payloads by WIS2 nodes, Global Broker services, as well as Replay API services (optional OGC API - Features services for data notifications).

WIS2 Notification Message documents shall be encoded in GeoJSON (RFC7946 [4]) as defined in this specification and shall be made available as MQP payloads. Additionally, they can be provisioned as defined by OGC API - Features.

Weather/climate/water data is by nature geospatial and temporal. The W3C Data on the Web Best Practices [5] and Spatial Data on the Web Best Practices [6] publications provide guidelines on how to best enable spatiotemporal data to lower the barrier for users, search engine optimization, and linked data. This also aligns with the FAIR data principles (Findable, Accessible, Interoperable, Reusable) [7].

ii. Keywords

The following are keywords to be used by search engines and document catalogues.

wmo, wis 2.0, weather, climate, water, metadata, pubsub, mqp, message queuing protocol, GeoJSON

iii. Security Considerations

Based on the WMO Unified Data Policy for the International Exchange of Earth System Data (Resolution 1 (Cg-Ext(2021) [8], 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.

1. Scope

This document defines the content, structure, and encoding of a notification message published as part of a WIS2 Global Broker or a Replay API service.

The WIS2 Notification Message Encoding standard defined herein is an extension of the International Standard GeoJSON.

WIS2 Notification Message documents shall be encoded as GeoJSON as defined in OGC API - Features - Part 1: Core.

The primary purpose of WIS2 Notification Messages are to notify subscribers or clients of new data being published.

This specification defines the conformance requirements for the WIS2 Notification Message Encoding. Annex A defines the abstract test suite.

2. Conformance

Conformance with this standard shall be checked using the tests specified in Annex A (normative) of this document.

GeoJSON provides an encoding for encoding geographic features (geometry, attributes). This standard is an extension of GeoJSON.

Data providers are required to comply with all conformance classes of this specification in support of providing MQP services.

WMO shall publish guidance material to assist data providers in constructing WIS2 Notification Messages.

This standard identifies one Requirements Class which defines the functional requirements.

The mandatory Requirements Class for this specification is:

  • "WIS2 Notification Message Encoding Core"

3. References

  • OGC: OGC 17-069r, OGC API - Features - Part 1: Core 1.0.1 (2022) [9]

  • IETF: RFC-7946 The GeoJSON Format (2016) [10]

  • IETF: RFC-8259 The JavaScript Object Notation (JSON) Data Interchange Format (2017) [11]

  • IETF: RFC 3339: Date and Time on the Internet: Timestamps (2002) [12]

  • IETF: RFC 4122: A Universally Unique IDentifier (UUID) URN Namespace (2005) [13]

  • W3C/OGC: Spatial Data on the Web Best Practices, W3C Working Group Note (2017) [14]

  • W3C: Data on the Web Best Practices, W3C Recommendation (2017) [15]

  • W3C: Data Catalog Vocabulary, W3C Recommendation (2014) [16]

  • IANA: Link Relation Types (2020) [17]

  • IETF: JSON Schema (2022) [18]

  • WMO: WIS2 Topic Hierarchy (2022) [19]

4. Terms and definitions

This document uses the terms defined in OGC Policy Directive 49, which is based on the ISO/IEC Directives, Part 2, Rules for the structure and drafting of International Standards. In particular, the word “shall” (not “must”) is the verb form used to indicate a requirement to be strictly followed to conform to this Standard and OGC documents do not use the equivalent phrases in the ISO/IEC Directives, Part 2.

This document also uses terms defined in the OGC Standard for Modular specifications (OGC 08-131r3), also known as the 'ModSpec'. The definitions of terms such as standard, specification, requirement, and conformance test are provided in the ModSpec.

The following additional terms and definitions also apply.

4.1. Abbreviated terms

Table 1. Symbols and abbreviated terms
Abbreviation Term

API

Application Programming Interface

DCPC

Data Collection and Production Centres

GDC

Global Discovery Catalogue

GIS

Geographic Information System

GISC

Global Information System Centre

HTML

Hypertext Markup Language

HTTP

Hypertext Transfer Protocol

HTTPS

Hypertext Transfer Protocol Secure

IANA

Internet Assigned Numbers Authority

IETF

Internet Engineering Task Force

ISO

International Organization for Standardization

JSON

JavaScript Object Notation

MQP

Message Queuing Protocol

MQTT

Message Queuing Telemetry Transport

NC

National Centre

NWP

Numerical Weather Prediction

OGC

Open Geospatial Consortium

PubSub

Publish / Subscribe

URI

Uniform Resource Identifier

URL

Uniform Resource Locator

UUID

Universally Unique Identifier

W3C

World Wide Web Consortium

WCMP

WMO Core Metadata Profile

WIS

WMO Information System

WMO

World Meteorological Organization

WNM

WIS2 notification message

5. Conventions

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

5.1. Identifiers

The normative provisions in this Standard are denoted by the URI:

All requirements and conformance tests that appear in this document are denoted by partial URIs which are relative to this base.

5.2. Examples

Examples provided in this specification are encoded as GeoJSON.

Complete examples can be found at https://schemas.wmo.int/wnm/1.0.0/examples

5.3. Schemas

The WIS2 Notification Message schema can be found at https://schemas.wmo.int/wnm/1.0.0/schemas/wis2-notification-message-bundled.json

5.4. Schema representation

JSON Schema [20] objects are used throughout this standard to define the structure of metadata records. These schema objects are also typically represented using YAML [21]. YAML is a superset of JSON, and in this standard are regarded as equivalent.

Metadata record instances are always defined as JSON.

5.4.1. Properties

A JSON property represents a key-value pair, where the key is the name of the property and the value is a standard JSON data type.

"myPropertyName": "test123"

6. Introduction

A WIS2 Notification Message (WNM) provides descriptive information about data or metadata made available through WIS 2.0. The standard notification message format ensures that the WIS2 ecosystem (data publisher, data user, and global services) is a robust, effective, and unified data exchange platform for weather, climate, and water.

WIS2 Notification Message documents are provided as MQP payloads by WIS2 nodes, Global Broker services, as well as Replay API services.

A WNM provides notification metadata about data or metadata published to WIS2, including when the data was published, its spatial and temporal characteristics, and where to access and download.

6.1. Motivation

MQP brokers provide "push" based services, supporting event-driven workflows, maximizing efficient use of network, bandwidth, and rapid response to time-sensitive events (e.g. severe weather events). However, MQP brokers do not specify a payload encoding. Using GeoJSON as a baseline for this specification provides broad interoperability, lowering the barrier and extending the reach of data in the WIS2 ecosystem and beyond.

6.2. Scenarios

The following scenarios are useful in understanding the drivers and principles that were used in the development of this specification:

6.2.1. Publish, Subscribe, Download

Event driven (PubSub) workflow involves a client connecting to a MQP broker, subscribing to one or more topics and receiving relevant notifications. Notifications provide information to ensure data integrity and spatiotemporal extents of a data granule.

6.2.2. Replay API workflow

API workflow involves a client connecting to an OGC API - Features services in order to query for messages in the past using spatial, temporal, or attribute predicates. A Replay API workflow is valuable in situations where connections to MQP brokers may drop, thereby allowing a given subscriber to gather past messages.

7. WIS2 Notification Message

Note: This section of working draft document is the same as Appendix E in the Manual on the WMO Information System (WMO-No. 1060), Volume II.

The WIS2 Notification Message (WNM) is an extension of the Open Geospatial Consortium OGC API - Features standard and shall be encoded in GeoJSON. The normative provisions in the WIS2 Notification Message are denoted by the base URI (http://wis.wmo.int/spec/wnm/1) and requirements are denoted by partial URIs relative to this base. Property names, values and examples are represented with shaded text in this document.

1. Requirements Class "Core"

URI

http://wis.wmo.int/spec/wnm/1/req/core

Target type

Notification metadata

Dependency

The JavaScript Object Notation (JSON) Data Interchange Format (IETF RFC8259 (2017))

Dependency

JSON Schema (2022)

Dependency

The GeoJSON Format (IETF: RFC-7946 (2016))

Dependency

OGC API – Features – Part 1: Core corrigendum (OGC: OGC 17-069r)

Preconditions

The record conforms to GeoJSON (RFC7946)

1.1 Overview

The table below provides an overview of the set of properties that may be included in a WNM.

Table 2. WNM core properties
Property Requirement Description

id

Required

A universally unique identifier (UUID) of the message (see 1.4 Identifier)

type

Required

A fixed value denoting the record as a GeoJSON Feature (see 1.3 GeoJSON compliance)

conformsTo

Required (one of conformsTo or version)

The version of WNM associated that the record conforms to (see 1.5 Conformance).

version

Required (one of conformsTo or version)

DEPRECATED Please use conformsTo (see 1.5 Conformance)

geometry

Required

Geospatial location associated with the data or metadata (see 1.7 Geometry)

properties.pubtime

Required

The date and time when the notification was published, in RFC3339 format, Coordinated Universal Time (UTC) (see 1.8 Properties / Publication time)

properties.data_id

Required

Unique identifier of the data as defined by the data producer (see 1.9 Properties / Data identification)

properties.metadata_id

Optional

Identifier for associated discovery metadata record to which the notification applies (see 1.10 Properties / Metadata identification)

properties.producer

Optional

Identifies the provider that initially captured and processed the source data, in support of data distribution on behalf of other Members (see 1.11 Properties / Producer)

properties.datetime

Optional

Identifies the reference date and time of the data instance to which the notification is relayed, in RFC3339 format, UTC (see 1.12 Properties / Temporal description)

properties.start_datetime

Optional

Identifies the start date and time of the data being published, in RFC3339 format (see 1.12 Properties / Temporal description)

properties.end_datetime

Optional

Identifies the end date and time of the data being published, in RFC3339 format (see 1.12 Properties / Temporal description)

properties.cache

Optional

Indicates whether the data in the notification should be cached (if not specified, the default value is true) (see 1.13 Properties / Cache)

properties.integrity

Optional

Specifies a checksum to be applied to the data to ensure that the download is accurate (see 1.14 Properties / Integrity)

properties.content

Optional

Used to embed small products inline within the message (see 1.15 Properties / Content)

links

Required

Online linkages for data retrieval or additional resources associated with the dataset (see 1.16 Links)

1.2 Message size

The WIS2 Notification Message allows for the transmission of messages in a compact manner and includes the ability to embed content inline as required (see 1.15 Properties / Content).

Requirement 1

/req/core/message_size

A

A WNM message SHALL NOT exceed 8 192 bytes.

1.3 GeoJSON compliance

The WIS2 Notification Message schema is based on GeoJSON (RFC7946) and its associated information model. Compliant messages are therefore compliant with GeoJSON.

Requirement 2

/req/core/validation

A

Each WNM SHALL validate without error against the WNM schema.

B

Each WNM SHALL provide id, type, geometry and properties properties for GeoJSON compliance.

C

Each WNM record type property SHALL be set to a fixed value of Feature for GeoJSON compliance.

1.4 Identifier

A universally unique identifier of the message is generated by the originator of the message, using the UUID standard (RFC4122). It provides the anti-loop feature that is needed to ensure that the message will be seen once by all Global Brokers. It remains the same throughout the lifetime of the message in the WIS2 ecosystem.

The data_id is retained to ensure traceability and consistency of the same resource (see 1.9 Properties / Data identification).

Example:

"id": "31e9d66a-cd83-4174-9429-b932f1abe1be"

Requirement 3

/req/core/identifier

A

The id property SHALL be a Universally Unique Identifier (UUID).

1.5 Conformance

The conformsTo property to identifies the version of the WNM standard to which the notification conforms. Conformance identification is valuable for version detection and handling of content.

Note
that conformsTo replaces version. For the deprecation period, only one (but not both) of conformsTo or version are permitted.
Example:
"conformsTo": [
  "http://wis.wmo.int/spec/wnm/1/conf/core"
]

Requirement 4

/req/core/conformance

A

A WNM SHALL provide information on conformance via the OAFeat conformsTo property.

B

The conformsTo property SHALL advertise conformance to WNM.

1.6 Version

DEPRECATED Please use conformsTo.

The version property provides the version of WNM that the message conforms to.

Note
that conformsTo replaces version. For the deprecation period, only one (but not both) of conformsTo or version are permitted.

Requirement 5

/req/core/version

A

A WNM SHALL provide information on version conformance via the version property.

B

The version property SHALL be fixed to v04 for this version of the specification.

1.7 Geometry

The type of geometry in a notification message may be Point or Polygon. It can also be type null if the geometry cannot be derived.

Example: Point
{
  ...
  "geometry": {
    "type": "Point",
    "coordinates": [
      6.146255135536194,
      46.223296618227444
    ]
  }
  ...
}
Example: Point with elevation
{
  ...
  "geometry": {
    "type": "Point",
    "coordinates": [
      6.146255135536194,
      46.223296618227444,
      392
    ]
  }
  ...
}
Example: Polygon
{
  ...
  "geometry": {
    "type": "Polygon",
    "coordinates": [[
      [-7.75,40.43],
      [-7.75,78.46],
      [71.91,78.46],
      [71.91,40.43],
      [-7.75,40.43]
    ]]
  }
  ...
}
Example: null
{
  ...
  "geometry": null
  ...
}

Requirement 6

/req/core/geometry

A

A WNM record SHALL provide one geometry property to convey the geospatial properties of a notification using a geographic coordinate reference system (World Geodetic System 1984 [WGS 84]) with longitude and latitude decimal degree units.

B

The geometry property SHALL only provide one of a Point or Polygon geometry, or a null value when a geometry value is unknown or cannot be determined.

Permission 1

/per/core/geometry

A

The geometry property MAY provide a third element (height) as per clause 4 of the GeoJSON specification.

1.8 Properties / Publication time

The pubtime property identifies the date/time when the notification was first posted or published by the originator. The date/time is encoded in RFC3339 format, using UTC (Z).

The publication date/time is critical for subscribers. It prevents message loss by providing awareness among subscribers about how far behind the publisher they may be.

The pubtime property is also valuable for change detection as part of updates and deletion notifications.

Ensuring that pubtime is properly managed for updates and deletions is important for data and metadata download workflows. For example, an out-of-date pubtime can lead to errors for clients when managing updates or deletions in their local copies of data. An update with a newer pubtime and identical datetime indicates a newer version of the data or metadata.

Example:

"properties": {
  ...
  "pubtime": "2022-03-20T04:50:18.314854383Z"
  ...
}

Requirement 7

/req/core/pubtime

A

A WNM SHALL provide a properties.pubtime property.

B

The properties.pubtime property SHALL be in RFC3339 format.

C

The properties.pubtime property SHALL be in UTC.

D

The properties.pubtime property SHALL be set to the current time by the original publisher of the notification.

E

The properties.pubtime property SHALL be set to the current time also for notifications about updates or deletions.

F

The properties.pubtime property SHALL NOT be modified by any intermediaries.

1.9 Properties / Data identification

The data_id property uniquely identifies the data described by the notification and is defined by the data producer. A data producer may use an identification scheme of their choice.

Example:

"properties": {
  ...
  "data_id": "wis2/ma-marocmeteo/data/core/weather/surface-based-observations/synop/WIGOS_0-504-1-60288_20240210T130000"
  ...
}

Requirement 8

/req/core/data_id

A

A WNM SHALL provide a properties.data_id property.

B

The properties.data_id property SHALL be unique within the scope of the relevant dataset.

Recommendation 1

/rec/core/data_id

A

The properties.data_id property SHOULD NOT use an opaque id. It should be encoded with meaningful values to support client-side filtering.

Permission 2

/per/core/data_id

A

The properties.data_id property MAY contain a valid WIS2 topic, without the channel and version.

1.10 Properties / Metadata identification

The metadata_id property uniquely identifies the associated discovery metadata record. This property is an important linkage between a WMO Core Metadata Profile (WCMP) dataset discovery metadata record and the related data notifications. The inclusion of this property allows a subscriber to consult additional documentation of the dataset and understand the access control applied to the data.

Example:

"properties": {
  ...
  "metadata_id": "urn:wmo:md:ca-eccc-msc:observations.swob"
  ...
}

Recommendation 2

/rec/core/metadata_id

A

A WNM SHOULD provide a properties.metadata_id property that identifies the associated WCMP dataset discovery metadata record. See requirement for metadata identification in WCMP (Appendix F, 1.4 Identifier).

Permission 3

/per/core/metadata_id

A

A WNM MAY provide additional identifiers to discovery metadata records in non-WIS2 catalogue systems as a link object with (rel=related or rel=up).

1.11 Properties / Producer

The producer property identifies the provider that initially captured and processed the source data, in support of data distribution on behalf of other Members.

Example:

"properties": {
  ...
  "producer": "fra"
  ...
}

Recommendation 3

/rec/core/producer

A

A WNM SHOULD provide a properties.producer property when publishing data on behalf of other Members.

1.12 Properties / Temporal description

The datetime property identifies the date and time of the data (for example, when a measurement was observed). When data or metadata are updated or deleted, this value should identify the original data or metadata, which can be significantly different from the current time.

The start_datetime and end_datetime properties identify a temporal extent (for example, the start and end times of an NWP forecasting period). All dates and times are encoded in RFC3339 format using UTC (Z). A null value can also be used if a temporal description of the data cannot be derived.

Example: Temporal instant
"properties": {
  ...
  "datetime": "2022-03-20T04:45:00Z"
  ...
}
Example: Temporal extent
"properties": {
  ...
  "start_datetime": "2022-03-20T04:45:00Z",
  "end_datetime": "2022-03-22T04:45:00Z"
  ...
}
Example: No temporal description
"properties": {
  "datetime": null,
  ...
}

Requirement 9

/req/core/temporal

A

A WNM SHALL provide a temporal description by either a properties.datetime property or both the properties.start_datetime and properties.end_datetime properties.

B

The temporal description SHALL be in RFC3339 format.

C

The temporal description SHALL be in UTC.

D

The temporal description SHALL be set to null (using only properties.datetime) when a temporal description cannot be derived.

1.13 Properties / Cache

Core data, by default, is cached by Global Cache services, as described in the Guide to WIS, Volume II.

However, a data producer can use the properties.cache value to request Global Cache services to not cache their core data granule.

Example: Specifying data not to be cached
"properties": {
  "cache": false,
  ...
}

Permission 4

/per/core/cache

A

A WNM MAY specify, via the properties.cache property, whether the data should be cached .

1.14 Properties / Integrity

For data verification, it is recommended that data integrity information to be included via the integrity property. Providing this information will allow data consumers to ensure that a given data granule has not been corrupted during download.

The method property provides a format of the hashing method used to enable an integrity check of the data. The preferred values are sha256, sha384, sha512, sha3-256, sha3-384, and sha3-512.

The value property provides the result of the hashing method in base64 encoding.

Example:

"properties": {
  ...
  "integrity": {
    "method": "sha512",
    "value": "CPvTLiOfYRgfL3YNF/KKElwamwvLQwnzd96VnF2WoYuuH+hVIbwFSPQHHd/qa/fNVUBckviC5/HZs3Nx2jXEsA=="
  }
  ...
}

Recommendation 4

/rec/core/integrity

A

A WNM SHOULD provide a properties.integrity property, consisting of a method property identifying the hashing method (sha256, sha384, sha512, sha3-256, sha3-384, sha3-512) and a value property of the hashing result, when it can be easily derived.

1.15 Properties / Content

The content property allows for the inclusion of data in the notification message when the length of the data, once encoded, is smaller than 4 096 bytes.

The encoding property provides the character encoding of the data (UTF-8, base64 or gzip). The gzip encoding means that the data are compressed using the algorithm defined in RFC1952 and consequently converted to text using Base64 encoding.

The value property provides the data in accordance with the encoding property.

The size property provides the size, in bytes, of the data in its original unencoded form, and therefore this value shall not be directly compared with the size limit.

Example:

"properties": {
  ...
  "content": {
    "encoding": "utf-8",
    "value": "encoded bytes from the file",
    "size": 457
  }
  ...
}

Requirement 10

/req/core/content

A

For data whose resulting size in the encoded form is greater than 4 096 bytes, notifications SHALL NOT provide the data inline via properties.content.value. Note that the encoding may either enlarge the data size (for example, when binary data, such as BUFR, is Base64 encoded), or reduce the size (for example, when XML data are compressed with gzip).

Recommendation 5

/rec/core/content

A

A WNM SHOULD provide the content property, consisting of an encoding property (either utf-8, base64 or gzip), a value property of the data and a size property with the length of the data.

Permission 5

/per/core/content

A

For data whose resulting size (after possible compression) is less than 4 096 bytes, notifications MAY provide the data inline via properties.content.value.

The links array property consists of one or more objects providing URLs to access data.

Each link object provides:

  • An href property with a fully qualified link to access the data;

  • A rel property providing an IANA link relation or WIS link type describing the relationship between the link and the message;

  • A type property providing the media type of the data;

  • A length property providing the length (in bytes) indicating the size of the data;

  • A security property providing a description of the access control mechanism applied (for example, recommended data with restrictions).

Links are used to communicate new data or metadata notifications. Links can also communicate when data or metadata have been deleted or invalidated.

Example: Canonical link
"links": [{
  "href": "https://example.org/data/4Pubsub/92c557ef-d28e-4713-91af-2e2e7be6f8ab.bufr4",
  "rel": "canonical",
  "type": "application/bufr"
}]
Example: Multiple links
"links": [{
  "href": "https://example.org/data/4Pubsub/92c557ef-d28e-4713-91af-2e2e7be6f8ab.bufr4",
  "rel": "canonical",
  "type": "application/bufr"
}, {
  "href": "https://example.org/oapi/collections/my-dataset/items/my-data-granule",
  "rel": "item",
  "type": "application/json"
}]
1.16.1 Access control

For recommended data, WNM links may also provide links to resources that implement access control in support of authentication and authorization. In secure data use cases, a user needs to be able to detect access-controlled data as part of data discovery and evaluation. The example demonstrates how to express access control using HTTP Basic authentication for a given data access service.

Example: Access controlled link
"links": [{
  "rel": "data",
  "type": "application/json",
  "title": "link to WAF endpoint",
  "href": "https://example.org/data/secure-data",
  "security": {
    "default": {
      "type": "http",
      "scheme": "basic",
      "description": "Please contact the data provider for accessing this secured resource."
    }
  }
}]

1.17 Additional properties

A WIS2 Notification Message can be extended as required for organizational purposes by adding properties (of any type) in the message. Additional properties do not render a notification non-compliant with the provisions of this specification.

Example:

"properties": {
  ...
  "_comment": {
    "validationErrors": [
      "error 1",
      "error 2"
    ]
  }
  ...
}

Permission 7

/per/core/additional_properties

A

A WNM MAY provide additional properties of any type in any part of the document as needed.

2. WIS2 notification message resources

2.1 WMO Codes Registry

2.2 WMO schemas server

Validation schemas, examples and other resources are published at https://schemas.wmo.int/wnm.

Annex A: Conformance Class Abstract Test Suite (Normative)

Conformance Class: Core

label

http://wis.wmo.int/spec/wnm/1/conf/core

subject

Requirements Class "core"

classification

Target Type:Notification Metadata

Message size

label

/conf/core/message_size

subject

/req/core/message_size

test-purpose

Validate that a WNM has a valid message size.

Check that the size of the complete WNM does not exceed 8192 bytes.

Validation

label

/conf/core/validation

subject

/req/core/validation

test-purpose

Validate that a WNM is valid to the authoritative WNM schema.

Run JSON Schema validation on the WNM against the WNM authoritative schema.

Identifier

label

/conf/core/identifier

subject

/req/core/identifier

test-purpose

Validate that a WNM has a valid identifier.

Check for the existence of an id property in the WNM.

Check that the id property is a valid UUID.

Conformance

label

/conf/core/conformance

subject

/req/core/conformance

test-purpose

Validate that a WNM notification provides valid conformance information.

Check for the existence of a conformsTo property in the WNM notification.

In the WNM notification’s conformsTo array property, check that ONE of the values is equal to http://wis.wmo.int/spec/wnm/1/conf/core.

Version

label

/conf/core/identifier

subject

/req/core/identifier

test-purpose

Validate that a WNM has a valid version.

Check for the existence of an version property in the WNM.

Check that the id property is equal to v04.

Geometry

label

/conf/core/geometry

subject

/req/core/geometry

test-purpose

Validate that a WNM provides a valid geometry property.

Check for the existence of one geometry property in the WNM.

Check that all geometry.coordinates value data types are integers or floats.

Check that geometry.coordinates longitudinal values are between -180 and 180.

Check that geometry.coordinates latitudinal values are between -90 and 90.

Check that geometry property is a valid GeoJSON geometry.

Properties / Publication Time

label

/conf/core/pubtime

subject

/req/core/pubtime

test-purpose

Validate that a WNM has a valid pubtime.

Check for the existence of an properties.pubtime property.

Check that the properties.pubtime property is in RFC3339 format.

Check that the properties.pubtime property is in the UTC timezone.

Properties / Data Identification

label

/conf/core/data_id

subject

/req/core/data_id

test-purpose

Validate that a WNM has a valid data_id.

Check for the existence of an data_id property.

Properties / Temporal description

label

/conf/core/temporal

subject

/req/core/temporal

test-purpose

Validate that a WNM provides a valid temporal description.

Check for the existence of one properties.datetime or both properties.start_datetime and properties.end_datetime.

Check that the any of the properties.datetime or both properties.start_datetime and properties.end_datetime properties are in RFC3339 format.

Check that the any of the properties.datetime or both properties.start_datetime and properties.end_datetime properties are in the UTC timezone.

Annex B: Schemas (Normative)

Note
The schema document will only be published on https://schemas.wmo.int/wnm/1.0.0 once the standard has been approved.

WIS2 Notification Message Schema

$schema: https://json-schema.org/draft/2020-12/schema
$id: https://raw.githubusercontent.com/wmo-im/wis2-notification-message/main/schemas/notificationMessageGeoJSON.yaml
title: WIS2 Notification Message Encoding
description: WIS2 Notification Message Encoding

type: object
properties:
  id: 
    type: string
    format: uuid
    description: UUID (RFC4122) - Guarantee uniqueness of the message over (at least) a 24h period.
  conformsTo:
    type: array
    contains:
      const: http://wis.wmo.int/spec/wnm/1/conf/core
  version:
    type: string
    description: DEPRECATED, please use `conformsTo`.
    const: v04
  type:
    type: string
    enum:
      - Feature
  geometry:
    oneOf:
      - enum:
        - null
      - $ref: 'https://raw.githubusercontent.com/opengeospatial/ogcapi-features/master/core/openapi/schemas/pointGeoJSON.yaml'
      - $ref: 'https://raw.githubusercontent.com/opengeospatial/ogcapi-features/master/core/openapi/schemas/polygonGeoJSON.yaml'
  properties:
    type: object
    properties:
      pubtime:
        type: string
        format: date-time
        description: |
          Identifies the date/time of when the file was posted/published, in RFC3339 format.
          The publication date/time is critical for subscribers to prevent message loss by knowing
          their lag (how far behind the publisher they are).
      data_id: 
        type: string
        description: |
         Unique identifier of the data as defined by the data producer.
         Data producers SHOULD NOT use an opaque id, but something meaningful to support client side filtering.
      metadata_id:
        type: string
        description: |
         Identifier for associated discovery metadata record to which the notification applies to.
         The identification SHOULD be from a WCMP2 discovery metadata record identifier from the WIS2
         Global Discovery Catalogue. Identifiers based on external catalogue systems MAY be articulated as additional links.
      producer:
        type: string
        description: |
          Identifies the provider that initially captured and processed the source data, in support of data distribution on behalf of other Members.
      datetime:
        type:
          - string
          - null
        format: date-time
        description: Identifies the date/time of the data being published, in RFC3339 format.
      start_datetime:
        type: string
        format: date-time
        description: Identifies the start date/time date of the data being published, in RFC3339 format.
      end_datetime:
        type: string
        format: date-time
        description: Identifies the end date/time date of the data being published, in RFC3339 format.
      cache:
        type: boolean
        description: |
          Whether the data in the notification should be cached (if not specified, the default value is `true`).
          When set to `false`, WIS2 Global Cache services do not cache the canonical link, and publish the
          notification with an unmodified canonical link (which points back to the endpoint as specified by the data producer).
          The notification is always published by the Global Cache regardless to the `cache` topic.
        default: true
      integrity:
        type: object
        description: Specifies a checksum to be applied to the data to ensure that the download is accurate.
        properties:
          method:
            type: string
            description: |
                A specific set of methods for calculating the checksum algorithms:
                * ``sha256``: the Secure Hash Algorithm 2, 256 bits, value is base64 encoded.
                * ``sha384``: the Secure Hash Algorithm 2, 384 bits, value is base64 encoded.
                * ``sha512``: the Secure Hash Algorithm 2, 512 bits, value is base64 encoded.
                * ``sha3-256``: the Secure Hash Algorithm 3, 256 bits, value is base64 encoded.
                * ``sha3-384``: the Secure Hash Algorithm 3, 384 bits, value is base64 encoded.
                * ``sha3-512``: the Secure Hash Algorithm 3, 512 bits, value is base64 encoded.
            enum:
              - sha256
              - sha384
              - sha512
              - sha3-256
              - sha3-384
              - sha3-512
          value:
            type: string
            contentEncoding: base64
            description: Checksum value.
        required:
          - method
          - value
      content:
        type: object
        description: Used to embed small products inline within the message.
        properties:
          encoding:
            type: string
            description: Encoding of content
            enum:
              - utf-8
              - base64
              - gzip
          size:
            type: integer
            maximum: 4096
            description: |
              Number of bytes contained in the file. Together with the ``integrity`` property, it provides additional assurance that file content was accurately received.
              Note that the limit takes into account the data encoding used, including data compression (for example `gzip`).
          value:
            type: string
            description: The inline content of the file.
            maxLength: 4096
        required:
          - encoding
          - size
          - value
    required:
      - pubtime
      - data_id
    oneOf:
      - allOf:
        - required:
          - start_datetime
          - end_datetime
      - allOf:
        - required:
          - datetime

  links:
    type: array
    minItems: 1
    items:
      allOf:
        - $ref: 'https://raw.githubusercontent.com/opengeospatial/ogcapi-features/master/core/openapi/schemas/link.yaml'
        - properties:
            security:
              type: object
              $ref: https://raw.githubusercontent.com/OAI/OpenAPI-Specification/3.1.0/schemas/v3.0/schema.yaml#/definitions/Components/properties/securitySchemes

oneOf:
  - required:
    - id
    - conformsTo
    - type
    - geometry
    - properties
    - links
  - required:
    - id
    - version
    - type
    - geometry
    - properties
    - links

example:
  $ref: https://raw.githubusercontent.com/wmo-im/wis2-notification-message/main/examples/example1.json

Annex C: Examples (Informative)

WIS2 Notification Message Examples

Example: single observation including meaningful geometry, observation datetime and content
{
    "id": "31e9d66a-cd83-4174-9429-b932f1abe1be",
    "conformsTo": [
        "http://wis.wmo.int/spec/wnm/1/conf/core"
    ],
    "type": "Feature",
    "geometry": {
        "type": "Point",
        "coordinates": [
            6.146255135536194,
            46.223296618227444
        ]
    },
    "properties": {
        "pubtime": "2022-03-20T04:50:18Z",
        "datetime": "2022-03-20T04:45:00Z",
        "integrity": {
            "method": "sha512",
            "value": "A2KNxvks...S8qfSCw=="
        },
        "data_id": "dataset/123/data-granule/UANT01_CWAO_200445___15103.bufr4",
        "metadata_id": "urn:wmo:md:ca-eccc-msc:observations.swob",
        "content": {
            "encoding": "utf-8",
            "value": "encoded bytes from the file",
            "size": 457
        }
    },
    "links": [
        {
            "href": "https://example.org/data/4Pubsub/92c557ef-d28e-4713-91af-2e2e7be6f8ab.bufr4",
            "rel": "canonical",
            "type": "application/bufr"
        },
        {
            "href": "https://example.org/oapi/collections/my-dataset/items/my-data-granule",
            "rel": "item",
            "type": "application/json"
        }
    ]
}
Example: NWP product including polygon geometry, start_datetime and end_datetime. The polygon is an array with 5 elements. The first (and last) elements are most southwestern point of the rectangle using longitude and latitude and followed by other coordinates in a clockwise direction.
{
    "id": "31e9d66a-cd83-4174-9429-b932f1abe1be",
    "conformsTo": [
        "http://wis.wmo.int/spec/wnm/1/conf/core"
    ],
    "type": "Feature",
    "geometry": {
        "type": "Polygon",
        "coordinates": [
            [
                [
                    -7.75,
                    40.43
                ],
                [
                    -7.75,
                    78.46
                ],
                [
                    71.91,
                    78.46
                ],
                [
                    71.91,
                    40.43
                ],
                [
                    -7.75,
                    40.43
                ]
            ]
        ]
    },
    "properties": {
        "pubtime": "2022-03-20T04:50:18Z",
        "start_datetime": "2022-03-20T00:06:00Z",
        "end_datetime": "2022-03-20T00:12:00Z",
        "integrity": {
            "method": "sha512",
            "value": "A2KNxvks...S8qfSCw=="
        },
        "data_id": "dataset/4546/abcdef-abcd-abcd-abcd-abcdefabcd",
        "metadata_id": "urn:wmo:md:fr-meteo-france:gap123"
    },
    "links": [
        {
            "href": "https://example.org/data/nwp/92c557ef-d28e-4713-91af-2e2e7be6f8ab.grib",
            "rel": "canonical",
            "type": "application/grib"
        }
    ]
}
Example: minimal viable message compliant to the specification
{
    "id": "31e9d66a-cd83-4174-9429-b932f1abcdef",
    "conformsTo": [
        "http://wis.wmo.int/spec/wnm/1/conf/core"
    ],
    "type": "Feature",
    "geometry": null,
    "properties": {
        "pubtime": "2022-11-20T16:40:37Z",
        "datetime": "2022-11-11T11:11:11Z",
        "data_id": "data/data-123/items/abcdefab-abcd-1234-5678-0123456789ab",
        "metadata_id": "urn:wmo:md:test-nmhs-xyz:some_dataset",
        "cache": false
    },
    "links": [
        {
            "href": "https://example.org/92c557ef-d28e-4713-91af-2e2e7be6f8ab.txt",
            "rel": "canonical"
        }
    ]
}
Example: notification of the deletion of a data granule
{
    "id": "31e9d66a-cd83-4174-9429-b932f1abcdef",
    "conformsTo": [
        "http://wis.wmo.int/spec/wnm/1/conf/core"
    ],
    "type": "Feature",
    "geometry": null,
    "properties": {
        "pubtime": "2022-12-22T16:40:37Z",
        "datetime": "2022-11-11T11:11:11Z",
        "data_id": "data/data-123/items/abcdefab-abcd-1234-5678-0123456789ab",
        "metadata_id": "urn:wmo:md:test-nmhs-xyz:some_dataset",
        "cache": false
    },
    "links": [
        {
            "href": "https://example.org/92c557ef-d28e-4713-91af-2e2e7be6f8ab.txt",
            "rel": "deletion"
        }
    ]
}

Annex D: Bibliography

Annex E: Revision History

Date Release Editor Primary clauses modified Description

2022-12-05

Template

Tom Kralidis

all

update from TT-Protocols/ET-W2AT


1. https://community.wmo.int/governance/commission-membership/commission-observation-infrastructures-and-information-systems-infcom/commission-infrastructure-officers/infcom-management-group/standing-committee-information-management-and-technology-sc-imt
2. https://community.wmo.int/governance/commission-membership/infcom
3. https://ogcapi.ogc.org/features
4. https://datatracker.ietf.org/doc/html/rfc7946
5. https://www.w3.org/TR/dwbp
6. https://www.w3.org/TR/sdw-bp
7. https://en.wikipedia.org/wiki/FAIR_data
8. https://library.wmo.int/doc_num.php?explnum_id=11113#page=9
9. https://docs.opengeospatial.org/is/17-069r4/17-069r4.html
10. https://datatracker.ietf.org/doc/html/rfc7946
11. https://datatracker.ietf.org/doc/html/rfc8259
12. https://datatracker.ietf.org/doc/html/rfc3339
13. https://datatracker.ietf.org/doc/html/rfc4122
14. https://www.w3.org/TR/sdw-bp
15. https://www.w3.org/TR/dwbp
16. https://www.w3.org/TR/vocab-dcat
17. https://www.iana.org/assignments/link-relations/link-relations.xml
18. https://json-schema.org
19. https://github.com/wmo-im/wis2-topic-hierarchy
20. https://json-schema.org
21. https://en.wikipedia.org/wiki/YAML