History:Development/XML Web Service/Version 1

This page describes the next generation XML based web service for MusicBrainz. Initially we will discuss the proposed XML and its Relax NG schema for expressing MusicBrainz (and music in general) metadata. Once we hammer that out, we'll discuss the URL scheme proposed by Matthias Friedrich.

Use Cases

This new web service will have the following use cases:

• Retrieve artist (via mbid)/album (via mbid/cdid)/track (via mbid)
  • Each of these should return a minimal amount of data and have options to return more detailed data:
    • artist: optional list of albums
    • album: optional artist info, cdids, release info, list of tracks
    • track: optional artist info

• Retrieve a list of tracks that match a given trmid
  • same arguments that apply to track info should be used here

• Full text search of the DB (via lucene query)
• Login to MB
• Submit trmids (after login)
• Check donation status of user (for showing pop-ups in Picard)
• Lookup track (like MBQ_FileLookup)

URL Schema

The web service will be REST style, which means we need a structure for our URL namespace. The schema discussed below allows for future development (using versions) and different types of output (using content negotiation). There will be at least three types of resources: artist, album and track, but more can be added later. You can either request a resource by its ID or apply a filter to the set of all resources of a type.

General query parameters, available for all resources:

type	xml, html, whatever we want to support
inc	A list of space separated values describing how much detail should be included in the output. If there is no 'inc' parameter, just the basic data for a resource is returned. For artists that would be name and sortName.

The 'inc' parameter is the successor of the old web service's depth concept. To keep the system scalable and to minimize download times, we should only include the minimal usable amount of data. Users can either use the 'inc' parameter to request more detail or issue another query.

artist resources

Parameters for http://musicbrainz.org/ws/1/artist/MBID:

inc	Supported: 'albums', 'va-albums'

Parameters for http://musicbrainz.org/ws/1/artist/:

name	Fetch a list of artists with a matching name
limit	Limit the number of artists returned

album resources

Parameters for http://musicbrainz.org/ws/1/album/MBID:

inc	Supported: 'cdids', 'tracks', 'releases'

Parameters for http://musicbrainz.org/ws/1/album/:

title	Fetch a list of albums with a matching title
cdid	Fetch all albums matching to the given CdIndexId
limit	Limit the number of albums returned

track resources

Parameters for http://musicbrainz.org/ws/1/track/MBID:

inc	Supported: 'trms'

Parameters for http://musicbrainz.org/ws/1/track/:

title	Fetch a list of tracks with a matching title
artist	The returned tracks have to match the given artist name
album	The returned tracks have to match the given album title
limit	Limit the number of tracks returned

XML Format

There is a single schema for all responses of the web service. The definition isn't finished yet, there are a few issues that have to be discussed:

• Use 'mb' prefixes or make it the default namespace?
• Do we really need amazon and DC namespaces? If we later want to make the format extensible by allowing

• people to add elements in their own namespaces, amazon and DC will look like extensions.

• The 'mb:counts' element is weird. If we don't need the 'trmid' attribute, we can easily add the track

• counts to the 'track-list' element and 'cdid' to 'cdid-list'.

• Some data is coded in attributes but most is in elements. How about removing all attributes except for ids?
• ARs are currently missing.

RobertKaye's responses:

• Lets use a default namespace and use mmd as the short name of the namespace. Music Meta Data.
• I think its good practice to use dc -- we should keep it. But declaring the az namespace for one element is silly.
• The counts element is intented to convey metadata about an album -- it can be useful to know how many ids of the various types there are without actually getting any of the ids. Maybe we can find a better name?
• I did that to conserve space in the output -- esp with the counts where you could have 1000%+ overhead to represent a single digit integer... The RDF/XML is so VERBOSE that we're wasting TONS of bandwidth on a verbose encoding. Let's tighen this one and make it easier to look at.
• Yup, still on the todo list.

The following sample XML document describes a partial album:

<?xml version="1.0" encoding="UTF-8"?>
<mb:metadata xmlns:dc="http://purl.org/dc/elements/1.1/"
             xmlns:mb="http://musicbrainz.org/ns/mb/1/"
             xmlns:az="http://www.amazon.com/gp/aws/landing.html#">
    <mb:album-list>
      <mb:album id="8f468f36-8c7e-4fc1-9166-50664d267127" type="album">

        <dc:title>Dummy</dc:title>
        <mb:counts track="11" cdid="10" trmid="73"/>
        <az:asin>B000001FI7</az:asin>

        <mb:artist id="8f6bd1e4-fbe1-4f50-aa9b-94c450ec0f11" begin="1991" end="2011">
          <dc:title>Portishead</dc:title>
          <mb:sortName>Portishead</mb:sortName>
        </mb:artist>

        <mb:release-list>
          <mb:release date="1994-10-17" country="us"/>
        </mb:release-list>

        <mb:cdid-list>
           <mb:cdid id="D5LsXhbWwpctL4s5xHSTS_SefQw-"/>
        </mb:cdid-list>

        <mb:track-list>
          <mb:track id="b5d7d380-f43a-4c1f-a5de-694150b093ac" duration="306200">
            <dc:title>Mysterons</dc:title>

            <!-- This block is shown only if the track artist != album artist -->
            <mb:artist id="8f6bd1e4-fbe1-4f50-aa9b-94c450ec0f11" begin="1991" end="2011" type="group">
              <dc:title>Portishead</dc:title>
              <mb:sortName>Portishead</mb:sortName>
            </mb:artist>

            <mb:trmid-list>
               <mb:trmid id="58bdde9c-9c47-487a-94ae-1e9c4001bd3d"/>
            </mb:trmid-list>

          </mb:track>
        </mb:track-list>

      </mb:album>
    </mb:album-list>
