Tightening the CAP Profile for Flood Hub Guidance

The first flood-hub-guidance-feed implementation proved that a non-CAP guidance source could be reconciled locally and published as generated CAP through multi-channel-relay.

The next useful question was more precise:

If this generated CAP is guidance for official alerting authorities, what should the CAP profile say, and what should it avoid saying?

That distinction matters. The service is still not an issuing authority for public warnings, and Google Flood Hub guidance is not being treated as an automatic public alert. The generated CAP is an authority-facing guidance product. The profile now says that more plainly.

What changed

The most visible changes are identity and wording.

Live guidance alerts now use:

sender: flood-hub-guidance@alert-hub.org
source: AI-assisted guidance on Google Flood Hub.
senderName: Alert-Hub.Org Guidance Based on Flood Hub

The headline now starts with:

Guidance for flood conditions in ...

where the final text is the emitted CAP areaDesc.

The description now includes a direct caveat:

This guidance product is intended to inform official alerting authorities, which remain responsible for determining whether and how to warn the public.

The instruction similarly points alerting authorities back to official situational awareness:

Alerting authorities should maintain awareness of relevant alerts or warnings, authoritative local sources, and emergency guidance from official sources with local situational awareness.

Those two sentences are not decoration. They are part of the product boundary. The generated CAP is useful only if downstream readers understand that it is guidance, not a replacement for official local decision-making.

A narrower CAP payload

The profile also removes several optional CAP elements from live guidance alerts.

Live generated guidance CAP no longer emits:

• top-level code
• info.effective
• info.onset
• info.parameter

The effective omission is deliberate. CAP already defines the effective time as the same as sent when effective is absent. For this product, duplicating that field did not add useful information.

The onset omission is also deliberate. The generated guidance is not a statement that a future emergency onset has been formally declared. It is a current guidance product derived from Flood Hub input.

Removing parameter is a tradeoff. Earlier generated CAP included build, warning, revision, fingerprint, polygon, and poll-run metadata inside CAP parameter elements. That was convenient for debugging, but it made the CAP payload carry internal operational details. The service still has traceability through logs, database rows, relay request records, and the local warning/revision model. The CAP itself is now cleaner.

The OASIS Event Terms eventCode remains:

OET: OET-194

That is different from the top-level CAP code element and remains appropriate for the flood event classification.

Audience and response type

The generated info block now says who this guidance is for:

audience: OfficialAuthorities
responseType: Assess

The hand-written CAP serializer already supported the CAP ordering needed here: audience is emitted after certainty and before eventCode.

This is a small detail, but it matters because profile work is often about being precise with ordinary-looking fields. A downstream validator or reviewer should see a product aimed at assessment by official authorities, not a public call to action.

Freshness is two hours from sent

The expiry policy also changed.

Previously, live guidance CAP used the upstream forecastPeriodHours when available, with a longer fallback. That made the CAP expiry follow the upstream forecast horizon. The new profile treats expiry as guidance freshness instead.

Live guidance CAP now sets:

expires = sent + 2 hours

That is intentionally shorter than many forecast windows. It says less about when flooding may occur and more about when this guidance product should be considered out of date.

The identifier change

The identifier was also changed to the directed OID-shaped form:

urn:oid:2.49.0.3.1.YYYY.MM.DD.HH.MM.MSS

The prefix anticipates use of the Alert-Hub.Org OID allocation. The timestamp is derived from the CAP sent time in UTC, with MSS as the three-digit millisecond component.

There is a known weakness here: timestamp-only identifiers can collide if multiple alerts are emitted in the same millisecond. That concern was recorded during review. The implementation follows the directive anyway, because the profile requirement was explicit.

Area text is still the hard part

The areaDesc field was cleaned so it describes the area rather than the product.

For example, the old shape could include wording such as:

Highly Likely flash flood guidance area for Kenya, Uganda

The new shape is area-only:

Kenya, Uganda

That is better, but it is not the end of the problem. The feedback correctly noted that areaDesc should ideally match the extent of the polygons or circles. The current implementation can use affected country names when available and can clean fallback place descriptions, but better polygon-to-place naming remains future work.

For now, the important improvement is that areaDesc is no longer carrying probability, hazard, or product wording. It is an area label.

Verification

The focused JVM test set passed after the changes:

./gradlew :guidance-feed:test \
  --tests org.floodhub.guidance.cap.FlashFloodCapAlertFactoryTest \
  --tests org.floodhub.guidance.cap.CapXmlSerializerTest \
  --tests org.floodhub.guidance.config.ApplicationConfigurationBindingTest \
  --tests org.floodhub.guidance.flashflood.FlashFloodRelayPublicationTest

Those tests cover the CAP object factory, serialized element ordering, the sent + 2h expiry rule, the OID-shaped identifier, omitted optional elements, and the actual CAP XML payload submitted to multi-channel-relay.

What remains

The main remaining work is area quality.

The service now avoids product wording in areaDesc, but better human-readable descriptions for irregular hazard polygons remain an open geospatial problem. Country names are a defensible fallback when they are all that is available, but they are often coarser than the actual guidance geometry.

That is an acceptable boundary for this slice. The generated CAP profile is now clearer about what it is: a short-lived guidance product for official alerting authorities, based on Flood Hub input, with a clean CAP payload and explicit caveats about responsibility for public warning decisions.