Ok, so then we'll have some repeated data in vcalendar and transitIncident.
I don't have anything against that, I just wanted to be sure that I
understood what you meant.
Here's another draft. Let's see if I didn't miss anything:
Changes:
I've moved the old "human-readable values only for now" to a "will add
later" section, as there's no point having them in what, for now, is a
machine-readable section only.
For the same reason, I've moved back to the old "abbr/title" way of dealing
with fields with both machine-readable and human-readable data, to more
closely follow that microformats idiom.
I've added the fields additionalText and moreInfoURL: had talked about them
in the conversation, but never actually got around to putting them in a nice
proposal.
I've reformatted the explanation so that it can still be understood even if
the email program cuts lines into two.
I've added a few examples at the end.
In your previous email you say that you won't provide both machine- and
human-readable data for "vcalendar" and "transitIncident". That's fine with
me, but having this in the standard suggests that it's forbidden to have
both. I think it may be better to say that it's ok to give just one, and
that if both are given then the "title" idiom should be used. Just after the
node list I've added yet another proposal on how to handle this. It will be
easy for both people and computers to make sense of data given in that
format. From your comments, I see that you'll be using options 2, 4, and 6.
-------
A transit incident is defined by the following HTML nodes. These can, for
example, be in the <description> node of an RSS post:
- content:
Text of the alert message that was sent to subscribers
- vcalendar
hCalendar document tree; human or machine data but not both for each class
contains general date information for this alert.
You may want to set the style to display:none for this node.
- transitIncident: surrounding node: machine-readable information about this
alert
(however human-readable information can be included too)
You most surely want to set the style to display:none for this node, so
that humans will read the "content" node above and not this.
- transitIncident.affectedResource: surrounding node, optionally repeated:
what is being affected by this alert. It contains:
- transitIncident.affectedResource.routeShortName: optional; if missing, all
routes affected; example: "N" or "71"
- transitIncident.affectedResource.stopName: optional; if missing, all stops
--maybe for a particular line-- affected; example: "Main Street"
- transitIncident.incidentDate: surrounding node, optional if all contents
are missing; when the incident has an effect. It contains:
- transitIncident.incidentDate.dtstart: start date+time; optional; if
missing, starts far in the past; ISO-formatted date is included in the
"title" attribute, as hCalendar does:
<abbr class="dtstart" title="2008-05-16">Monday, May 16, 2008</abbr>
- transitIncident.incidentDate.dtend: end date+time; optional; if missing,
never ends; ISO-formatted date as in dtstart
- transitIncident.publishDate: surrounding node, optional if all contents
are missing; when we should tell about the incident. It contains:
- transitIncident.publishDate.dtstart: start date+time; optional; if
missing, starts far in the past; ISO-formatted date as in incidentDate
- transitIncident.publishDate.dtend: end date+time; optional; if missing,
never ends; ISO-formatted date as in incidentDate
- transitIncident.agencyName: optional; if missing, we can infer the agency
name from the feed this data comes from
- transitIncident.incidentId: optional; unique id that can later be used to
refer to this incident or update. If none is given, and we'll use the RSS
guid or the ATOM atom:id as the incidentId, prefixed with the string
"feed:".
- transitIncident.originalIncidentId: value of the incidentId field for a
previous post.
- transitIncident.updateType: optional; for updates, the kind of update.
Machine-readable values are "update" and "cancellation"; the machine
readable value is to be combined with an eventual human-readable value as
<abbr class="updateType" title="cancellation">Clear</abbr>
- transitIncident.additionalText: optional; human-readable text which we'd
like displayed with this alert, and which does NOT repeat information
already given in the machine-readable fields.
- transitIncident.moreInfoURL: optional; URL pointing to a page with
additional information. We should only use this if the containing format
(RSS, Atom) does not provide a way to associate such URLs to a post.
In general, each node can contain either
1- some text which is both machine-readable and human-readable, in the
contents: <tag>contents</tag>
2- human-readable text only, in the contents: <tag>May Day, 2009</tag>;
however, some readers of your data may actually be machines, and may not be
able to make sense of this
3- human-readable text in the contents and machine-readable text in the
title attribute: <tag title="1234BDGC5xx465">Main Street</tag>
4- machine-readable text only, in the contents: <tag>1234BDGC5xx465</tag>;
however, unless you provide equivalent human-readable data somewhere else
and you mark this tag with style "display:none", you will confuse your human
readers because they'll see garbage
5- machine-readable text only, in the title attribute: <tag
title="1234BDGC65cx"></tag>; however, unless you provide equivalent
human-readable data somewhere else your human readers will be missing some
information.
6- And, as usual with microformats, human-readable data can be put anywhere
in the contents of a surrounding node, outside of the inner nodes, and will
be ignored by machine readers. For example
<div class="incidentDate">This text will be ignored by computers<span
class="dtstart">Since there is no 'title', computers will think this is a
date and will get confused</span>This will be ignored too</div>
To add a new incident:
- Post a "transitIncident".
"affectedResource" is required, and can be repeated.
"originalIncidentId" must not be present.
"updateType" must not be present.
All other fields are optional.
To update an existing incident:
- Post a "transitIncident".
"originalIncidentId" must be present, and be the "incidentId" of the
incident that this is updating.
"incidentId" is optional; if not given, we'll assign an incidentId to this
update post using the RSS guid or ATOM atom:id as described before.
"updateType" must be present and set to "update".
"affectedResource" is optional, and can be repeated; if present, we want to
change the list of affected resources.
All other fields are optional. If missing, it means we don't want to update
it in the original post.
To clear an incident:
- Post a "transitIncident".
"originalIncidentId" must be present, and be the "incidentId" of the
incident that this is updating.
"updateType" must be present and set to "cancellation".
All other fields must not be present.
A machine-based client may still show this incident for some time
(indicating that it is cleared, however).
It is also possible to clear an incident by updating it (see before), with
an end effect date (incidentDate.dtend) in the past.
It is possible to force us to stop publishing an incident by updating it
(see before), with an end publish date (publishDate.dtend) in the past.
We will add the following fields in the future, when we have thought of a
good way to make them machine-readable:
- transitIncident.affectedResource.stopResourceType: optional; for
accessibility messages, it indicates which resource in a stop is affected
(elevator, escalator, wayside lift)
- transitIncident.affectedResource.stopResourceLocation: optional; for
accessibility messages, it indicates which resource in a stop is affected
(example: concourse to inbound platform)
- transitIncident.incidentDate.incidentRecurrence: optional
- transitIncident.incidentCause: optional
- transitIncident.incidentEffect: optional
Notes:
I've removed the field
- messageType: optional; human-readable content only, for now; example
values: transit alert, transit advisory, accessibility alert, accessibility
advisory. "Alert" means "unplanned event, effective now", and "advisory"
means "planned event" which I find redundant. Let's discuss if we want to
add it back.
Example for adding a new incident:
<description>
<div class="content">Bank station is closed for repairs from April 12th to
April 16th. Please use Green station instead.</div>
<div class="vcalendar" style="display:none">
<span class="dtstart" title="2008-04-12">April 12th, 2008</span>
<span class="dtend" title="2008-04-16">April 16th, 2008</span>
</div>
<div class="transitIncident" style="display:none">
<div class="affectedResource">
<span class="stopName">Bank</span>
</div>
<div class="incidentDate">
<span class="dtstart" title="2008-04-12">April 12th, 2008</span>
<span class="dtend" title="2008-04-16">April 16th, 2008</span>
</div>
<div class="publishDate">
<span class="dtend" title="2008-04-16">April 16th, 2008</span>
</div>
<div class="additionalText">Please use Green station instead.</div>
<a class="moreInfoURL" href="www.someagency.com?alert=57625">Click here
for more information.</a>
<div class="incidentId">57625</div>
</div>
</description>
The same example with the fields that I just said "would be added in the
future", with some example values of how I'd like them to look like:
<description>
<div class="content">Bank station is closed for repairs from April 12th to
April 16th. Please use Green station instead.</div>
<div class="vcalendar" style="display:none">
<span class="dtstart" title="2008-04-12">April 12th, 2008</span>
<span class="dtend" title="2008-04-16">April 16th, 2008</span>
</div>
<div class="transitIncident" style="display:none">
<div class="affectedResource">
...
|
