Introduction and Rule Set 1.0

Introduction and Rule Set 1.0 PDF Version (680 KB)

Version Control

Purpose of this Document

This document defines a set of rules, recommendations, and managed list of values that are recommended for use of the Common Alerting Protocol (CAP) in Canada.

This profile is conformant with the Common Alerting Protocol, (the “Reference Standard” or CAP) in that valid CAP-CP is also valid CAP. As with the Reference Standard, compliance with the CAP-CP is not limited to any one alerting methodology, nor is it specific to any one alerting method, communications channel, or sub-group of public alerting stakeholders. In fact, significant effort has been made to ensure it does not include bias to any method, channel or sub-group of stakeholders.

This document is managed and versioned independently of the CAP-CP Location document and the CAP-CP Event References document so that it is not dependent on updates to either documents, and is not subject to update each time the others are updated. This approach limits the scope of CAP-CP updates to each of the rules, locations or event references, and supports more specialized focus of the participants to the change management process.

Copyright

This document is licenced under a Creative Commons License which stipulates how the document can be used and shared. Specifically, it has been licensed under the Creative Commons: Attribution Share-Alike 3.0 Unported license.

For reference, the following has been extracted from the Creative Commons online documentation:

This license allows you to share (copy, distribute and transmit the work) and to remix (to adapt the work to make commercial use of the work) under the following conditions:

