This section describes Google-specific differences with the CAP 1.2 XML format. The Google CAP schema is available for download from GitHub.
Overview
Alert message data must be provided in CAP 1.2 XML format. (CAP 1.1 XML format also is accepted.)
Google Public Alerts requires some elements that are optional in the OASIS spec,
such as <expires>
, <description>
, and <area>
. These elements
allow Google to process and display your alerts effectively. For example,
specifying <area>
helps us target your alert to the users most likely to
find it relevant based on their location.
The tables below list the standard CAP 1.2 message elements as modified by the additional Google Public Alert requirements. These elements, including the Google modifications, comprise the data dictionary for CAP-Google. They have been implemented in the Google CAP validator as Google Public Alerts CAP v1.0.
Terminology
- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
- Where an element's optionality has changed from the OASIS CAP 1.2 specification, the new value is bold and highlighted in RED.
About the requirements tables
The "Optionality" columns in the tables below classify each element as one of the following:
- REQUIRED: Your feed is considered invalid if it doesn't include a properly-formatted value for this tag
- CONDITIONAL: Optional, but conditioned on the value of another tag
- OPTIONAL: These tags are supported to allow you to tailor results based on your application
Google CAP also specifies additional requirements about the format and content of field values. The "notes and requirements" columns provide details and reasons for these.
<alert>
element and sub-elements
Element Name | Optionality | CAP-Google notes and requirements | |||
---|---|---|---|---|---|
<alert> |
REQUIRED | ||||
<identifier> |
REQUIRED | ||||
<sender> |
REQUIRED | ||||
<sent> |
REQUIRED | If the location cited in the <area> block falls within a single timezone, <effective> SHOULD specify time in that zone, including allowance for Daylight Savings when applicable. When the content of a message applies across multiple timezones, the message producer SHOULD use UTC times in preference to local times.
|
|||
<status> |
REQUIRED | Require the use of "test" as <status> for all test messages. Sending test messages "actual" is considered extremely bad form and will lead Google to suspend a publisher. |
|||
<msgType> |
REQUIRED | <msgType> UPDATE or CANCEL must include at least one <references> element. As specified in the CAP standard, any alert message that is updating a previous alert should use <msgType> Update</msgType> and set <references> to all previous messages that haven't reached their <expires> date. The UPDATE or CANCEL must apply to a non-expired alert, and hence all related messages and unexpired alerts must be referenced when an UPDATE or CANCEL is issued. |
|||
<source> |
OPTIONAL | ||||
<scope> |
REQUIRED | ||||
<restriction> |
CONDITIONAL | ||||
<addresses> |
CONDITIONAL | ||||
<code> |
OPTIONAL | ||||
<note> |
OPTIONAL | ||||
<references> |
OPTIONAL | Required if <msgType> is "Update" or "Cancel".
Where your system republishes CAP content from another publisher, you should include alert CAP in full, but if it's been edited use the <references> tag to link to the original source. |
|||
<incidents> |
OPTIONAL |
<info>
element and sub-elements
Element Name | Optionality | CAP-Google notes and requirements |
---|---|---|
<info> |
REQUIRED | At least one <info> must be present all <info> blocks must have the same <category> and <eventCode> values. |
<language> |
OPTIONAL | All <info> blocks with the same <language> must have the same values for <event> |
<category> |
REQUIRED | |
<event> |
REQUIRED | length: < 35 characters
Google Public Alerts requires CAP that supports a finite and pre-defined set of The set of event types should be defined in a CSV or Google Spreadsheet document (sample here). We want these to be short (< 35 char) and descriptive enough for the public to understand; we use the event string (or sometimes the This should go either in the |
<responseType> |
OPTIONAL | <responseType> is strongly recommended, when applicable, along with a corresponding <instruction> value. |
<urgency> |
REQUIRED | Do not use "unknown" as this makes indexing alerts and relative rankings difficult. It's important for Google to know how this field is set and by whom, though this is outside the scope of the formal profile. While preferably this value is set by the publisher on a case-by-case basis following clear triggering guidelines, they might be fixed by <event> , though this reduces the flexibility of alert authors. As an example, NOAA in the USA sets urgency statically based on event type. |
<severity> |
REQUIRED | Do not use "unknown" as this makes indexing alerts and relative rankings difficult. It's important for Google to know how this field is set and by whom, though this is outside the scope of the formal profile. While preferably this value is set by the publisher on a case-by-case basis following clear triggering guidelines, they might be fixed by <event> , though this reduces the flexibility of alert authors. As an example, NOAA in the USA sets urgency statically based on event type. |
<certainty> |
REQUIRED | Do not use "unknown" as this makes indexing alerts and relative rankings difficult. It's important for Google to know how this field is set and by whom, though this is outside the scope of the formal profile. While preferably this value is set by the publisher on a case-by-case basis following clear triggering guidelines, they might be fixed by <event> , though this reduces the flexibility of alert authors. As an example, NOAA in the USA sets urgency statically based on event type. |
<audience> |
OPTIONAL | |
<eventCode> |
OPTIONAL | |
<effective> |
OPTIONAL | Time zone fields must be included in all date/time values. If the location cited in the <area> block falls within a single timezone, <effective> SHOULD specify time in that zone, including allowance for Daylight Savings when applicable. When the content of a message applies across multiple timezones, the message producer SHOULD use UTC times in preference to local times. |
<onset> |
OPTIONAL | Time zone fields must be included in all date/time values. If the location cited in the <area> block falls within a single timezone, <effective> SHOULD specify time in that zone, including allowance for Daylight Savings when applicable. When the content of a message applies across multiple timezones, the message producer SHOULD use UTC times in preference to local times. |
<expires> |
REQUIRED | <expires> must come after <effective> in time order. Time zone fields must be included in all date/time values. If the location cited in the <area> block falls within a single timezone, <effective> SHOULD specify time in that zone, including allowance for Daylight Savings when applicable. When the content of a message applies across multiple timezones, the message producer SHOULD use UTC times in preference to local times. |
<senderName> |
OPTIONAL | This is strongly recommended. Having the human readable name for the sender enables the <web> link to be shown in a user-friendly way as per the publisher/sender's preferences. In addition, this allows alert aggregators to acts to publish from multiple authorities. |
<headline> |
OPTIONAL | length: < 140 characters
The headline string can be free text, but should be < 140 characters. (CAP 1.2 suggests < 160 for text messages). The start of this string should be a few descriptive words that explain the core of the alert (for example, "Pontoon bridge closure...."). The |
<description> |
REQUIRED | The value of this element must not be the same as the <instruction> element. Google uses <description> to populate the "Message" section of our page and <instruction> to populate the "Recommended actions" section. Thus, even though some publishers make them identical, they serve different purposes in CAP and on the Google alerts pages. |
<instruction> |
OPTIONAL | Optional though strongly recommended. Google Public Alerts uses this field in alert details pages as the "recommended action".
The<instruction> and <description> fields should be different, as they serve different purposes. Though some publishers simply copy one to the other, this makes for a poor user experience |
<web> |
REQUIRED | This should link to a copy of the original alert accessible on your web server. Note: Google validates against this. |
<contact> |
OPTIONAL | This contact field is optional but we strongly recommend it be present as it provides a way for users to provide feedback and respond to the alert. For example, "For emergencies call 911". |
<parameter> |
OPTIONAL |
<resource>
element and sub-elements
Element Name | Optionality | CAP-Google notes and requirements |
---|---|---|
<resource> |
OPTIONAL | Let us know when discussing your content with Google what kinds of resources may be linked to the message. For example, related web sites, .wav files, or images. |
<resourceDesc> |
REQUIRED | |
<mimeType> |
REQUIRED | |
<size> |
OPTIONAL | |
<uri> |
OPTIONAL | |
<derefUri> |
CONDITIONAL | |
<digest> |
OPTIONAL |
<area>
element and sub-elements
Element Name | Optionality | CAP-Google notes and requirements |
---|---|---|
<area> |
REQUIRED | <area> blocks must have at least one <circle> , <polygon> , or <geocode> . Google strongly prefers <circle> or <polygon> . |
<areaDesc> |
REQUIRED | <areaDesc> element may be used by Google to generate the location text string used in the alert title/headline. |
<polygon> |
OPTIONAL | Polygons must meet the following requirements:
|
<circle> |
OPTIONAL | |
<geocode> |
OPTIONAL | Values for <geocode> should be associated with a free and open dataset of polygons. As an example, in the USA, this includes the following:
<area> <geocodes> elements. Notices of updates to this list should be posted via a separate channel, preferably as RSS or email alerts. |
<altitude> |
OPTIONAL | |
<ceiling> |
CONDITIONAL |
Additional field requirements
Date/time fields
Date/Time fields MUST include the time zone. This applies to <sent>
, <effective>
, <onset>
, and <expires>
:
- If the location cited in the
<area>
block falls within a single timezone,<effective>
SHOULD specify time in that zone, including allowance for Daylight Savings when applicable. - When the content of a message applies across multiple timezones, the message producer SHOULD use UTC times in preference to local times.
Event changes or expiration
Event changes or expiration SHOULD be handled in the following way:
<msgType>
UPDATE or CANCEL must include at least one<references>
element.- There are three ways to CANCEL events, in order of preference:
- Set an
<expires>
datetime for each event, with the message description setting the expectation that this alert will end on its own. - Issue a new
<alert>
with<msgType>
UPDATE,<responseType>
"All Clear", and<expires>
a short time in the future. - Issue a new
<alert>
with<msgType>
CANCEL.
- Set an
Refer to Sample updates and cancellations for examples.