</mb:metadata>

The above XML parses and validates with the following Relax NG schema:

<?xml version="1.0" encoding="UTF-8"?>
<!--
   <hr>
   Relax NG Schema for MusicBrainz XML Metadata Version 0, draft 1

   Copyright (c) 2004 Robert Kaye
   
   The schema is released under the Creative Commons 
   Attribution-ShareAlike 2.0 license.

   http://creativecommons.org/licenses/by-sa/2.0/
   <hr>

   TODO:
     - Constrain text values and attributes
     - Add AR support
     - Add extensibility

-->
<grammar xmlns="http://relaxng.org/ns/structure/1.0"
         datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes"
         xmlns:mb="http://musicbrainz.org/ns/mb/1/"
         xmlns:dc="http://purl.org/dc/elements/1.1/"
         xmlns:az="http://www.amazon.com/gp/aws/landing.html#">

   <start>
     <ref name="metadata"/>
   </start>

   <define name="metadata">
       <element name="mb:metadata">
         <optional>
           <ref name="artist-list"/>
         </optional>
         <optional>
           <ref name="album-list"/>
         </optional>
         <optional>
           <ref name="track-list"/>
         </optional>
       </element>
   </define>

   <define name="album-list">
       <element name="mb:album-list">
           <oneOrMore>
               <ref name="album-entity"/>
           </oneOrMore>
       </element>
   </define>

   <define name="artist-list">
       <element name="mb:artist-list">
           <oneOrMore>
               <ref name="artist-entity"/>
           </oneOrMore>
       </element>
   </define>

   <define name="track-list">
       <element name="mb:track-list">
           <oneOrMore>
             <ref name="track-entity"/>
           </oneOrMore>
       </element>
   </define>

   <define name="artist-entity">
       <element name="mb:artist">
           <optional>
               <attribute name="id"/>
           </optional>
           <optional>
               <attribute name="begin"/>
           </optional>
           <optional>
               <attribute name="end"/>
           </optional>
           <optional>
               <attribute name="group"/>
           </optional>
           <optional>
               <attribute name="type"/>
           </optional>

           <element name="dc:title">
               <text/>
           </element>

           <optional>
               <element name="mb:sortName">
                   <text/>
               </element>
           </optional>
       </element>
   </define>

   <define name="album-entity">

       <element name="mb:album">
           <optional>
               <attribute name="id"/>
           </optional>
           <optional>
               <attribute name="type"/>
           </optional>
           <optional>
               <attribute name="status"/>
           </optional>

           <element name="dc:title">
               <text/>
           </element>
           <optional>
             <element name="mb:counts">
                 <optional>
                     <attribute name="track"/>
                 </optional>
                 <optional>
                     <attribute name="cdid"/>
                 </optional>
                 <optional>
                     <attribute name="trmid"/>
                 </optional>
                 <text/>
             </element>
           </optional>
           <optional>
               <element name="az:asin">
                   <text/>
               </element>
           </optional>

           <optional>
               <ref name="artist-entity"/>
           </optional>

           <zeroOrMore>
             <ref name="release-list"/>
           </zeroOrMore>

           <zeroOrMore>
             <ref name="cdid-list"/>
           </zeroOrMore>

           <optional>
             <ref name="track-list"/>
           </optional>

       </element>
   </define>

   <define name="track-entity">
       <element name="mb:track">
           <optional>
               <attribute name="id"/>
           </optional>
           <optional>
             <attribute name="duration"/>
           </optional>

           <element name="dc:title">
               <text/>
           </element>
           <optional>
             <ref name="artist-entity"/>
           </optional>
           <optional>
             <ref name="album-entity"/>
           </optional>
           <optional>
             <ref name="trmid-list"/>
           </optional>
       </element>
   </define>

   <define name="release-list">
       <element name="mb:release-list">
           <element name="mb:release">
           <optional>
               <attribute name="date"/>
           </optional>
           <optional>
               <attribute name="country"/>
           </optional>
           </element>
       </element>
   </define>

   <define name="cdid-list">
       <element name="mb:cdid-list">
           <element name="mb:cdid">
               <attribute name="id"/>
           </element>
       </element>
   </define>

   <define name="trmid-list">
       <element name="mb:trmid-list">
           <element name="mb:trmid">
               <attribute name="id"/>
           </element>
       </element>
   </define>

</grammar>