Attribution: You must attribute the work in the manner specified by the author or licensor (but not in any way that suggests that they endorse you or your use of the work.

Share Alike: If you alter, transform, or build upon this work, you may distribute the resulting work only under the same or similar license to this one.

For more information, please visit: http://creativecommons.org/licenses/by-sa/3.0/

Notices

This document and the information contained herein is provided on an "AS IS" basis and the Authors, and their officers, employees or agents DISCLAIM ALL WARRANTIES OR REPRESENTATIONS, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY OR REPRESENTATION THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE RIGHTS OF OTHERS, OR ANY IMPLIED WARRANTIES OR REPRESENTATIONS OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Official versions are maintained at www.CAP-CP.ca.

Terms

• “CEMCS” refers to Canadian Emergency Management Communications Specifications governed by SOREM.
• “CEMCS CMP” refers to the Change Management Process established for managing Canadian Emergency Management Communications Specifications.
• “SC” refers to Common Alerting Protocol – Canadian Profile (CAP-CP) 1.0 Specification Committee as established under the CEMCS CMP and the CAP-CP 1.0 SC Terms of Reference.
• “SOREM” refers to Senior Officials Responsible for Emergency Management. It reports to the Federal/Provincial/ Territorial Deputy Ministers Responsible for Emergency Management.
• “Subject Event” refers to an “event”, real (i.e. Hurricane) or conceived (i.e. Terrorism) that the CAP Alert Message pertains too.
• “Layer” refers to a collection of additional information, supplemental to the usual information, found in a CAP message and attributed to one originating entity. A CAP-CP message may have several layers.
• “Profile” refers to a collection of rules applying additional constraints, supplemental to the usual constraints, on formatted information found in a CAP message and attributed to one originating entity. A CAP-CP message may have several profiles.

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 IETF RFC 2119, available at http://www.ietf.org/rfc/rfc2119.txt

CAP-CP Sub-Committee

The Specification Committee membership may include both voting and non-voting members. A Chair and Vice-Chair shall be selected from the committee's voting membership with a Secretary selected from either group.

Voting Representation

Organizations with voting oversight of this document included the following:

• Alberta Emergency Management Agency
• Canadian Public Safety Operations Organization (formerly known as the Canadian Association for Public Alerting and Notification)
• Centre for Security Science
• Environment Canada
• Industry Canada
• Natural Resources Canada
• Pelmorex Communications Inc.
• Public Safety Canada
• Sécurité Publique Québec
• NetAlerts Inc.

Non-Voting Representation

Organizations overseeing the process used to manage this document included the following:

• Canadian Radio-television and Telecommunications Commission
• Federal, Provincial, Territorial – Interoperability Working Group (FPT IWG), on behalf of the federal, provincial, territorial Senior Officials Responsible for Emergency Management (SOREM)
• Public Safety Canada – Interoperability Development Office
• Canadian General Standards Board (CGSB) in a consultative role

Acknowledgement

The Specifications Committee gratefully acknowledges the contributions of the following people in the preparation of this CAP-CP Location References document.

• Norm Paulsen (Committee Chair)
• Doug Allport
• Khalil Hayek
• Kirsten Wells
• Robert De La Durantaye
• Thomas Poirier-Blanchet
• Philip Dawe
• Wendy Wu
• Tim Trytten
• Jacob Westfall
• Yannick Asselin
• Jeff Conrad
• Noah Moser

Other CAP-CP Documents

The entire CAP-CP is defined by three documents, all of which can be found at www.CAP-CP.ca. The other two documents are titled as follows:

• CAP-CP Event References. This document identifies Canadian event references for use with CAP-CP. It is versioned independently of this document.
• CAP-CP Location References. This document identifies Canadian location references for use with CAP-CP. It is versioned independently of this document.

Additionally, the following Annex is supported:

• CAP-CP Location References Geocode Annex. This document lists the Canadian location references for use with CAP-CP. It is an appendix to the CAP-CP Location References document and contains additional supporting material.

CAP-CP Rules Overview

The CAP-CP rules primarily centers on four main requirements and constraints. They are as follows:

• Constraint of one subject event type per alert message
• Requirements associated with event identification
• Requirements associated with languages
• Requirements associated with location identification

Additionally, there are other rules and recommendations intended to help overcome implementation challenges that have been identified by the early adopters of the Reference Standard and the CAP-CP.

The specifics for all these points are detailed later in this document. What follows is a general discussion for each point.

Constraint of one subject event type per alert message

The Reference Standard allows for the inclusion of multiple subject events within a single CAP alert message, but specifies only one unique message identifier is required. Therefore, a situational change to any one of the subject events, triggering a new CAP update message, would give the appearance of a change to any and all of the other subject events within the update message. Further, given that event values will be used for the purpose of filtering, routing, validating, and other needs within the community; systems could have difficulty handling a single alert message containing multiple events when only a subset of events are of interest.

To avoid any potential confusion, the CAP-CP limits each CAP alert message to one single event type value.

Requirements associated with event identification

Further to 10.1, the Reference Standard simply requires that a human readable value describing the subject event for an alert message exists. It does not offer suggestions or a recognized list of events as that is a function of any alerting system that employs the Reference Standard.

However, since the CAP-CP includes rules on issues like languages, providing a coordinated Canadian event list within the CAP-CP, independent of any specific alerting system, will assist in consistency for Canadian users.

Given that Canadian alert messages may be translated by automated applications, a list of recognized pre-translated event types is provided. Further, the use of a master <eventCode> list supports the routing and filtering alert messages by event type.

The CAP-CP includes the requirement of an event code that must come from a comprehensive managed list of events. This list is found in the CAP-CP Event References document. As mentioned previously, this document is managed separately from the main body of the CAP-CP, as it is expected to change more frequently than the rules.

Requirements associated with languages

The Reference Standard identifies a language value as an optional element. In the absence of a value, US English is assumed in accordance with the Reference Standard. In Canada, where there are two official languages, use of the language value is very important for message distributors.

The CAP-CP requires the use of the language value. Further, it defines additional practices that address challenges associated with issuing and updating alerts in multiple languages.

Requirements associated with location identification

The Reference Standard supports the use of geo-referenced location codes to identify the alert area. Prior to this version of CAP-CP, CAP-CP required the inclusion of geo-referenced location codes as defined by the CAP-CP for this purpose. However, as noted in the last version, notice was given that deprecation of this requirement might be forthcoming.

Deprecating the required use of geo-referenced location codes in this specification does not preclude their requirement in other specifications within an alerting community. As an example, the use of geo-referenced location codes may be required for broadcaster distribution undertakings that are complying to an industry standard that uses equipment that expects geo-referenced location codes. Alternatively, systems such as the Multi-Agency Situational Awareness System (MASAS) are better suited to geospatial polygons, without a requirement for a geo-referenced location code.

With this version of the CAP-CP standard, the term “location reference” has been re-defined to mean any CAP conformant location reference; whether it is a geo-referenced code or a CAP conformant GIS construct. i.e. polygon or circle. Therefore, to be conformant with CAP-CP, a CAP conformant GIS construct must be present, and or a CAP-CP Location Reference value must be present.

The CAP-CP continues to include a managed list of standard geo-referenced location codes for systems that choose to employ them. This list is found in the CAP-CP Location References document. As mentioned previously, this document is managed separately from the main body of the CAP-CP, as it is expected to change more frequently than the rules.

CAP-CP Rules and Recommendations Introduction

The CAP-CP rules and recommendations are listed in the following sections. To help with the understanding and table formats used in the next sections, the following three explanatory sections are presented.

Table Layout Definitions

Element: a CAP-XML element as described in the Reference Standard
Use: a rule outlining the usage specifics of an element. As per the Reference Standard, one of “Required”, or “Optional” and as per CAP-CP one of “Required”, “Recommended” or “Optional”
Type: a categorization of the rule to one of “Technical” (format or structure) or “Policy” (the business of public alerting)
Value: allowable values for an element defined by a rule for the element
Description: a general description of a rule and its purpose
Notes: any special notes regarding implementation of a rule
Example: XML examples or snippets, which illustrate the use of a rule

CAP-CP <valueName> Scheme

The Reference Standard states that, “Values of ‘valueName' that are acronyms SHOULD be represented in all capital letters without periods”. The standard does not provide any further recommendations on creating a <valueName> or determining the domain of the code nor its format. In CAP-CP, the <valueName> should uniquely identify the value list being used, and if the value list is expected to change, should provide a method to accommodate changes by identifying each unique revision.

CAP-CP has adopted a URN-like scheme for creating valueNames. The following format will be used to create CAP-CP valueNames:

{type}:{identifier}:{specific string}

The character formatting for URNs from the IETF's RFC 2141 will be followed, including case in-sensitivity. <type> will be one of “profile” or “layer”. <identifier> is a unique string identifying this value list. This might be the agency who publishes the list or the type of list, and acronyms should follow the Reference Standard recommendations. <specific string> is further information about this value list such as a further identifying name, sub-segment, or version number. For example:

profile:CAP-CP:Location:1.0

Layer creators should ensure that their valueNames follow this format, do not conflict with established CAP-CP valueNames, and uniquely identify their organization.

Please note that the three CAP-CP documents are versioned independently, and that the versions used in the following examples are for reference only.

CAP Elements Mapping Table to CAP-CP

The following table identifies each of the CAP elements and any associated CAP-CP rules or recommendations that reference them:

CAP-CP Rules

This section identifies specific requirements and constraints associated with the CAP-CP rule set. CAP Reference Standard content is included for reference and comparison only. Differences in Reference Standard interpretations, unless specifically noted, are unintended and do not mean to override the Reference Standard.

Rule #1. CAP-CP message must be valid CAP

 CAP

Element: N/A

Use:

Type:

Value:

Description: The Reference Standard

Notes:

Example:

CAP-CP

Element: N/A

Use: Required

Type: Policy

Value:

Description: All alert messages must be structured and formatted according to the guidelines set out by the Reference Standard. Messages that do not conform to this standard are also considered invalid CAP-CP messages as well.

Notes: Systems receiving invalid CAP messages will not necessarily be expected to act on them; however, rather than aborting the process, it is recommended that the message be flagged with a “concern” or “error” system element and the originator notified of the reason for the flag. Recipients of a CAP message that may contain one of these elements should contact the originator for details.  

Example:

Rule #2. Constraint of one subject event per alert message

Element: N/A

Use:

Type:

Value:

Description:

Notes: CAP places no restrictions on the number of different subject event types per alert message

Example:

Element: N/A

Use: Required

Type: Policy

Value:

Description: To avoid any potential confusion, and consistent with other profiles of CAP, CAP-CP constrains each alert message to one subject event.

Notes:

• The Reference Standard allows for the inclusion of none, one, or many subject event types in a single alert message, but only one unique message <identifier>. An update to the information of any one of the events would appear as an update to the information of all the other event types, when that may not be the case.
• A practical method of validating this rule is to ensure that all <info> blocks in an alert message have the same <eventCode> values.

(1) (Acceptable)

<alert …>
…
<info>
  …
  <event>Thunderstorm</event>
  …
 <eventCode>
   <valueName>profile:CAP-CP:Event:1.0</valueName>
   <value>thunderstorm</value>
 </eventCode>
  …
  <area>
  <areaDesc>area 1</areaDesc>
  <geocode>…</geocode>
 </area>
</info>
<info>
…
  <event>Thunderstorm</event>
  …
  <eventCode>
   <valueName>profile:CAP-CP:Event:1.0</valueName>
   <value>thunderstorm</value>
 </eventCode>
…
 <area>
  <areaDesc>area 2</areaDesc>
  <geocode>…</geocode>
 </area>
</info>

(2) (Not Acceptable)

<alert …>
  …
<info>
  …
  <event>Thunderstorm</event>
  …
  <eventCode>
    <valueName>profile:CAP-CP:Event:1.0</valueName>
    <value>thunderstorm</value>
  </eventCode>
  …
<area>
  <areaDesc>area 1</areaDesc>
  <geocode>…</geocode>
</area>
</info>
<info>
  …
  <event>Tornado</event>
  …
  <eventCode>
    <valueName>profile:CAP-CP:Event:1.0</valueName>
    <value>tornado</value>
  </eventCode>
  …
<area>
  <areaDesc>area 2</areaDesc>
  <geocode>…</geocode>
</area>
</info>

Rule #3. The CAP-CP version for an alert message must be identified

Element: <code>

Use: Optional

Type: Technical

Value: User defined

Description: Any user-defined value, flag or special code used to identify the alert message for special handling.

Notes:

Example:

Element: <code>

Use: Required

Type: Technical

Value: profile:CAP-CP:1.0

Description: A value used to identify which version of the CAP-CP that the alert message is intended to be conformant with.

Notes:

1. <code> is a multi-use element. This “required” use, for noting the CAP-CP version, does not preclude the option of using <code> for other purposes, such as referencing an additional Profile, layer identification, system specific functions, etc.

Example:

(Multiple profile reference)
<alert>
  …
  <scope>Public</scope>
  <code>profile:CAP-CP:1.0</code>
  <code>IPAWS v1.0</code>
<note></note>
…

(Additional Layer reference)

<alert>
  …
  <scope>Public</scope>
  <code>profile:CAP-CP:1.0</code>
  <code>layer:EnvironmentCanada:1.0</code>
  <note></note>
  …

Rule #4. Alert messages intended for public distribution must include an <info> block

Element: <msgType>

Use: Required

Type: Policy

Value: “Alert”, “Update”, “Cancel”, “Ack”, “Error”

Description: A value denoting the state of the alert at the time of this message

Notes:

Example:

Element: <msgType>

Use: Required

Type: Policy

Value:

Description: Alert states, and the transition from one state to another, are implied with the use of the <msgType> and <references> elements.

1. For alert messages intended for public distribution, a <msgType> of “Alert”, “Update” or “Cancel” does affect the intended message to the public, and therefore an <info> block is required.
2. For alert messages with a <msgType> of “Ack” or “Error”, an info block is not required, as these messages are primarily intended for system level purposes and not for distribution to the public. 

Notes: Processing of “Ack” or “Error” messages is optional, and systems may impose their own associated rules.

Example:

(for public distribution)

<alert .. >
  …
  <status>Actual</status>
  <msgType>Alert</msgType>
  <source>Environment Canada</source>
  <scope>Public</scope>
  <code>profile:CAP-CP:1.0</code>
  <note />
  <references />
  <incidents />
  <info>
    ….
  </info>
</alert>

(not for public distribution)

<alert .. >
  …
  <status>Actual</status>
  <msgType>Error</msgType>
  <source>Environment Canada</source>
  <scope>Public</scope>
  <code>profile:CAP-CP :1.0</code>
  <note >Invalid eventCode</note>
  <references >test@ec.gc.ca,TEST-1,2009-01-01T12:00:00-00:00</references>
  <incidents />
</alert>

Rule #5. <info> blocks must specify the content language

Element: <language>

Use: Optional

Type: Policy

Value: Defined by RFC 3066

Description: The code denoting the language of the <info> blocks sub-elements within the alert message.

Notes: If not present or null, an implicit default value of "en-US" SHALL be assumed.

Example:

Element: <language>

Use: Required

Type: Technical

Value:

Description:

1. All messages with an <info> block must include the <language> element in order to denote the language of the content of the <info> block.
2. Multilingual messages must use separate <info> blocks for each language, with all non free-form text elements repeated verbatim in each block.
3. Mixing public display content or text from different languages within the same <info> block is not allowed, except for inherently multilingual content (people, places, things) that may or may not include accented characters.

Notes:

1. The corresponding RFC 3066 values for Canadian English and French are “en-CA” and “fr-CA”.  A message may support other languages spoken in Canada and the appropriate values should be used.
2. UTF-8 is the recommended encoding for XML documents in order to support a wide range of languages and accented characters.
3. Enumerated CAP element values, such as those defined for <urgency>, <severity>, <certainty>, <responseType>, etc. are in English only, and are always used as specified by CAP within all <info> blocks.

Content in the <info> block, such as <description>, <resource> (ex. audio files), external <web> links, etc. should serve the needs of the language value within the <info> block. 

Example:

(The values for <event> and <areaDesc> are translated across <info> blocks below as they are values for public display. Other public display elements not exampled below requiring translation include…<senderName>, <headline>, <description>, <instruction>, <web>, <contact>, <audience> )

<info>
  <language>en-CA</language>
  <category>Met</category>
  <event>Hurricane</event>
  <responseType>Monitor</responseType>
  <urgency>Expected</urgency>
  <severity>Severe</severity>
  <certainty>Likely</certainty>
  …
  <area>
    <areaDesc>Avalon Peninsula</areaDesc>
    …
  </area>
</info>

<info>
  <language>fr-CA</language>
  <category>Met</category>
  <event>Ouragan</event>
  <responseType>Monitor</responseType>
  <urgency>Expected</urgency>
  <severity>Severe</severity>
  <certainty>Likely</certainty>
  …
  <area>
    <areaDesc>péninsule d'Avalon</areaDesc>
    …
  </area>
</info>

Rule #6. A recognized <eventCode> must be used

Element: <eventCode>

Use: Optional

Type: Technical

Value: user-defined

Description: A system specific code identifying the event type of the alert message

Notes:

Example:

Element: <eventCode>

Use: Required

Type: Technical

Value: the <valueName>,<value> pair for the event code associated  with an event from the CAP-CP Event References document.

Description:

1. The CAP-CP requires the use of an <eventCode> value from the CAP-CP Event References document that should match the corresponding <event> value.
2. There is a limit of one <eventCode> value from the CAP-CP Event References list per alert message even though multiple occurrences of the element <eventCode> may appear in an alert message.
3. The event code format is 4 to 12 characters, is not case-sensitive, and has no spaces allowed.
4. The <valueName> version suffix will change as new versions of the Event References document are published.  As <eventCode> is a multi-use element, messages may be created that use codes from different versions of the Event References document in order to provide backward compatibility and to ease transition between list updates.

Notes: Additional event codes from other lists may be included for other purposes.

Example:

(The following example uses an <eventCode> from two Event References lists. The user is to identify the appropriate reference list from the <valueName> entry for their purposes.)

<info>
  …
  <event>Thunderstorm</event>
  …
  <eventCode>
    <valueName>profile:CAP-CP:Event:1.0</valueName>
    <value>thunderstorm</value>
  </eventCode>
  <eventCode>
    <valueName>SAME</valueName>
    <value>SVR</value>
  </eventCode>

  …
</info>

Rule #7. Location References are required

Element: <geocode> <polygon> <circle>

Use: Optional

Type: Technical

Value: user defined.

Description: A geographic reference to one or more locations where the information in CAP message is applicable.

Notes: In CAP, use of <polygon> and <circle> are recommended and preferred.

Example:

Element: <geocode> <polygon> <circle>

Use: Required

Type: Technical

Value: One or more of either the <geocode> <polygon> or <circle> elements must have a valid value where if only <geocode> is used, it must have a value that conforms to the CAP-CP Location References geocode set.

Description:

1. The Profile requires the use of at least one of either a <geocode> value from the CAP-CP Location References document; a <polygon> value; or a <circle> value.
2. Other <geocode> values from other code systems may optionally be used in addition to the above.
3. When using any of the location reference elements, as many as necessary to fully cover the alert message target area may be used. NOTE: higher level <geocode>s as defined in the CAP-CP Location References document are recommended to be used in place of several lower level <geocode>s where possible when using <geocode>s.
4. If using <geocode>, the respective <valueName> for the version of the CAP-CP Location References in which the <geocode> is extracted from must be included.

Notes:

1. Supplemental location codes from other lists such as a CLC or postal code may be added to a CAP-CP messages but are considered extraneous to the CAP-CP standard and there is no expectation that they will be used except by the parties that identify to them (Note: CLC is an Environment Canada Weather Radio location code).
2. Multiple <geocode>s from different versions of CAP-CP Location References may be included in one CAP-CP message.
3. The use of a <geocode> value from an earlier or later version of CAP-CP Location References than this CAP-CP Rules document is allowed for. e.g. A system might adopt CAP-CP Rules v1.0 and continue to use CAP-CP Location References Beta 0.4.

Example:

(In the first example, the first <geocode> uses an area Division while the second <geocode> uses an area Sub-Division all within the same <info> block. The location reference for the message is the union of the two referenced locations)

<info>
  …
  <area>
  …
  <geocode>
  <valueName>profile:CAP-CP:Location:1.0</valueName>
  <value>3506</value>
  </geocode>
  <geocode>
  <valueName>profile:CAP-CP:Location:1.0</valueName>
  <value>3507004</value>
  </geocode>
  …
  </area>
  …
  </info>

(The second example uses a <geocode> from two location reference lists. The recipient is to identify to the appropriate reference list from the <valueName> entry for their purposes.)

<info>
  …
  <area>
  …
  <geocode>
  <valueName>profile:CAP-CP:Location:1.0</valueName>
  <value>3506</value>
  </geocode>
  <geocode>
  <valueName>PostalCode:2011</valueName>
  <value>M4R2S8</value>
  </geocode>
  …
  </area>
  …
  </info>

(In the third example, the first <geocode> uses a value from a previous CAP-CP Location References list while the second <geocode> uses a value from a later CAP-CP Location References list)

The location referenced in the two versioned lists is essentially the same location, but a change in the definition of the location has occurred between these versions. The newer version better reflects the intended location reference. The older version allows for systems configured to the older version to remain functional.

<info>
  …
  <area>
  …
  <geocode>
    <valueName>profile:CAP-CP:Location:0.4</valueName>
    <value>2429065 /value>
  </geocode>
  <geocode>
    <valueName>profile:CAP-CP:Location:1.0</valueName>
    <value>29073 </value>
  </geocode>
  …
  </area>
  …
</info>

The CAP-CP Location Reference 2429065 in version 0.4 (part of Saint-Philibert) becomes Location Reference 2429073 in version 1.0 (part of Saint-Georges) due to the Quebec renovated land registry and changes to political boundaries of many municipalities.

(In the fourth example, only a <polygon> is used

<info>
  …
  <area>
  …
  <polygon>47.6325,-70.5033 47.4732,-70.2871 47.4425,-70.2483 47.3334,-70.3551 47.1601,-70.5438 47.0116,-70.7199 47.0684,-70.7868 47.1831,-71.016 47.1833,-71.0163 47.1835,-71.016 47.6324,-70.5035 47.6325,-70.5033</polygon> 
  …
  </area>
  …
  </info>

Rule #8. <area> blocks are required

Element: <area>

Use: Optional

Type: Technical

Value:

Description: Area sub-element container

Notes:

Example:

Element: <area>

Use: Required

Type: Technical

Value:

Description:
1 An <area> block is required for each <info> block.
2 <areaDesc> is a textual description of the area defined by the combination of area elements, and like <event>, may not necessarily be a name found associated with the Location References document.

Notes:
Area descriptions (like events) will need to be translated by the originator of the message for messages with both English and French <info> blocks in cases where the location name is not associated with the Location References document.

Example:

<info>
  …
  <area>
  <areaDesc>Shawinigan Area</areaDesc>
  <polygon>-73.2174,46.7498 -72.5497,46.7665 -72.5497,46.7665
  -72.4830,46.6498 -72.4830,46.6498 -72.4330,46.5832 -72.433,46.5832
  -72.8832,46.3998 -72.8832,46.3998 -72.8833,46.4000 -72.8833,46.4000
  -72.9666,46.5333 -73.1389,46.5201 -73.1389,46.5201 -73.1858,46.5139
  -73.1858,46.5139 -73.2174,46.7498 </polygon>
  <geocode>
    <valueName>profile:CAP-CP:Location:1.0</valueName>
    <value>2435040</value>
  </geocode>
  <geocode>
    <valueName>profile:CAP-CP:Location:1.0</valueName>
    <value>2435027</value>
  </geocode>
  …
  </area>
</info>

Rule #9. An Update or Cancel message should minimally include references to all active messages

Element: <references>

Use: Optional

Type: Technical

Value:

Description: An element that lists earlier message(s) referenced by the alert message.

Notes: The normative copy in CAP requires <references> for “Update” and “Cancel” values, however, it is not enforced in the schema.

Example:

Element: <references>

Use: Required

Type: Policy

Value:

Description:

1. Consistent with the normative copy of the Reference Standard, <references> are required with <msgType> values of “Update” or “Cancel”.
2. Further, CAP-CP requires references to all active messages (ones with at least one active <info> block) whose status is impacted by the new message. An “active” <info> block is one that has not yet reached its <expires> time.
3. In the case of an <info> block that does not have an <expires> time, all further messages in the chain should include a reference to that message since it does not expire on its own.

Notes: Referencing all alert messages with <info> blocks that still have an <expires> time in the future ensures that any messages that may still be playing incorrectly are properly superseded by the most recent Update or Cancel. This resolves issues caused by transmission delays and/or lost messages that may result in message chains being broken. If only a single reference were used, a missed message could result in an alert playing beyond its intended time.

Example:

(The first Alert message with a 3 hour expires time)

<alert … >
  <identifier>ABC-7</identifier>
  <sender>A@ca</sender>
  <sent>2008-01-01T01:00:00-00:00</sent>
  <status>Actual</status>
  <msgType>Alert</msgType>
  …
  <references></references>
  <info>
  …
  <expires>2008-01-01T04:00:00-00:00</expires>
  …
  </info>
  …
</alert>

(The subsequent “Update” with a 3 hour expires time referencing the first)

<alert … >
  <identifier>ABC-8</identifier>
  <sender>A@ca</sender>
  <sent>2008-01-01T02:00:00-00:00</sent>
  <status>Actual</status>
  <msgType>Update</msgType>
  …
  <references>A@ca,ABC-7,2008-01-01T01:00:00-00:00</references>
  <info>
  …
  <expires>2008-01-01T05:00:00-00:00</expires>
  …
  </info>
  …
</alert>

(Another subsequent Update with a 3 hours expires time referencing the first two)

<alert … >
  <identifier>ABC-9</identifier>
  <sender>A@ca</sender>
  <sent>2008-01-01T03:00:00-00:00</sent>
  <status>Actual</status>
  <msgType>Update</msgType>
  …
  <references>A@ca,ABC-7,2008-01-01T01:00:00-00:00 A@ca,ABC-8,2008-01-01T02:00:00-00:00</references>
  <info>
  …
  <expires>2008-01-01T06:00:00-00:00</expires>
  …
  </info>
  …
</alert>

(A further subsequent Update with a 3 hours expires time referencing the most recent two as the earliest one has expired and should not be playing anymore for two reasons…1) it has been superseded, or 2) it has expired)

