XSPF v1 Notes and Errata: Difference between revisions

From XiphWiki
Jump to navigation Jump to search
m (→‎xml:base: Fix XML comment)
(→‎xml:base: Swap two sentences)
Line 210: Line 210:
  </playlist>
  </playlist>


Both XSPF-0 and XSPF-1 support the ''xml:base'' attribute and your implementation of XSPF should do as well. Though XML Base is mentioned in the XSPF specification, the ''xml:base'' attribute is not mentioned explicitly.
Though XML Base is mentioned in the XSPF specification, the ''xml:base'' attribute is not mentioned explicitly. Both XSPF-0 and XSPF-1 support the ''xml:base'' attribute and your implementation of XSPF should do as well.


= Errata =
= Errata =

Revision as of 12:06, 29 July 2008

This page lists errata of the XSPF version 1 document and also gives advice on using and understanding XSPF.

Notes

<trackList> and <trackNum> spelling

Please note that trackList and trackNum elements MUST NOT be written in all lowercase since XSPF is case-sensitive. These two are the only elements containing capital letters so just remember trackList and trackNum and your XSPF will be fine.

Absolute vs. relative URIs in key attibutes

The attributes rel (<meta> and <link>) and application (<extension>) are by XSPF v1 specification allowed to hold relative URIs. For example this meta element is legal in XSPF v1:

<meta rel="playCount">14</meta>

While this might look elegant it comes with several drawbacks:

  • You might easily forget that this string is a URI and include non-URI characters like spaces by mistake (e.g. rel="play count" is not valid)
  • You lose the namespace concept: nobody will know what or whom this key belongs to or came from

For these reasons it is strongly recommended to use absolute URIs as keys instead:

<meta rel="http://example.com/track/meta/playCount/1/0/">14</meta>

Version information in key attributes

When defining you own extensions to XSPF you will have to choose an application URI for your onw extensions:

<extension application="http://example.com/myext/">
  ..
</extension>

Please consider including version information in your application URIs and increase it whenever the structure of your extension changes:

<extension application="http://example.com/xspf/track/1/0/">
  ..
</extension>

This enables others to properly distinct different versions of your extensions without the need to do version guessing. Adding version information to rel of <meta> and <link> is a good idea as well:

<meta rel="http://example.com/track/meta/playCount/1/0/">14</meta>

Element order

In XSPF child elements can appear in any order. That means that for example both these tracks are valid for XSPF v1.

As appearing in the specification:

<track>
  <creator>Creator first</creator>
  <album>Album after</album>
</track>

Also valid:

<track>
  <album>Album first</album>
  <creator>Creator after</creator>
</track>

This is not mentioned in the specification and might have been ignored by some implementations. Thus for people implementing XSPF support that means:

  • XSPF readers must be able to deal with arbitrary element order
  • XSPF writers should always produce XSPF files with elements in the order appearing in the specification for maximum compatibility.

To save you extracting this information yourself the order of elements appearing in the XSPF specification is:

  • playlist
  • playlist.title
  • playlist.creator
  • playlist.annotation
  • playlist.info
  • playlist.location
  • playlist.identifier
  • playlist.image
  • playlist.date
  • playlist.license
  • playlist.attribution
  • playlist.attribution.location
  • playlist.attribution.identifier
  • playlist.link
  • playlist.meta
  • playlist.extension
  • playlist.trackList
  • playlist.trackList.track
  • playlist.trackList.track.location
  • playlist.trackList.track.identifier
  • playlist.trackList.track.title
  • playlist.trackList.track.creator
  • playlist.trackList.track.annotation
  • playlist.trackList.track.info
  • playlist.trackList.track.image
  • playlist.trackList.track.album
  • playlist.trackList.track.trackNum
  • playlist.trackList.track.duration
  • playlist.trackList.track.link
  • playlist.trackList.track.meta
  • playlist.trackList.track.extension

Whitespace

Whitespace handling in XML can be a little difficult to understand at first. Since XSPF is based on XML, people implementing XSPF readers or writers do have to know about the basics of whitespace handling in XML. The good things is we summed it up here to make things easier for you.

Ignore in non-leaf elements

Whitespace in elements only holding child elements (but no text) must be ignored.

