CAP origination annex: accessibility at the source

CAP origination annex: accessibility at the source (informative)

Part of the Three Senses Alerting Standard, draft 0.10.0. Informative annex: it binds no conformance requirement (R1 to R8 live in THE-STANDARD.md); it specifies how an alert ORIGINATOR carries accessibility inside a standard OASIS CAP 1.2 message so that any receiving device can render it, with no coordination beyond this page.

The reference origination implementation is the @ideafe/three-senses/compose module (the Three Senses Alert Composer core), developed under a Memorandum of Agreement with FEMA's IPAWS Program Management Office for the IPAWS-OPEN test environment.

1. Design rules

1. STANDARD CAP ONLY. Everything rides fields CAP 1.2 already defines: <resource> for media, <parameter> for metadata. A receiver that knows nothing about this annex sees a fully valid, fully ordinary CAP alert. Nothing replaces or alters the message text.
2. ROUND-TRIP UNTOUCHED. A gateway or redistributor that does not understand a parameter defined here MUST pass it through byte-intact, and one that re-serves CAP passes the ORIGINAL XML byte-intact (the IPAWS rule: a received message is never changed, manipulated, or filtered).
3. NEVER GUESS, NEVER REWRITE. A composer attaches an ASL resource only on an exact template match; a renderer applies a Three Senses parameter only when the value parses exactly. Broken or unknown values are ignored in favor of local inference: a wrong-hazard video or a wrong-family rhythm is worse than none. A relay never rewrites: it shows the authority's text unchanged, and the protective action in simple words comes from the authority's pre-approved template (see "Template identifier" below), never from a downstream simplification. Where no template exists, the relay shows the <instruction> verbatim (rule S3 of THE-STANDARD.md).
4. HONESTY IN THE LABEL. An FCC template video explains what an alert TYPE means in ASL. It is never presented as a translation of the specific message (47 CFR 10.500(e)(3) leaves agency, location, and time to the text channels). The resourceDesc written by the Composer says so in words.

2. ASL video as a CAP resource

One <resource> block per <info>:

<resource>
  <resourceDesc>American Sign Language video: what a Tornado Warning means
    (official FCC WEA template video; not a translation of this specific
    message)</resourceDesc>
  <mimeType>text/html</mimeType>
  <uri>https://www.youtube.com/watch?v=a59VLxN82uI</uri>
</resource>

• mimeType is text/html when the URI is a viewing page (the FCC publishes the official templates on its channel); a directly hosted file carries its real type (video/mp4) and, per CAP, a <size> when known. Assume aggressive size budgets: alerts are received in disasters, on bad networks.
• The normative source of template-to-video pairings is wea-asl-templates.json in this repository (Apache-2.0, compiled from FCC DA 25-12 Appendix C and the FCC's official ASL template page, with the mismatches between the two sets recorded honestly).

Template identifier

An authority that issues pre-approved templates identifies the template a message uses, so that a relay can select the matching signed clip and the matching simple-words action without interpreting free text. The identifier is the CAP <eventCode> of the <info> block (the three-letter SAME code, for United States WEA templates) or, where the authority publishes its own template list, an identifier the authority defines in a <parameter> of its own namespace. This annex defines no new element and no new valueName for it. A relay that finds no template, or an identifier it does not recognize, shows the <instruction> field verbatim and attaches no clip (design rule 3). A clip stored in advance on the receiver is played only when the <digest> of the alert's resource matches the stored copy; otherwise the receiver fetches the resource. The non-normative guide docs/signed-template-library.md describes how an authority builds such a library.

3. Three Senses metadata as CAP parameters

Two <parameter> blocks per <info>, namespaced so they can never collide:

<parameter><valueName>ideafe:threeSenses:family</valueName><value>STORM</value></parameter>
<parameter><valueName>ideafe:threeSenses:version</valueName><value>0.10.0</value></parameter>

• ideafe:threeSenses:family is one of the standard's family names (GROUND, WATER, STORM, FIRE, THREAT, TEST, OTHER, ALL_CLEAR), chosen by the originator under the section 4 crosswalk of THE-STANDARD.md. The family names a CATEGORY only; the protective action always travels in language (<instruction>, WEA text).
• ideafe:threeSenses:version is the standard draft the originator mapped against. A renderer that does not recognize the version treats the parameter as absent.
• Receiver rule (mirrors rule 3): prefer the sender-declared family over local inference only when the value is an exact family name; otherwise infer locally exactly as if the parameter were missing. Severity is NEVER carried here: CAP <severity> is already the channel for it, and duplicating it would invite contradiction.

4. WEA texts

The 90-character short and 360-character long WEA texts ride the IPAWS parameter convention:

<parameter><valueName>CMAMtext</valueName><value>...90 characters...</value></parameter>
<parameter><valueName>CMAMlongtext</valueName><value>...360 characters...</value></parameter>

SPANISH is not a different valueName: per IPAWS/NWS practice, Spanish WEA is a SECOND <info> block, identical to the first except <language>es-US</language> and the Spanish strings under the same plain CMAMtext/CMAMlongtext valueNames. The IPAWS profile requires <category> and <eventCode> to be identical across the info blocks, and the Composer renders both blocks from one template so they always are. Messages bound for EAS or HazCollect also carry the profile's required EAS-ORG parameter (the originator's SAME organization code), which the Composer takes as easOrg.

The Composer's precheck enforces, from the CAP 1.2 base spec: closed value lists on status/msgType/urgency/severity/certainty/category (runtime-validated, because JSON input has no type system), identifier and sender character restrictions, dateTime with a numeric timezone offset (never "Z", and UTC written -00:00), and references as sender,identifier,sent triples on every Update, Cancel, Ack, and Error. From the IPAWS profile: <code>IPAWSv1.0</code>, a required <expires>, and a required three-letter SAME <eventCode>. From IPAWS-OPEN operational limits and the FEMA agreement's software requirements (not the OASIS profile itself): polygons under 100 nodes, six-digit SAME geocodes, and the WEA length/character rules. The profile makes SAME geocodes a SHOULD rather than a MUST; the Composer accepts any geometry but originators are advised to include SAME geocodes, since some disseminators ignore purely geospatial areas. Where FEMA's IPAWS-OPEN Web-Service Interface Design Guidance states a stricter rule, the Guidance wins; this annex tracks it.

5. What this annex is not

It does not originate live public alerts (the Composer is test-environment software under its agreement); it does not replace the FCC's device-side template mechanism (47 CFR 10.480(f)); it does not define new CAP elements; and it does not make the ASL videos IDE's: they are United States government works, mapped here so they get used.

Source: CAP-PROFILE.md in the @ideafe/three-senses package, by International Deaf Emergency, licensed CC BY-ND 4.0.