<alert … >
  <identifier>ABC-10</identifier>
  <sender>A@ca</sender>
  <sent>2008-01-01T04:00:00-00:00</sent>
  <status>Actual</status>
  <msgType>Update</msgType>
  …
  <references>A@ca,ABC-8,2008-01-01T02:00:00-00:00 A@ca,ABC-9,2008-01-01T03:00:00-00:00</references>
  <info>
  …
  <expires>2008-01-01T07:00:00-00:00</expires>
  …
  </info>
  …
</alert>

Rule #10. Use established <event> values

Element: <event>

Use: Required

Type: Technical

Value: user-defined

Description: The text denoting the subject event of the alert message

Notes:

Example:

Element: <event>

Use: Required

Type: Policy

Value: an event from the CAP-CP Event References document

Description: It is recommended that the <event> value also come from the CAP-CP event list.  Using these pre-defined and pre-translated values helps ensure that all public alert messages are using common terminology to describe events.

Notes:

1. Authorities using <event> values other than those from the CAP-CP event reference list will need to map them to the Event References event code in order to be CAP-CP conformant. The CAP-CP <event> names therefore can still be derived using the event code value.
2. When creating public alerts using the <eventCode> “other”, a short and descriptive <event> value should be used. The originator would be expected to provide any necessary translations of these other events. The Tier I event names in the Event References document are helpful should this situation occur.
3. When creating public alert messages in languages other than English or French, a translation of the list to the appropriate language should be conducted in advance for inclusion in alerts.
4. The CAP-CP event list does not include leading articles as part of the full name of the event (i.e... the ‘d' and apostrophe in the reference… d'orages). However, articles contained within the name (not leading) are included as they will always be present in form of the display of <event>. Automated phrase construction using <event> needs to accommodate the leading article separately. 

