RadioTAG v1.0.0 Draft 6

[Andy Buckingham]

It's with great pleasure I present Draft 6 of the RadioTAG technical specification.

This draft is now a candidate for ratification at the next RadioDNS steering board meeting. Please can I encourage anyone with interest in the project to review the draft at their earliest convenience. I would appreciate any feedback no later than 1700 UTC on 17th June 2015. This allows a reasonable window for an updated draft to be circulated before submitting to the steering board for their meeting in July.

You may recall Draft 5 was produced during the development of the EBU Cross Platform Authentication (CPA) specification during Q1 2014. The CPA group published their final specification late last year and the RadioTAG draft has been updated to include some minor changes from that final version.

In addition, the following other changes have been made:

• Moved endpoints to /radiodns/tag/1/ base path
  
  ETSI standardisation of RadioEPG in to an ETSI specification introduced a versioned path for locating IP-based documents. The RadioVIS part of the Slideshow specification also has a similar path for it's endpoint. By using a path we avoid the potential of conflicting with other endpoints on a multi-purpose server. The inclusion of a version number also makes future development of the specification easier to manage without breaking legacy implementations.
  
  
• Changed references for "station" to "bearer" or "service"
  
  RadioDNS and ETSI specifications commonly refer to radio stations as "radio services". The specific "station" param in HTTP POSTs is actually a Bearer definition, therefore it has been changed to "bearer".
  
  
• Add (optional) time source parameter
  
• 
  There are some concerns about how reliable the time attribute will be from differing clients with differing "clock" sources. It will be difficult to tackle this within the timescales to deliver a finalised 1.0 specification, so as a compromise and to aide future investigation, we have added an optional 'time_source' attribute which allows a client to inform the broadcaster of where they sourced the time from.
  
• 
  This will allow a broadcaster to make a better decision about how reliable that time might be and therefore potentially vary their response to the incoming tag to increase or decrease the range/scope of returned events.
  
  
• Change RadioDNS domain params format to bearerURI
  
• 
  The use of a RadioDNS FQDN format (without the .radiodns.org ending) to define a service is unusual in the wider scope of RadioDNS applications. Changed to the ETSI Hybrid Radio spec-defined bearerURI, which is intended to be a universal identifier for Bearers.
  
  
• Replace radiotag:sid and :service with simplified combined element, using bearerURI format
  
  Term sid was incorrect. Changing sid to bearer leaves us with 2x elements representing a service and it's relevant "location", therefore merging in to a single element with text body as the display name and attribute 'uri' with the bearer URI.
  
  
• Remove 100x100 image size restriction
  
  The RadioTAG specification should not be involved in the specification of display restrictions. The 100x100 restriction was placed in the spec due to the targeting of a specific device. Since inclusion, display technologies have improved significantly to the point that 100x100 may look poor on modern displays.

Thank you for your time and I look forward to receiving your feedback in due course.

Regards,

Andy Buckingham,

Application Team Lead for RadioTAG.

[Chris Needham]

Hi Andy,

> It's with great pleasure I present Draft 6 of the RadioTAG technical specification.

Many thanks for your work updating the RadioTAG spec. I have a few minor comments, mainly about the Content-Type HTTP header:

Page 7:

"bits of the API hang together"

Is the language here a bit too informal? I suggest "parts of the API work together"

Page 11:

In the description of time_source, I suggest adding a line break before "When not set", to clarify that this text doesn't apply to the 'ntp' value.

Page 12 (section 6.1.3):

The POST /tag response has Content-Type: text/html;charset=utf-8, but the example response body shown is plain text, not HTML.

Page 23 (section 9.1.1):

The POST /radiodns/tag/1/tag response has Content-Type: text/html;charset=utf-8, but the example response body shown is plain text, not HTML.

Page 24:

The POST /register response does not have a Content-Type header.

Page 27:

The POST /associate request shows Content-Type: application/x-www-form-urlencoded but the body is JSON.

Page 34:

The GET /radiodns/tag/1/tags response has Content-Type: text/html;charset=utf-8, but the example response body shown is plain text, not HTML.

Page 35:

The POST /register response does not include a Content-Type header.

Page 36:

The POST /token request has Content-Type: application/x-www-form-urlencoded but the request body shown is JSON.

Also, more generally, as we're using the Atom format, should we use application/atom+xml as the Content-Type, rather than application/xml?

I realise some of these comments may not be related to the changes introduced in this new draft, so please forgive me if I'm retreading old ground.

Chris

--
Chris Needham
Senior Software Engineer
BBC Research & Development

________________________________________
From: radiotag-...@googlegroups.com [radiotag-...@googlegroups.com] on behalf of Andy Buckingham [andy.bu...@radiodns.org]
Sent: 03 June 2015 16:00
To: RadioTAG Application Team
Subject: RadioTAG v1.0.0 Draft 6

It's with great pleasure I present Draft 6 of the RadioTAG technical specification.

This draft is now a candidate for ratification at the next RadioDNS steering board meeting. Please can I encourage anyone with interest in the project to review the draft at their earliest convenience. I would appreciate any feedback no later than 1700 UTC on 17th June 2015. This allows a reasonable window for an updated draft to be circulated before submitting to the steering board for their meeting in July.