Elements affected:

  • playlist
  • playlist.attribution
  • playlist.trackList
  • playlist.trackList.track

Process in non-string leaf elements

In XSPF all elements with non-string content (i.e. of type dateTime, nonNegativeInteger, or anyURI) must be process with the "collapse" method. Sounds difficult but is easy:

  • Leading and trailing whitespace ('\t'(0x08), '\n'(0x0a), '\r'(0x0d), ' '(0x20)) is removed
  • Whitespace "in the middle" is converted to a single space (think s/[\t\n\r ]+/ / Perl people)

For example the three-line text

  ABC
DEF	GHI

will become

ABC GHI DEF

Elements affected:

  • playlist.attribution.identifier
  • playlist.attribution.location
  • playlist.date
  • playlist.identifier
  • playlist.image
  • playlist.info
  • playlist.license
  • playlist.link
  • playlist.location
  • playlist.meta
  • playlist.trackList.track.duration
  • playlist.trackList.track.identifier
  • playlist.trackList.track.image
  • playlist.trackList.track.info
  • playlist.trackList.track.link
  • playlist.trackList.track.location
  • playlist.trackList.track.meta
  • playlist.trackList.track.trackNum

Keep in "real" string leaf elements

Whitespace in string elements is significant and has to be preserved. So if <annotation> contains line feeds the annotation text really spans several lines:

<annotation>Line feeds and even spaces are preserved.
This example annotation spans two lines</annotation>

Elements affected:

  • playlist.annotation
  • playlist.creator
  • playlist.title
  • playlist.trackList.track.album
  • playlist.trackList.track.annotation
  • playlist.trackList.track.creator
  • playlist.trackList.track.title

Do X in Extensions

Whitespace handling inside of extension elements depends on the specific extension.

Elements affected:

  • playlist.extension
  • playlist.trackList.track.extension

URI RFC used

The XSPF v1 specification mentions RFC 2396 when talking about URIs. As asking on uri@w3.org revealed, we should have referred to STD 66 instead which stands for "latest RFC of URI" (RFC 3986 as of 2007-07-09). What does that mean practically?

This means:

  • You can use IPv6 host part URIs in XSPF v1
  • You should use a RFC 3986 parser for your XSPF v1 implementation

<playlist.location> vs. xml:base

playlist.location

.. contains the (possibly relative) URI recommended to retrieve the surrounding playlist (or an updated version of it). playlist.location is not an embedded base URI used to resolve relative URIs, xml:base is. playlist.location can be thought of as XSPF's counterpart to Atom's feed.link element:

atom:feed elements SHOULD contain one atom:link element with a rel
attribute value of "self".  This is the preferred URI for
retrieving Atom Feed Documents representing this Atom feed.

xml:base

.. is an xml-wide attribute defined in XML Base. If xml:base is set it contains the absolute URI that must be used to resolve any relative URI from the surrounding XSPF playlist, as an embedded URI has highest priority when resolving relative URIs (from XSPF-1, 6.2 Relative paths, originally from XML Base, 4.1):

  1. The base URI is embedded in the document's content.
  2. The base URI is that of the encapsulating entity (message, document, or none).
  3. The base URI is the URI used to retrieve the entity.
  4. The base URI is defined by the context of the application.

Please note this also includes the playlist.location element.
Here is an example of using xml:base with XSPF:

<?xml version="1.0" encoding="UTF-8"?>
<playlist version="1" xmlns="http://xspf.org/ns/0/" xml:base="http://example.org/one/">
  <location>two</location><!-- Resolves to http://example.org/one/two -->
  <trackList />
</playlist>

Though XML Base is mentioned in the XSPF specification, the xml:base attribute is not mentioned explicitly. Both XSPF-0 and XSPF-1 support the xml:base attribute and your implementation of XSPF should do as well.

Errata

4.1.1.2.12.2 content

This paragraph describes the content of playlist.meta. It also reads "xspf:playlist elements MAY contain exactly one" which does not make sense for the content of an element and can be safely ignored.

4.1.1.2.14.1.1.1.12.2 content

This paragraph describes the content of playlist.trackList.track.meta. It also reads "xspf:playlist elements MAY contain exactly one" which does not make sense for the content of an element and can be safely ignored.