Re: [emergency-adopt-docs] Re: [emergency] CAP Example Practices Notes A

Subject: Re: [emergency-adopt-docs] Re: [emergency] CAP Example Practices Notes Available for Comment Until May 20

At our June 25, 2013 EMA C&D SC meeting, we edited the Example Practices note to respond to the remaining issues raised by Jacob Westfall. These comments and our responses (in bold) are listed below. The latest draft of the note with these changes is attached.

Circles with radius 0. This document continues to sit on the fence and needs to be clear on whether this Practice is supported or not. They are allowed by CAP and have been a common method for denoting a “point” that has been used in practice for a number of years. Usually at the beginning phase of an emergency when the actual affected area may not be yet be determined but the location is at least known. If they are to be discouraged, then that argument should be persuasive and well developed.

We cleaned up the language to be more definitive and added an example:

"A zero-radius circle implies a geometric point. In general, the radius should be comparable in scale to the precision implied by the circle's center coordinates. For instance, given a center point latitude with three decimal places (about 100 meters), the radius ought to be .1 kilometer rather than zero.

Note that zero-radius circles may reflect an intentional policy decision. For example, a zero-radius circle may be the only option for earthquakes, which usually are defined by a point and, since they occur quickly, may not have a warning area. Similarly, a zero-radius circle may be appropriate at the beginning phase of an emergency when the actual affected area may not be yet be determined but the location is at least known."

Need further definition and an example of the practice in section F “means to extend a CAP message”. There are possible misinterpretations of what this is suggesting is possible.

We deleted the material related to extending a CAP message using the <resource> element.

Usage documentation. Parameter is not an acceptable location to provide links to documentation. Why is this even necessary in an actual message? Is there an expectation that every time someone opens this CAP message it will retrieve the usage documentation and display it as supplemental information alongside the CAP?

We deleted material related to adding link to usage docs in alert message parameters.

Expires section. Expires applies to the information and not the alert message. This should be made clear as its a common misunderstanding. The recommendations on how to generate a default expires time are all assuming that its “alert based” and not “information based” which is incorrect.

Changed heading and reworded and shortened to make this discussion relevant to the alert message information block:

3.3 Alert information expiration

"The <alert><info><expires> time is optional, and is defined in the CAP specification as "The expiry time of the information of the alert message." Determining the <expires> time of an alert information block during alert issuance can be challenging, yet having an <expires> time is extremely helpful for CAP feed clients and other downstream alert recipients. Unless an explicit <expires> time is specified, it will be up to the various disseminators, feeds and delivery systems to determine how long the alert information will remain visible to the public.

• One possibility is to set alert information expiration to a time slightly after the next expected update of the alert information. This helps avoids gaps for clients that poll more slowly.

o For example, if an agency issues measures flood gauges and issues updates every 30 minutes, the <expires> time can be 45 minutes or more after the <sent> time."

“Alert Expiration vs Alert Update”. This statement is contrary to both the specification and all best practices related to composing a message. I completely disagree with the Practice being advanced here.

We deleted section on using custom parameters to show event end.

On Sat, Jun 8, 2013 at 10:28 AM, Anthony Mancuso <amancuso@google.com> wrote:

Jacob,

I added your comments to the latest version of the "Example Practices -- CAP Elements" doc for discussion and comment by EMA Collateral & Documents Subcommittee members (at our next meeting on Thursday, June 1, at 9 AM Eastern). The doc is attached, and I added my responses inline below.

Tony

On Wed, May 29, 2013 at 6:23 AM, Jacob Westfall <jake@jpw.biz> wrote:

> I believe I addressed all your comments in prior versions. Can you point to
> anything that was not addressed?

The following comments sent Apr 2.

My comments on the latest Elements draft,

- Why is there a reference made to CAP 1.0 and 1.1 in the opening of the document?

-- Done (deleted these references).

- Circles with radius 0. This document continues to sit on the fence and needs to be clear on whether this Practice is supported or not. They are allowed by CAP and have been a common method for denoting a “point” that has been used in practice for a number of years. Usually at the beginning phase of an emergency when the actual affected area may not be yet be determined but the location is at least known. If they are to be discouraged, then that argument should be persuasive and well developed.

--- The two paragraphs in the current doc regarding 0-radius circles say that use of a 0 radius circle is fine if a point is intended.

- Need further definition and an example of the practice in section F “means to extend a CAP message”. There are possible misinterpretations of what this is suggesting is possible.

--- Current Section 2.5 gives examples (such as images or audio files) of the type of resource data that can be used to extend a cap message.

- Usage documentation. Parameter is not an acceptable location to provide links to documentation. Why is this even necessary in an actual message? Is there an expectation that every time someone opens this CAP message it will retrieve the usage documentation and display it as supplemental information alongside the CAP?

-- Changed the " should be provided in a <parameter>" to "can be provided ..." to make it clearer that this is an option that may make sense in some applications.

- Expires section. Expires applies to the information and not the alert message. This should be made clear as its a common misunderstanding. The recommendations on how to generate a default expires time are all assuming that its “alert based” and not “information based” which is incorrect.

-- What is the difference between saying the information in the alert expires and saying the alert expires (since the alert contains the information)? It is not conflating the event with the alert, which I believe is the main source of confusion to be avoided. This section is making the important point that an expires time (for the alert/alert information) is helpful so that alert distributors will know how long to keep the alert active.

- “Alert Expiration vs Alert Update”. This statement is contrary to both the specification and all best practices related to composing a message. I completely disagree with the Practice being advanced here.

-- Again, this is saying that the expires time is the time the alert information expires. This section makes the point that it can be used to set the time for the next update (to replace the information in the expired alert with new information in the update). And it makes the related point that a parameter can be used to express the expires time of the actual event (if known)

- Get rid of the Element Examples section. There should be an example provided for each Practice in the sections above.

-- Done.

--
Jacob Westfall <jake@jpw.biz>

---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail. Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php

emergency-adopt-docs message