Example:

<info>
  …
  <event>thunderstorm</event>
  …
  <eventCode>
    <valueName>profile:CAP-CP:Event:1.0</valueName>
    <value>thunderstorm</value>
  </eventCode>
  …
  </info>

Rule #11. Indicate when an update message contains non-substantive content changes

Element: <parameter>

Use:

Type:

Value:

Description: A system specific additional parameter associated with the alert message.

Notes: A <msgType> value of “Update” updates and supercedes the earlier message(s) identified in <references>.  Therefore the update message must reflect the entire state of the event and is by default always a substantive change.

Example:

Element: <parameter>

Use: Recommended

Type: Policy

Value: A <valueName> of “profile:CAP-CP:1.0:MinorChange” and a <value> of “none”, “text”, “correction”, “resource”, “layer”, or “other”.

Description:   The purpose of this parameter is to support advanced distribution decisions associated with reducing the number of cases of over alerting.

1. This parameter may only be used when the <msgType> is “Update” and the <references> element is correctly populated.
2. This parameter may only be used when all <info> blocks in a message contain non-substantive content changes or no change.   Adding or removing an <info> block relative to the previous message is a substantive change.
3. The addition, removal, or change of the following elements may be considered non-substantive:  <audience>, <headline>, <description>, <instruction>, <web>, <contact>, <parameter>, <areaDesc>, and <resource> blocks.  Both sending and receiving systems are free to impose additional constraints on what they consider to be non-substantive changes.
4. When an alert message is considered a minor update, all <info> blocks must contain a “MinorChange” parameter value(s) with an appropriate value setting reflecting the minor change. 
5. A <note> element may be used to further explain the reason for the minor changes in this update.
6. When no change has occurred in an <info> block relative to the previous message, the value of “none” should be used.
7. When a change has occurred between <info> blocks where some free form text content may have been added or modified, the value of “text” should be used in the <info> block(s) where applicable.
8. When a correction is made to some of the free form content, perhaps because of an error, spelling mistake or omission, the value of “correction” should be used in the <info> block(s) where applicable.
9. When the addition, modification, or removal of a <resource> block and its associated content takes place relative to the previous message, the value of “resource” should be used in the <info> block(s) where applicable.
10. When the addition, modification, or removal of layer based values takes place relative to the previous message, the value of “layer” should be used in the <info> block(s) where applicable.
11. When the content change doesn't meet the criteria of the other parameter values, the value of “other” should be used in the <info> block(s) where applicable.  A <note> element should always be used with “other” changes.
12. The values “none”, “text”, “correction”, “resource”, “layer”, and “other” are not case sensitive, and shall not be translated.

