Notes on the current RadioTag proposal

[Sean O'Halpin]

On Wednesday last week (4th May 2011), Andy Buckingham, Robin Cooksey
and I (Sean O'Halpin) met up to discuss RadioTag.

We agreed some specific points regarding client id generation, the
format of submissions and responses, and some principles in the
overall design of the RadioTag spec.

In the context of improving the 'out of the box' experience, we also
discussed enabling tagging without having to register ('unpaired'
tagging).

Paired tagging is what we've been calling authenticated tagging - the
pairing is between the device (aka client) and an authenticated user
account. I'll deal with the first two of these in more detail below.

In summary, they can be compared as follows:

| | Authorized | Authenticated |
|-----------+------------+---------------|
| Unpaired | Yes | No |
| Paired | Yes | Yes |

We also all agreed being able to list tags on the device itself would
greatly enhance the user experience. I'll also deal with this in more
detail below.

It's become apparent the bulk of the RadioTag spec is now
about authentication and authorization. If other RadioDNS services
require authorization, we wouldn't want them to have to repeat or
reinvent what we've come up with. So the idea was mooted that perhaps
a separate RadioAuth spec would be in order to define how unpaired
clients and authenticated user accounts interact. Maybe it's too early
to generalize to this extent (there's nothing else on the table which
requires authentication yet) but still we're curious to hear your
opinions on this.

Finally, we would especially welcome feedback/ideas on the following
open issues:
- what data should be included in a tag
- how to upgrade from an unauthenticated tag list to an authenticated
one (how this would work on the device and on the server)
- how paging through a list of tags should work

* Server generating client_id

We agreed it makes sense for the server to generate client ids as it's
more difficult for device firmware to generate UUIDs. This also allows
the server side to apply some basic gatekeeping (in that it will
accept only requests that contain its own client ids).

* Format of submissions

We agreed that the data format of submissions should be
"application/x-www-form-urlencoded", i.e. what you normally submit
from a FORM on an HTML page. Version 1.0 of the spec will not require
any structured data so this will suffice.

* Format of responses

We agreed that we will use XML as the data format.

We also agreed that we would use Atom as the basis for structuring
data, both for individual tags and lists of tags.

The spec should define a specific subset of Atom to cover our needs
and possibly include a schema which could be used to validate on the
server side.

We didn't come up with a definitive specific subset. Here are our
ideas - suggestions are welcome.

In the following, the element prefix "radiotag:" indicates the
RadioTag namespace. All other elements are assumed to be from the Atom
namespace.

Atom defines the following as required:

| Element | Description |
|---------+---------------------------------------------|
| id | unique identifier for this tag |
| title | broadcaster generated title |
| updated | datetime tag was modified in ISO format UTC |

We would also want at least the following to be required:

| Element | Description |
|------------------+-------------------------------------------------|
| author | name of tag service provider (e.g. BBC, Global) |
| published | datetime of creation (= tag time) |
| summary | text only - i.e. must not include HTML tags |
| link rel="image" | link to 100x100 image representing tag |
| link rel="self" | user accessible url for tag |
| radiotag:service | human-readable name of service tagged |
| radiotag:sid | RadioDNS service identifier |

Note the difference here between 'id' and 'link rel="self". 'id' is a
globally unique identifier. 'link rel="self"' gives the url as visible
to the device/user (i.e. scoped by the auth token).

For example:
#+begin_src xml
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom"
xmlns:radiotag="http://radiodns.org/radiotag">
<title>Sean's Tags</title>
<link href="http://radiotag.bbc.co.uk/tags"/>
<link rel="self" href="http://radiotag.bbc.co.uk/tags"/>
<link rel="next" href="http://radiotag.bbc.co.uk/tags?page=2"/>
<updated>2011-05-05T08:15:00Z</updated>
<author>
<name>BBC</name>
</author>
<id>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6</id>
<entry>
<title>In Our Time: Thu 5 May 2011</title>
<radiotag:sid>0.c224.ce15.ce1.dab</radiotag:sid>
<radiotag:service>BBC Radio 4</radiotag:service>
<link rel="self" href="http://radiotag.bbc.co.uk/tags/1"/>
<link rel="image"
href="http://www.bbc.co.uk/iplayer/images/episode/
b010t69b_640_360.jpg"/>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
<updated>2011-05-11T08:15:00Z</updated>
<published>2011-05-11T08:15:00Z</updated>
<summary>Melvyn Bragg and his guests discuss the origins and
early
development of Islamic law.</summary>
</entry>
</feed>
#+end_src

(Note that I'm including the Atom pagination 'link rel="next"' here
but see below for more discussion about this.)

Some open questions:

- do we want 'id' to be a unique universal identifier or could we use
a device/user scoped url as in the 'link rel="self"' case (and so
get rid of the latter)?
- what other link types might we want?
- any other elements needed?
- are we happy with the semantics we're applying to the 'updated' and
'published' elements or should we use our own more specific elements
under the radiotag namespace?
- are we happy using 'author' this way? Should we use 'source'
instead? Our own element?

Plenty to mull over there. All contributions welcome.

If there are any Atom experts out there who can see issues with the
above proposal, please chip in - we want this to be squeaky clean.

Robin agreed to come up with reasonable limits for the contents of
each tag in the Atom entry to accommodate device constraints.

Finally, we agreed that the initial response to a tag would be a
string of text (Robin to supply limit). Specifically, it would /not/
be the Atom representation of the tag. The Atom representation is
intended to be used in lists (see below).

* General principles

We agreed the following general principles:

- the spec should not assume anything about the content of the tag,
though it must define the structure of responses. In other words,
the spec defines how the data is represented but the broadcaster
decides the content
- the spec should not assume that tags contain any programme metadata
- entries should not contain any substructure, i.e. they should
contain only text
- we will use UTF-8 encoding throughout

One consequence of these principles is that the spec should not assume
the presence of a programme metadata service.

* 'Unpaired' tagging

The idea of unpaired tagging is that you can provide an 'out of the
box' experience without the user needing to set up and pair with a
user account on a given service.

The basic idea is that (after a bit of under-the-hood negotiation
between client and service) the client ends up with a token that
grants it permission to create tags under a (possibly temporary)
device-specific account. The user can create and list tags on the
device without registering the device. The total number of tags
created this way can be limited, with new tags pushing out the oldest
ones (i.e. FIFO). Later, the user can register the device under an
authenticated user account and access the tags previously created on
the device via the new account.

The response to an initial unauthenticated tag request will specify
which levels of service the tag service provides. The level of service
can be one of:

- unpaired only
- paired only
- unpaired or paired

where 'unpaired' is effectively synonymous with 'unauthenticated' and
'paired' synonymous with 'authenticated'.

Where a choice of unpaired or paired tagging is available, the device
has to present an option to the user to either OK the tag or to
register.

The response should include auth tokens granting permission to request
either an unpaired auth token or a paired client id.

If the user chooses OK, then the device should use the unpaired
request token to request an unpaired auth token from the tag service
(which should be a UUID) with which it can then complete the tag
process using the unpaired auth token in place of the authenticated
auth token. The server side will have to distinguish between unpaired
auth tokens and authenticated auth tokens and create holding accounts
to store tags for unpaired auth tokens. How exactly this should work
is still up for grabs.

If the user chooses to register, then the device should display the
registration instructions (taken from the 401 response) which should
include the web front end url. The process should then proceed as
previously discussed.

Note that until the client registers the device, all responses to a
tag request will be 401 Unauthorized.

There are a few issues that unpaired tagging throws up.

The first is that unpaired tagging is anonymous and associated only
with the device. For example, this means there's no way for a user to
clear their tags once they have sold a device. I don't know how
worried we should be about that.

Allowing unpaired, unauthenticated tagging opens service providers up
to the possibility of being spammed by anonymous users. To alleviate
this problem we came up with a scheme that requires a bit of
negotiation on the part of the client. This does not completely remove
the threat of spamming but does mean that a client has to negotiate a
protocol in order to create tags. This will at least discourage the
script kiddies. Requiring the client to request a temporary auth
token/id from the tag provider means that we can at least validate
that requests are coming from clients which have gone through the
rigmarole of asking politely if they can create tags.

To alleviate the problem of using up service provider resource, we
agreed it made sense to limit the total number of tags that could be
stored this way though we did not decide on a specific number. It
seems reasonable to specify a minimum in the spec but leave the
maximum up to the provider.

As presented above, permitting unpaired tagging adds a good deal more
complexity to the protocol for both the client and server.

Lastly, this process introduces an element of service discovery in the
authentication response. Whether this is the right place to do so is
up for discussion.

* Lists of tags on the device

We all agreed it would be very desirable to be able to view a
list of tags on the device.

The list of tags would be returned to the device in response to a GET
request to the tag service which includes the current auth token
(unpaired or paired).

As agreed, we want to use Atom
(http://en.wikipedia.org/wiki/Atom_(standard)) as the basis for
structuring data about tags. Atom defines a number of standard but
generic tags (e.g. title, summary, source) that we can use to provide
a standardized description of the tag generated. This allows the
device to rely on a standard set of tags while leaving the content up
to the broadcaster. See below for an example.

As a user may have a large list of tags, we want to restrict the
number of entries returned to the device but also enable the device to
page through the results to list all tags.

There are a number of options we can pursue.

The Atom pagination spec
(http://tools.ietf.org/html/rfc5005#section-3) adds paging entries of
the form
#+begin_src xml
<link rel="next" href="http://example.org/index.atom?page=2"/>
#+end_src
but this does not allow the device to specify how many entries it
wants per page.

We could mandate a specific number of entries per page and let the
device manage that, but that seems restricting for more capable
clients.

With the addition of a =limit= parameter, the client could define how
many entries it wants per page.

Perhaps we could borrow from the OpenSearch spec and use =startIndex=
and =count= to achieve the same goal. See
http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_1.1_parameters.

All this is up for discussion.

Whichever method we choose, it seems most useful /by default/ to list
most recent first (by tagged date), i.e. by what the user most
recently did rather than by an externally derived date (e.g. programme
TX date). The spec could include sort order as a optional parameter.

[Kat]

This seems extremely well thought-through, thanks Sean.

I wonder if we shouldn't rename the unauthenticated/unauthorised level
of tagging though, as it's a little ambiguous. Especially as the word
is commonly used elsewhere, and later on you use it to describe the
second level, unpaired tagging (unauthenticated/authorised):

"The first is that unpaired tagging is anonymous and associated only
with the device. For example, this means there's no way for a user to
clear their tags once they have sold a device. I don't know how
worried we should be about that.

Allowing unpaired, unauthenticated tagging opens service providers up
to the possibility of being spammed by anonymous users."

Avoiding the use of the term 'anonymous' to describe the three kids of
tagging allowed by the spec would clear this up. I'm afraid I've not
got many good suggestion though. Unknown? Unidentified? Anyone got any
better suggestions?

Kat

> and =count= to achieve the same goal. Seehttp://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_1.....