.Sf "$Date: 2012/11/14 07:48:49 $" "$RCSfile: cap-structure.ms,v $" "$Revision: 1.32 $"
.NH 1
Introduction
.LP
The Common Alerting Protocol (CAP)\** is a versatile standard to
disseminate alerting messages in XML.
World Meteorological Organization (WMO) has adopted
CAP as a format for alerting information
in the WMO Information System (WIS).
.FS
The Common Alerting Protocol is developed as OASIS Standard,
and the latest version is 1.2
.B "http://docs.oasis-open.org/emergency/cap/v1.2/CAP-v1.2.html" .
The previous version 1.1 was also approved as
ITU-T Recommendation X. 1303 (09/2007).
.FE
The RSMC (Regional Specialized Meteorological Centre) Tokyo-Typhoon
started to create experimental CAP version of its tropical cyclone advisory
(hereafter TC advisory),
currently sent as plain text bulletins WTPQ20-25 RJTD on the GTS.
.LP
The CAP standard is so flexible.
In other words, it is necessary to create `profile',
i.e. set of various kinds of use-specific
conventions on details and optional elements.
This document gives a profile to CAP
(hereafter called CAP-RSMCTK)
used in the RSMC Tokyo's CAP version of TC advisory,
in addition to related operational information to use the data flow.
.LP
Please note that this specification is really experimental state.
Any comments and thoughts are welcomed
to refine it to be best understood in the Typhoon operation community
and best utilized in emerging public weather service activities.
.QP
.B Disclaimer :
This experimental CAP Atom feed (URL shown in Section \*[ref atom])
is provided for convenience of development of CAP profile
among Typhoon Committee members,
and is not intended for operational use.
Japan Meteorological Agency (JMA) does not guarantee its availability.
That means it may not be able to respond to queries in timely manner.
For operational use, please continue to use GTS bulletins WTPQ20-25.
.NH 1
Working Cycle of TC advisory
.KF
.LP
.PS
scale = 24
Origin:
circle rad 1 invis
down
Raxis: arrow 31 from Origin + (0, 0.5)
"analysis" "time" at Raxis.center + (-7, 0)
for v = 12 to 96 by 12 do {
right
move v from Origin
down
line 30 dashed
}
"Mon" at Origin + (0, 6)
"00Z" at Origin + (0, 2)
"12Z" at Origin + (12, 2)
"Tue" at Origin + (24, 6)
"00Z" at Origin + (24, 2)
"12Z" at Origin + (36, 2)
"Wed" at Origin + (48, 6)
"00Z" at Origin + (48, 2)
"12Z" at Origin + (60, 2)
"Thu" at Origin + (72, 6)
"00Z" at Origin + (72, 2)
"12Z" at Origin + (84, 2)
"Fri" at Origin + (96, 6)
"00Z" at Origin + (96, 2)
move to Origin
left
move 1
right
Vaxis: arrow 101
"valid time" at Vaxis.center + (0, 10)
for b = 0 to 24 by 6 do {
down
move b from Origin + (0, -3)
right
move b
Maptime: \
box wid 2 height 2 fill 0 at Here
move 1 from Maptime
line 71 thickness 1
move 24 from Maptime
circle rad 1 fill 0 at Here
move 48 from Maptime
circle rad 1 fill 0 at Here
move 72 from Maptime
circle rad 1 fill 0 at Here
}
for b = 3 to 21 by 6 do {
down
move b from Origin + (0, -3)
right
move b
Analysis: \
box wid 2 height 2 fill 0 at Here
move 1 from Analysis
line 68 thickness 1
move 24 from Analysis
circle rad 1 fill 0 at Here
move 45 from Analysis
circle rad 1 fill 1 at Here
move 69 from Analysis
circle rad 1 fill 1 at Here
}
.PE
.QP
.SM
Figure 1: illustration of update cycle of TC advisory.
Open (white) square indicates analysis.
Open (white) circle indicates forecast (24, 48, or 72 hours).
Filled (black) circle indicates information duplicated from previous issue
(forecast of 45 or 69 hours).
The squares/circles connected by a horizontal thick line represent
a bulletin disseminated every three hours.
In CAP version each circle is given as a single \*[cap info] block.
.NL
.sp 2
.KE
.
.LP
When RSMC Tokyo recognizes a relevant tropical cyclone,
it issues several types of products.
Please refer to TCP-23\** for complete listing.
.FS
TCP-23: The Typhoon Committee Operational Manual, Meteorological Component.
Available at
.B "http://www.wmo.int/pages/prog/www/tcp/operational-plans.html" .
.FE
The TC advisory (WTPQ20-25 RJTD),
for which the experimental CAP version is provided,
is one of such products.
.LP
The TC advisory consists of analysis and forecast.
All information has two time properties:
analysis time (the time of observation the advisory is based upon)
and valid time (the time about which the forecast is describing).
Please don't be confused when handling updates:
Figure 1 illustrates the relationship between analysis time and valid time.
.LP
Analysis is observation-based description of state of cyclone,
updated every three hours.
Forecast is made for 24, 48, and 72 hours after analysis\**.
.FS
This difference (valid time minus analysis time) is called forecast time.
.FE
The 24-hour forecast is updated every three hours.
But forecasts for longer time (i.e. 48 and 72 hours)
are updated only on six-hours interval (on 00, 06, 12, 18 UTC).
On intermediate hours (i.e. 03, 09, 15, 21 UTC)
the same content as previous bulletin is given as 45 and 69 hours forecast.
.
.NH 1
Data Structure
.LP
.\"
.\" === Begin Figure 2 ===
.\"
.KF
.sp 2
.QP
.B1
.nf
<\fBfeed\fP xmlns="\fBhttp://www.w3.org/2005/Atom\fP">
2012-10-29T07:44:20Z
... \fImetadata of the feed\fP ...
RSMC Tokyo - Typhoon Centre
<\fBentry\fP>
2012-10-29T06:40:57.001Z
... \fICAP headline\fP ...
... \fICAP description\fP ...
urn:uuid:4684c9e6-1fad-3a83-b797-43b40c62a6de
<\fBcontent\fP type="application/cap+xml">
<\fBcap:alert\fP xmlns:cap="\fBurn:oasis:names:tc:emergency:cap:1.2\fP">
urn:uuid:4684c9e6-1fad-3a83-b797-43b40c62a6de
... \fICAP message \fP ...
... \fIsubsequent entries (if any)\fP ...
.fi
.B2
.QP
.SM
Figure 2: structure of CAP-embedded Atom Feed used by RSMC Tokyo-Typhoon Centre.
.NL
.sp 2
.KE
.\"
.\" === End Figure 2 ===
.\"
.NH 2
Structure of Atom feed
.LB atom
.LP
At the time of writing\**,
the experimental
CAP messages uses Atom as a feed format.
Recipient centres can retrieve updates
by polling (periodically accessing) the feed at
.B "http://www.data.jma.go.jp/fcd/yoho/cap-rsmctk/atom.xml" .
Ten-minute interval is suggested for timely retrieval,
since the feed is updated on twenty-minute cycle.
.FS
CAP is just a format of XML,
and can be used with other transfer protocols or networks.
Currently RSMC Tokyo is using Atom feed on Internet
considering its experimental nature,
especially ease of development work and communication with
various interested parties.
.FE
.LP
The file `atom.xml' is in the Atom Syndication Format\** containing
recently-updated messages (Figure 2).
.FS
M. Nottingham, Ed. and R. Sayre, Ed., 2005:
The Atom Syndication Format. RFC 4287.
.B "http://tools.ietf.org/html/rfc4287" .
.FE
A
.B feed > <
contains variable number of
.B entry > <
elements.
Each
.B entry > <
contains a single CAP message (the \*[cap alert] element in
.B content > <
element),
to be described in following section.
.LP
Since the CAP messages are embedded in the Atom feed,
all information you need is retrieved at once by single HTTP GET request.
There is no need to retrieve individual CAP messages separately.
Thus the identifier of each entry or CAP message is UUID\**
(32 hexadecimal digits beginning with
.B urn:uuid: )
rather than HTTP URL.
.FS
P. Leach
.I "et al" .,
2005:
A Universally Unique IDentifier (UUID) URN Namespace. RFC 4122.
.B "http://tools.ietf.org/html/rfc4122" .
.FE
.LP
Frequent polling causes repeated downloading of the same data.
If the bandwidth matters, it is suggested to use
.B If-Modified-Since: ' `
request header of HTTP\** to suppress unnecessary data transfer.
.FS
R. Fielding
.I "et al" .,
1999:
Hypertext Transfer Protocol -- HTTP/1.1. RFC 2616.
Section 14.25
.B "http://tools.ietf.org/html/rfc2616#section-14.25"
describes the If-Modified-Since function.
.FE
.LP
For convenience, the Atom elements
.B title > <
and
.B summary > <
contain the minimum information of the CAP messages.
Thus generic software that only understands the Atom structure
(such as web browsers) can display the summary of the TC advisory.
.\"
.\" === Begin Figure 3 ===
.\"
.KF
.QP
.PS
scale = 1
right;
box dashed "Atom feed";
arrow dashed "1..*" above;
BC: [ { down;
box ht .2 wid 1 "alert";
box ht 1.3 wid 1 \
"identifier" "sender" "sent" "status" "scope" "code" \
"\fIinfo\fP";
} ]
move 0.7;
BI: [ { down;
box ht .2 wid 1 "info";
box ht 2.7 wid 1 \
"language" "category" "event" "urgency" "severity" "certainty" \
"\fIeventCode\fP" \
"effective" "onset" "expires" "senderName" \
"headline" "description" "web" \
"\fIparameter\fP" "\fIarea\fP" ;
} ]
move;
BP: [ { down;
box ht .2 wid 1 "parameter";
box ht .4 wid 1 \
"valueName" "value" ;
} ]
up;
move 0.2 from BP.n;
BE: [ { down;
box ht .2 wid 1 "eventCode";
box ht .4 wid 1 \
"valueName" "value" ;
} ]
down;
move 0.2 from BP.s;
BA: [ { down;
box ht .2 wid 1 "area";
box ht .4 wid 1 \
"areaDesc" "circle" ;
} ]
arrow "currently" "only 1" \
from 0.1 - (.1,0) to BI.nw - (0, .1);
arrow from 0.6 - (.1,0) to BE.nw - (0, .1);
arrow "1..*" above from 0.05 - (.1,0) to BA.nw - (0, .1);
arrow "1..*" above from 0.1 - (.1,0) to BP.nw - (0, .1);
.PE
.SM
Figure 3: structure of CAP message of CAP-RSMCTK profile.
Boxes and italic letters indicate XML elements containing child elements.
Upright letters (ex. "identifier") in the boxes
indicate `leaf-node' XML elements that contain text.
Arrows with note
.B "1..*" ' `
indicate repeatable element.
Other element (including all leaf nodes) appears always and only once
in CAP-RSMCTK profile.
All elements must have namespace URI
.B "urn:oasis:names:tc:emergency:cap:1.2" ''. ``
.NL
.sp 2
.KE
.\"
.\" === End Figure 3 ===
.\"
.NH 2
Structure of CAP Message
.LP
A CAP message is an XML document whose root element is
.B alert '' ``
having namespace
.B "urn:oasis:names:tc:emergency:cap:1.2" ''. ``
RSMC Tokyo uses prefix
.B cap: '' ``
in the XML element name to indicate CAP namespace, like \*[cap alert],
but in general, it is not recommended to rely on this.
It is recommended to use XML parser that understands namespace.
.LP
Figure 3 illustrates rough structure of CAP-RSMCTK.
Structure under \*[cap alert]
is quite simplified in comparison to the CAP specification.
There is no optional element (that may be missing)
directly under \*[cap alert] or \*[cap info].
That means application programmers won't have to worry
about preparing for missing elements
such as \*[cap effective], \*[cap onset], \*[cap expires], ....
All optional information are given in \*[cap parameter] or \*[cap area]
(described in Sections \*[ref parameter] and \*[ref area], respectively).
.NH 2
How Many Messages in a Feed?
.LB howmany
.LP
One thing worth to think about is
how many new \*[cap alert] messages may appear in the Atom feed.
There are two reasons for the feed to contain many messages.
.LP
Firstly, when there are many tropical cyclones
in the RSMC Tokyo's responsibility area,
the center issues as many advisory bulletins (plain text version)
as the cyclones.
Conventional system supports six cyclones at one time at maximum:
the same type of TC advisory uses six different GTS headings
(WTPQ20 RJTD is the first cyclone and WTPQ25 RJTD is the sixth one),
though four cyclones at a time is very rare.
.LP
Secondly, a text bulletin is splitted into multiple \*[cap alert] messages
for simplicity inside the message\**.
.FS
Primary reason for creating separate \*[cap alert] for each \*[cap info]
is simple strucutre for handling.
However, if the community prefers,
it is technically possible to change this so that
only one \*[cap alert] is sent for a cyclone at a time
and that includes multiple \*[cap info] blocks.
.FE
At maximum\** four messages may be created for four forecast times
(analysis, and 24, 48, 72 hours of forecast).
.FS
It is possible that the number of messages are less than four.
.FE
.NH 2
Updates between Messages
.LB updates
.LP
If your application has to manage updates between successive advisories,
a suggested way is to split Atom feed into \*[cap alert] messages
to store as separated files or database entries.
.IP \(bu
When new messages (\*[cap sent]
is newer than stored messages) arrives,
search past messages by \fBTC_Number\fP attribute.
.IP \(bu
Messages with the same \fBTC_Number\fP and older \*[cap sent] can be updated.
.IP \(bu
If newer message has parameter \fBTC_Remark\fP to signal termination of work,
the messages for the cyclone can be discarded.
.IP \(bu
Anyway it is suggested to implement \*[cap expiration]
as a fail-safe measure to remove stale information.