You may recall Draft 5 was produced during the development of the EBU Cross Platform Authentication (CPA) specification during Q1 2014. The CPA group published their final specification late last year and the RadioTAG draft has been updated to include some minor changes from that final version.

In addition, the following other changes have been made:

* Moved endpoints to /radiodns/tag/1/ base path

ETSI standardisation of RadioEPG in to an ETSI specification introduced a versioned path for locating IP-based documents. The RadioVIS part of the Slideshow specification also has a similar path for it's endpoint. By using a path we avoid the potential of conflicting with other endpoints on a multi-purpose server. The inclusion of a version number also makes future development of the specification easier to manage without breaking legacy implementations.

* Changed references for "station" to "bearer" or "service"

RadioDNS and ETSI specifications commonly refer to radio stations as "radio services". The specific "station" param in HTTP POSTs is actually a Bearer definition, therefore it has been changed to "bearer".

* Add (optional) time source parameter
*

There are some concerns about how reliable the time attribute will be from differing clients with differing "clock" sources. It will be difficult to tackle this within the timescales to deliver a finalised 1.0 specification, so as a compromise and to aide future investigation, we have added an optional 'time_source' attribute which allows a client to inform the broadcaster of where they sourced the time from.

*
*

This will allow a broadcaster to make a better decision about how reliable that time might be and therefore potentially vary their response to the incoming tag to increase or decrease the range/scope of returned events.

* Change RadioDNS domain params format to bearerURI
*
*
The use of a RadioDNS FQDN format (without the .radiodns.org<http://radiodns.org> ending) to define a service is unusual in the wider scope of RadioDNS applications. Changed to the ETSI Hybrid Radio spec-defined bearerURI, which is intended to be a universal identifier for Bearers.

*
*
* Replace radiotag:sid and :service with simplified combined element, using bearerURI format

Term sid was incorrect. Changing sid to bearer leaves us with 2x elements representing a service and it's relevant "location", therefore merging in to a single element with text body as the display name and attribute 'uri' with the bearer URI.

* Remove 100x100 image size restriction

The RadioTAG specification should not be involved in the specification of display restrictions. The 100x100 restriction was placed in the spec due to the targeting of a specific device. Since inclusion, display technologies have improved significantly to the point that 100x100 may look poor on modern displays.

Thank you for your time and I look forward to receiving your feedback in due course.

Regards,

Andy Buckingham,
Application Team Lead for RadioTAG.

--
You received this message because you are subscribed to the Google Groups "RadioTAG developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to radiotag-develo...@googlegroups.com<mailto:radiotag-develo...@googlegroups.com>.
For more options, visit https://groups.google.com/d/optout.

[Andy Buckingham]

Hi Chris,

Thank you for your detailed review:

On 5 June 2015 at 11:45, Chris Needham <chris....@bbc.co.uk> wrote:

Hi Andy,

> It's with great pleasure I present Draft 6 of the RadioTAG technical specification.

Many thanks for your work updating the RadioTAG spec. I have a few minor comments, mainly about the Content-Type HTTP header:

Page 7:

"bits of the API hang together"

Is the language here a bit too informal? I suggest "parts of the API work together"

I agree, we should formalise this language and appreciate your suggestion.

 

Page 11:

In the description of time_source, I suggest adding a line break before "When not set", to clarify that this text doesn't apply to the 'ntp' value.

I agree, the comment could easily be missed without the line break.

 

Page 12 (section 6.1.3):

The POST /tag response has Content-Type: text/html;charset=utf-8, but the example response body shown is plain text, not HTML.

This is a mistake and should be correct.

 

Page 23 (section 9.1.1):

The POST /radiodns/tag/1/tag response has Content-Type: text/html;charset=utf-8, but the example response body shown is plain text, not HTML.

As above.

 

Page 24:

The POST /register response does not have a Content-Type header.

This is incorrect, it should read "Content-Type: application/json".

 

Page 27:

The POST /associate request shows Content-Type: application/x-www-form-urlencoded but the body is JSON.

This is incorrect, it should read "Content-Type: application/json". 

 

Page 34:

The GET /radiodns/tag/1/tags response has Content-Type: text/html;charset=utf-8, but the example response body shown is plain text, not HTML.

This is incorrect, it should be "text/plain".

 

Page 35:

The POST /register response does not include a Content-Type header.

This is incorrect, it should have one and be "application/json".

 

Page 36:

The POST /token request has Content-Type: application/x-www-form-urlencoded but the request body shown is JSON.

This is incorrect, it should be "application/json". 

 

Also, more generally, as we're using the Atom format, should we use application/atom+xml as the Content-Type, rather than application/xml?

Good spot, I think we should correctly adhere to the Atom standard and therefore I agree with clarifying the MIME to be atom+xml. 

 

I realise some of these comments may not be related to the changes introduced in this new draft, so please forgive me if I'm retreading old ground.

Not at all, as we're pushing for ratification the whole document is up for careful scrutiny. Thanks again for your assistance.

Should there be no disagreement from other members, I will publish a revision to the draft on Wednesday with these changes. If anyone else has any thoughts on Draft 6 please do try and get these in before Wednesday for inclusion in the next revision.

 

To unsubscribe from this group and stop receiving emails from it, send an email to radiotag-develo...@googlegroups.com.