Public warnings and notices profile

How public alerts and emergency warnings are described so they can be shared consistently across systems.

Schemas: 1

Code lists: 8

Standards: schema.org, Common Alerting Protocol (OASIS)

Alert alert link

A public warning or notice issued by a government: an emergency, an evacuation, a boil-water notice, a road closure. Modelled on the Common Alerting Protocol (OASIS CAP 1.2), the international standard behind IPAWS in the US, EU-Alert, and national warning systems worldwide. schema.org has SpecialAnnouncement, but every one of its properties is COVID-shaped - quarantineGuidelines, gettingTestedInfo, travelBans - and it carries no severity, urgency, certainty, or expiry, so it is used only as a discovery projection, never as the model. Alerts are outbound (government to public); service requests are inbound. The two are deliberately separate profiles.

Standards: Common Alerting Protocol (OASIS)

FieldTypeDefinitionRequired
@id string This alert's own dereferenceable identifier. Yes
@type "Alert" Always Alert. Yes
alertIdentifier string CAP identifier. Unique per sender. Yes
sender Reference The GovernmentOrganization issuing. Required: an unattributed warning cannot be trusted or verified. Yes
sent string CAP sent. Full date-time with offset. Yes
alertStatus string CAP status. 'exercise' and 'test' must never be rendered to the public as real; publishing them without this field is dangerous. Yes
messageType string CAP msgType. An update or cancel must carry 'references' so consumers can supersede the earlier message rather than showing both. Yes
scope string termCode from the AlertScope code list. Yes
references Reference[] Earlier alerts this supersedes, as resolvable references. Where the superseded alert is outside the published window, use referencesIdentifier instead. No
referencesIdentifier string[] CAP identifiers of superseded alerts that are not present in this dataset. Real alert feeds are windowed: an update commonly supersedes an alert that has already expired out of the active feed. Requiring a resolvable reference would force a publisher to downgrade the update to a plain alert, which turns 'this supersedes an earlier warning' into 'this is a new warning' - materially wrong for a warning system. An update or cancel must carry references OR referencesIdentifier. No
incident string CAP incidents: groups alerts about the same event. No
note string CAP note: free-text context that doesn't fit another field. No
alertInfo object[] CAP info blocks. One per language: CAP's alert/info split exists precisely so a warning can be issued in several languages at once, which matters wherever government operates multilingually. Yes
area object[] Where the alert applies. Geometry is referenced, never embedded: a warning polygon is thousands of coordinate pairs and inlining it makes the alert unusable on the constrained channels alerts actually travel over. No
resource object[] Supporting files: maps, audio, translations. No
sourceDataset string The Dataset this record was published as part of. No 
{
  "@id": "https://example-city.gov/id/alert/2025-water-011",
  "@type": "Alert",
  "alertIdentifier": "EXC-2025-WATER-011",
  "sender": {
    "@id": "https://example-city.gov/id/organization/public-works",
    "name": "Public Works Department"
  },
  "sent": "2025-08-14T06:12:00-07:00",
  "alertStatus": "actual",
  "messageType": "alert",
  "scope": "public",
  "incident": "EXC-2025-MAIN-BREAK-4TH",
  "alertInfo": [
    {
      "@type": "AlertInfo",
      "inLanguage": "en-US",
      "category": [
        "infra",
        "env"
      ],
      "event": "Boil water notice",
      "responseType": [
        "prepare",
        "monitor"
      ],
      "urgency": "immediate",
      "severity": "severe",
      "certainty": "observed",
      "headline": "Boil water notice for District 2 following main break",
      "description": "A 12-inch water main failed overnight on 4th Street. Water pressure loss may have allowed contamination to enter the distribution system in District 2.",
      "instruction": "Boil all water used for drinking, cooking, or brushing teeth for at least one minute before use. Continue until this notice is lifted.",
      "effective": "2025-08-14T06:12:00-07:00",
      "onset": "2025-08-14T02:40:00-07:00",
      "expires": "2025-08-17T12:00:00-07:00",
      "senderName": "Example City Public Works",
      "web": "https://example-city.gov/alerts/2025-water-011",
      "contact": "+1-555-0311"
    },
    {
      "@type": "AlertInfo",
      "inLanguage": "es-US",
      "category": [
        "infra",
        "env"
      ],
      "event": "Aviso de hervir el agua",
      "responseType": [
        "prepare",
        "monitor"
      ],
      "urgency": "immediate",
      "severity": "severe",
      "certainty": "observed",
      "headline": "Aviso de hervir el agua para el Distrito 2 tras rotura de tubería",
      "description": "Una tubería principal de agua de 12 pulgadas falló durante la noche en la calle 4.",
      "instruction": "Hierva toda el agua para beber, cocinar o cepillarse los dientes durante al menos un minuto antes de usarla.",
      "effective": "2025-08-14T06:12:00-07:00",
      "expires": "2025-08-17T12:00:00-07:00",
      "senderName": "Obras Públicas de Example City"
    }
  ],
  "area": [
    {
      "@type": "AlertArea",
      "areaDescription": "District 2, north of 4th Street",
      "jurisdiction": {
        "@id": "https://example-city.gov/id/jurisdiction/example-city/district-2",
        "name": "District 2"
      },
      "geometry": {
        "@type": "Geometry",
        "geometryType": "Polygon",
        "encodingFormat": "application/geo+json",
        "vertexCount": 5,
        "coordinates": [
          [
            [
              -118.245,
              34.056
            ],
            [
              -118.238,
              34.056
            ],
            [
              -118.238,
              34.05
            ],
            [
              -118.245,
              34.05
            ],
            [
              -118.245,
              34.056
            ]
          ]
        ]
      },
      "geocode": [
        {
          "@type": "PropertyValue",
          "propertyID": "gs:local",
          "value": "district-2"
        }
      ]
    }
  ]
}
Download JSON