Notes:

1. Electing to process and the subsequent presentation of non-substantive content is left up to the sender or receiver.
2. If a receiver chooses to ignore this parameter and value, all update messages should be considered substantive as per the intent of the Reference Standard.
3. If a transmission error occurs and the receiver does not receive the referenced previous message to which the non-substantive change applies, the current message should be considered substantive.

Example:

(Initial Update)

<alert … >
  <identifier>CA-EC-CWTO-2008-13</identifier>
  …
  <references>cwto@ec.gc.ca,CA-EC-CWTO-2008-11,2008-07-16T16:00:00-00:00</references>
  …
  <info>
  …
  <language>en-CA</language>
  …
  <area>
  <areaDesc>Sainte-Anne-de-la-Perade</areaDesc>
  </area>      
  </info>
</alert>

(Subsequent Minor Update)

(The following message corrected the spelling of the name. In this case the original did not have an accent on the name segment Pérade so a minor update was initiated. No other elements from the referenced CAP message were altered so the original message, if it was left to continue playing as it was, would still be correct except for the spelling of the place name. Some distributors may choose not to resend the alert based on this change, opting to keep over-alerting cases to a minimum while others with passive display systems would likely act on this update).

<alert … >
  <identifier>CA-EC-CWTO-2008-14</identifier>
  …
  <references>cwto@ec.gc.ca,CA-EC-CWTO-2008-11,2008-07-16T16:00:00-00:00 cwto@ec.gc.ca,CA-EC-CWTO-2008-13,2008-07-16T16:00:00-00:00</references>
  …
  <info>
  …
  <language>en-CA</language>
  …
  <parameter>
    <valueName>profile:CAP-CP:1.0:MinorChange</valueName>
    <value>correction</value>
  </parameter>
  …
  <area>
    <areaDesc>Sainte-Anne-de-la-Pérade</areaDesc>
  </area>      
  </info>
