Practical exercise: Debug WIS2 metadata and publications

Learning outcomes

By the end of this exercise, you will be able to:

• validate WCMP2 discovery metadata and WIS2 Notification Messages (WNM);
• identify errors in geometry, required properties, links, security, and topic hierarchy;
• use MQTT Explorer and pywis-pubsub to inspect a publication;
• connect a validation error to a likely wis2box configuration or ingest problem.

Introduction

A WIS2 Node publishes two related but different things:

• Discovery metadata: a WCMP2 record describing a dataset. It is normally published as a notification on the node's metadata topic.
• Data notifications: WNM GeoJSON messages published on a WIS2 data topic. They point consumers to the data and carry observation time, publication time, and dataset identity.

In this exercise, the examples in this repository are your test cases. Some are valid controls; others contain one intentional defect. Your task is to find the defect, explain its operational impact, and propose the smallest correction.

Preparation

Install the validation tools, or use the versions already prepared in your training environment:

pip3 install pywis-pubsub pywcmp check-jsonschema
pywis-pubsub bundle sync
pywcmp bundle sync

If the WNM schema bundle is not available locally, use the copy in WNM-examples.

Open MQTT Explorer and connect to the test global broker (everyone:everyone@localhost:1884) and your wis2box broker (wis2box:<password from env>@localhost:1883). Subscribe to:

origin/a/wis2/#
cache/a/wis2/#
monitor/a/wis2/#

Do not publish test messages to an operational Global Broker.

Checkpoint: You can see at least one notification in MQTT Explorer, or the instructor has supplied a captured message for the remaining exercises.

Exercise 1: Validate WCMP2 discovery metadata

Validate the three records in WCMP2-examples:

pywcmp ets validate WCMP2-examples/ex1.json
pywcmp ets validate WCMP2-examples/ex2.json
pywcmp ets validate WCMP2-examples/ex3.json

Complete the table:

Inspect each record before deciding:

1. Is the record a WCMP2 core Feature?
2. Does the items link identify the MQTT channel where data notifications are published?
3. Does the channel agree with the centre ID and data policy?
4. Are custom values, such as the status object, backed by a meaningful vocabulary and accepted by the profile?

Checkpoint: Explain why a discovery record can be syntactically valid JSON but still be unusable for dataset discovery or publication.

Exercise 2: Find defects in WNM messages

Run both checks against every WNM example:

check-jsonschema \
  --schemafile WNM-examples/wis2-notification-message-bundled.json \
  WNM-examples/ex1.json

pywis-pubsub ets validate WNM-examples/ex1.json

Repeat for ex2.json through ex6.json and record the result:

Use these rules while investigating:

• Geometry coordinates are [longitude, latitude, elevation?], not [latitude, longitude] and not an object with lat and lon keys.
• Geometry may be null when a location is unavailable.
• Core WNM messages require pubtime, datetime, data_id, and metadata_id in the expected locations.
• metadata_id must point to the WCMP2 record describing the dataset.
• The relationship in a data link must be one accepted by the WNM profile.
• Security objects may contain only properties allowed by the applicable OpenAPI Security Scheme.

Do not treat every finding as the same kind of failure. Label each one as:

• schema failure;
• abstract-test failure;
• valid message with a likely operational or semantic problem;
• valid control message.

Exercise 3: Repair one message

Choose one failing WNM and copy it to a temporary file. Make one minimal correction. Keep the original unchanged.

For example:

Copy-Item WNM-examples\\ex3.json repaired.json

Edit repaired.json, then run both validators again. Record:

1. the original defect;
2. the field you changed;
3. why the correction is sufficient;
4. whether the corrected message now passes schema validation and ETS.

Compare your corrected message with another pair's result. A correction is incomplete if it only makes the JSON parser happy but leaves the WIS2 meaning wrong.

Exercise 4: Topic hierarchy investigation

Classify each topic as valid or invalid and explain why:

Then compare the topic with the links[].channel value in WCMP2-examples/ex1.json. Identify the mismatch that would prevent a consumer from following discovery metadata to the correct data stream.

Exercise 5: wis2box ingest triage

Use the wis2box logs or Grafana to reason through these reports:

1. Topic Hierarchy validation error: No plugins for ... in data mappings
2. Data already published for <data_id>; not publishing
3. A SYNOP file fails because station metadata is missing.

For each, state:

• what configuration or input is wrong;
• the first place you would inspect;
• the smallest corrective action.

Remember that duplicate suppression is normally intentional. A missing mapping and missing station metadata are different failures and need different fixes.

Exercise 6: Observe Global Broker monitoring feedback

Keep two MQTT Explorer windows open:

• Window A: connected to the wis2box broker on localhost:1883, with permission to publish;
• Window B: connected to the test Global Broker on localhost:1884, subscribed to monitor/a/wis2/# and origin/a/wis2/#.

Choose either a WNM or a WCMP2 example. Copy and paste the JSON into the MQTT Explorer publish dialog in Window A. Publish the same payload twice: once on a valid topic and once on an invalid topic.

Use these topics for the comparison:

Valid:   origin/a/wis2/<centre-id>/data/core/weather/surface-based-observations/synop
Invalid: origin/a/wis2/<centre-id>/data/core/weather/surface-based-observations/synop/station123/extra

If you chose a WCMP2 record, publish it on the corresponding metadata topic for the valid attempt and add an invalid extra level for the second attempt:

Valid:   origin/a/wis2/<centre-id>/metadata
Invalid: origin/a/wis2/<centre-id>/metadata/extra

Use the centre ID from the training setup and do not publish to an operational broker. Watch Window B for a monitoring message sent by the Global Broker on a topic such as:

monitor/a/wis2/<centre-id>

Hint: The test Global Broker used for this exercise is deliberately permissive and will publish most test messages so you can observe the monitoring response. In production, a Global Broker validates incoming messages and discards invalid publications instead of forwarding them.

Record for both attempts:

1. the publication topic;
2. whether a monitoring message arrived;
3. whether validation succeeded or failed;
4. the message or record identifier used to correlate the feedback;
5. any validation or KPI details returned by the Global Broker.

Checkpoint: Explain the difference between a message rejected because its payload is invalid and a message published on a topic that does not conform to the WIS2 Topic Hierarchy. If no monitoring message appears, check Window A's topic and permissions, Window B's monitor/a/wis2/# subscription, and the test Global Broker connection.

Debrief

Discuss with your partner:

1. Which defects were caught by JSON Schema, and which required an abstract test or human reasoning?
2. How can a valid WNM still describe data incorrectly?
3. Why must a test broker be used when deliberately publishing malformed messages?
4. Which validation would you add to a Node's publication pipeline before a message reaches MQTT?

Expected end state

You should have:

• a completed WCMP2 validation table;
• a completed WNM validation table;
• one repaired WNM that passes the checks you ran;
• a topic hierarchy classification with reasons;
• a triage response for three common wis2box ingest messages.

Reference material

• WIS2 Notification Message specification
• WIS2 Topic Hierarchy
• WIS2 Cookbook