</alert>

CAP-CP Recommendations

This section identifies specific recommendations associated with the CAP-CP.  CAP Reference Standard content is included for reference and comparison only. Differences in Reference Standard interpretations, unless specifically noted, are unintended and do not mean to override the Reference Standard.

Recommendation #1. Preferential treatment of <polygon> and <circle>

Element: <area>

Use: Optional

Type: Technical

Value:

Description:
(1) Multiple occurrences permitted, in which case the target area for the <info> block is the union of all the included <area> blocks.
(2) MAY contain one or multiple instances of <polygon>, <circle> and/or <geocode>. If multiple <polygon>, <circle> and/or <geocode> elements are included, the location described by this <area> element is the union of those represented by the included elements.

Notes: <geocode> values are correlated to pre-defined geospatial locations, as in the case with the Standard Geographical Classification (SGC) codes which formed the basis for the CAP-CP land based Location References.

Example:

Element:

Use: Optional

Type: Technical

Value:

Description:

CAP-CP requires either a CAP-CP <geocode> value, or the use of optional <polygon> and <circle> values. When either or both <polygon> and <circle> values are present in an area block, the combination of these <polygon> and <circle> values alone is considered a more accurate representation of the alert area than the CAP supported combination of all <polygon>, <circle> and <geocode> values together. This distinction allows for CAP originators to support alerting systems that require geocodes and still be able to more accurately represent the threat area with GIS constructs all in one CAP message. E.g. Use of a location code for an entire city, with a polygon representing an alert that is specific to just a few blocks.

Notes: The union of the area(s) associated with <geocodes> are often much larger than the actual alert threat area, resulting in over alerting. Recipients that intend to process a CAP-CP message may choose to identify the alert area by the <polygon> and <circle> elements alone knowing that this does not represent anything less than the full intended alert area.

Example:

<info>
  …
  <area>
  <areaDesc>Shawinigan Area</areaDesc>
  <polygon>-73.2174,46.7498 -72.5497,46.7665 -72.5497,46.7665
  -72.4830,46.6498 -72.4830,46.6498 -72.4330,46.5832 -72.433,46.5832
  -72.8832,46.3998 -72.8832,46.3998 -72.8833,46.4000 -72.8833,46.4000
  -72.9666,46.5333 -73.1389,46.5201 -73.1389,46.5201 -73.1858,46.5139
  -73.1858,46.5139 -73.2174,46.7498</polygon>
  <geocode>
    <valueName>profile:CAP-CP:Location:1.0</valueName>
    <value>2435040</value>
  </geocode>
  <geocode>
    <valueName>profile:CAP-CP:Location:1.0</valueName>
    <value>2435027</value>
  </geocode>
  …
  </area>
</info>

The <polygon> provided is a more accurate representation of the alert area than is the combination of boundary files associated with the <geocode> values included in the alert.

Recommendation #2. <sender> should be descriptive

Element: <sender>

Use: Required

Type: Technical

Value: user-defined

Description: Identifies the originator of the alert message

Notes:

Example:

Element: <sender>

Use: Required

Type: Policy

Value:

Description:

1. Must be human readable.
2. Must identify the agency that assembled the message, which may have been done on behalf of another agency that originated the message. Ex. When a municipality originates an alert that is published by a provincial agency, the <sender> is the provincial agency, and the <senderName> is the municipality.
3. Must be as unique as possible. Ex. An internet domain name as part of <sender> is one way to create uniqueness

Notes: If an alert message created by another agency is being passed through a system, such as an aggregator, with no alterations, then the <sender> can remain as is.  However, if any changes are made to the message, or if the aggregator is the authority to its clients, the <sender> value should change to reflect the aggregator.        

Example:

The Montreal office of an Issuing Authority received alerting information from another office in non-CAP format and subsequently reformatted the data into a CAP format and redistributed the message. In this case “Montreal” is a human readable and “@[domain]” settles uniqueness.
…
<sender> Montreal@gc.ca</sender>
…

Note: The example is not a real value.

The following is a two tiered example of a human readable name with a uniqueness quality. The “operations-center” of the “New Brunswick Emergency Measures Organization” as part of the “Government of New Brunswick”
…
<sender>operations-center@EMO@gnb.ca</sender>
…

Note: The example is not a real value.

Recommendation #3. A <senderName> is strongly recommended

Element: <senderName>

Use: Optional

Type: Technical

Value:

Description: The human-readable name of the agency or authority issuing the alert message <info> block.

Notes:

Example:

Element: <senderName>

Use: Recommended

Type: Policy

Value:

Description: It is strongly recommended that this element be populated by alert message originators as this value is expected to be used for public presentation purposes.

Notes: The appropriately translated value for the name should be used in each <info> block of a multilingual alert message.

Example:

<info>
  …
  <language>en-CA</language>
  <senderName>Environment Canada</senderName>
  ..
  </info>
  <info>
  ..
  <language>fr-CA</language>
  <senderName>Environnement Canada</senderName>
  ..
</info>

Recommendation #4. <responseType> is strongly recommended, when applicable

Element: <responseType>

Use: Optional

Type: Policy

Value:

Description: The code denoting the type of action recommended for the target audience.

Notes: Multiple instances MAY occur within a single <info> block.

Example:

Element: <responseType>

Use: Recommended

Type: Policy

Value:

Description: It is recommended that alert message issuers include response types when applicable, along with a corresponding <instruction> value.  Using <responseType> allows for automated dissemination in all included languages of the actions the end user is expected to take when instructions may not be available, or not available in all languages.

Notes:

Example:

<info>
  …
  <responseType>Shelter</responseType>
  <responseType>Monitor</responseType>
  <instruction>Take cover as threatening conditions approach and monitor local media broadcasts for further updates</instruction>
  …
</info>

Recommendation #5. Indicate automated translation of free form text

Element: <parameter>

Use:

Type:

Value:

Description: A system specific additional parameter associated with the alert message.

Notes:

Example:

Element: <parameter>

Use: Optional

Type: Policy

Value: a <valueName> of “profile:CAP-CP:1.0:AutoTranslated” and a <value> of  “yes” or “no”

Description:  Automated translation is any kind of machine based translation of free form text or the assembly of phrases based on pre-set values where a human translator has not been involved.  The purpose of this rule is to support advanced distribution decisions associated with multilingual messages.

1. When automated language translation of free form text content in an <info> block has taken place, a single instance of this parameter should be used with a value of “yes”.
2. For alert messages with multiple <info> blocks, only the <info> block(s) where this automated translation has taken place should use the parameter.
3. When issuing an update message for an <info> block that contains free form text content that has been subsequently reviewed by a human for correct translation, replacing automated translated content, this parameter should be used with a value of “no”.
4. The values “yes” and “no” are not case sensitive and shall not be translated. 

Notes:

1. Electing to process and the subsequent presentation of automatically translated content is left up to the receiver.
2. Considerations related to translation and multilingual requirements are numerous, and are to be addressed in supporting documents.
3. Issuers who intend to use automated translation should supply supporting documentation indicating which elements are/were auto translated.

Example:

(In the following alert, the instruction was auto generated in English by software interpreting a responseType rather than the free form sentence generated by a person in French. In situations where the first language text is not so simple as exampled, interpretations can be problematic. Therefore, a simple parameter element is used to flag the auto translation activity of the originator)

<alert … >
  …
<info>
  <language>en-CA</language>
  …
  <instruction>Take shelter as threatening or hazardous conditions arrive.
  </instruction>
  <parameter>
    <valueName>profile:CAP-CP:1.0:AutoTranslated</valueName>
    <value>Yes</value>
  </parameter>
  …
  </info>
  <info>
  <language>fr-CA</language>
  …
  <responseType>Shelter</responseType>
  <instruction>En menaçant des approches de temps, prenez l'abri à l'intérieur et surveillez la radio locale pour d'autres mises à jour
  </instruction>
  …
  </info>
  </alert>

In the above alert, it is obvious that the AutoTranslated parameter is referring to the instruction element. However, in many cases it may not be so obvious and with several elements in CAP that can contain text and one parameter to address them all, it will require a detailed explanation in the supporting documentation for this parameter to be useful to end of the line distributors.

Date modified:

2022-08-16