https://wiki.musicbrainz.org/api.php?action=feedcontributions&user=ThomasVanderStichele&feedformat=atomMusicBrainz Wiki - User contributions [en]2024-03-29T12:13:38ZUser contributionsMediaWiki 1.39.4https://wiki.musicbrainz.org/index.php?title=MusicBrainz_XML_Meta_Data&diff=31105MusicBrainz XML Meta Data2009-07-23T10:23:07Z<p>ThomasVanderStichele: Make it clear that XML needs to be requested with type=xml</p>
<hr />
<div>=The MusicBrainz XML Metadata Format=<br />
<br />
[[Image:Attention.png]] '''Status:''' ''Stable. No more changes to the format please, but feel free to improve the documentation.'' (eg: [[Needs Editing|NeedsEditing]]) <br />
<br />
<br />
<br />
==Introduction==<br />
<br />
The [[MusicBrainz]] XML Metadata Format (MMD) is an XML based document format to represent music metadata. It has been designed to be easy to read, powerful and extensible. MMD is the official successor of the old RDF-based metadata format, which was popular among semantic web enthusiasts, but didn't have much acceptance otherwise because of its perceived complexity. <br />
<br />
The initial and predetermined use of MMD is in the [[XML Web Service|MusicBrainz Web Service]]. However, it may be useful for other applications, too. Third party use and extensions to the format will be discussed later in this document. <br />
<br />
The official format description is a [http://www.relaxng.org/ Relax NG schema]. You can browse the schema and example documents via the [http://bugs.musicbrainz.org/browser/mmd-schema/trunk trac source browser] or access it via our [http://subversion.tigris.org subversion] repository: <br />
<br />
<code><nowiki>svn co http://svn.musicbrainz.org/mmd-schema/trunk mmd-schema</nowiki></code> <br />
<br />
Questions about MMD can be asked on either the [[IRC|IRC channel]] or posted to [[Developers Mailing List|mb-devel]]. <br />
<br />
The rest of this document is a loose collection of examples and descriptions, feel free to improve the documentation to make it a more valuable resource for developers. <br />
<br />
==Structure==<br />
<br />
All valid MMD documents are in the <code><nowiki>http://musicbrainz.org/ns/mmd-1.0#</nowiki></code> namespace. The following is a perfectly valid, but empty, MMD document: <br />
<br />
<pre><?xml version="1.0" encoding="UTF-8"?><br />
<br />
<metadata xmlns="http://musicbrainz.org/ns/mmd-1.0#"><br />
<!-- no elements --><br />
</metadata><br />
</pre><br />
<br />
The <code><nowiki>metadata</nowiki></code> element may contain one of the following elements: <code><nowiki>artist</nowiki></code>, <code><nowiki>release</nowiki></code>, <code><nowiki>track</nowiki></code>, <code><nowiki>artist-list</nowiki></code>, <code><nowiki>release-list</nowiki></code>, <code><nowiki>track-list</nowiki></code>. Although the schema permits more than one of these elements to appear as children of <code><nowiki>metadata</nowiki></code>, it usually just contains one. <br />
<br />
===The artist, release, and track elements===<br />
<br />
The <code><nowiki>artist</nowiki></code>, <code><nowiki>release</nowiki></code> and <code><nowiki>track</nowiki></code> elements represent a corresponding entity from the [[MusicBrainz]] database. This MMD document represents an artist: <br />
<br />
<pre><?xml version="1.0" encoding="UTF-8"?><br />
<br />
<metadata xmlns="http://musicbrainz.org/ns/mmd-1.0#"><br />
<artist id="c0b2500e-0cef-4130-869d-732b23ed9df5" type="Person"><br />
<name>Tori Amos</name><br />
<sort-name>Amos, Tori</sort-name><br />
<life-span begin="1963-08-22"/><br />
<release-list><br />
<!-- releases omitted --><br />
</release-list><br />
</artist><br />
</metadata><br />
</pre><br />
<br />
If there are two artists with the same name in the database, a <code><nowiki>disambiguation</nowiki></code> element can be used. It could contain the decade the artist was active, or the genre. <br />
<br />
The following document represents a release: <br />
<br />
<pre><?xml version="1.0" encoding="UTF-8"?><br />
<br />
<metadata xmlns="http://musicbrainz.org/ns/mmd-1.0#"><br />
<release id="02232360-337e-4a3f-ad20-6cdd4c34288c" type="Album Official"><br />
<title>Little Earthquakes</title><br />
<text-representation language="ENG" script="Latn"/><br />
<asin>B000002IT2</asin><br />
<artist id="c0b2500e-0cef-4130-869d-732b23ed9df5" type="Person"><br />
<name>Tori Amos</name><br />
<sort-name>Amos, Tori</sort-name><br />
<life-span begin="1963-08-22"/><br />
</artist><br />
<release-event-list><br />
<event date="1992-01-13" country="GB"/><br />
<event date="1992-01-17" country="DE"/><br />
<event date="1992-02-25" country="US"/><br />
</release-event-list><br />
<disc-list><br />
<disc id="ILKp3.bZmvoMO7wSrq1cw7WatfA-"/><br />
<disc id="ejdrdtX1ZyvCb0g6vfJejVaLIK8-"/><br />
<disc id="Y96eDQZbF4Z26Y5.Sxdbh3wGypo-"/><br />
</disc-list><br />
<track-list count="12"/><br />
</release><br />
</metadata><br />
</pre><br />
<br />
The <code><nowiki>text-representation</nowiki></code> gives the language and script the release and track titles are written in. The <code><nowiki>asin</nowiki></code> element contains an amazon shop identifier. <br />
<br />
The following MMD document describes a track: <br />
<br />
<pre><?xml version="1.0" encoding="UTF-8"?><br />
<br />
<metadata xmlns="http://musicbrainz.org/ns/mmd-1.0#"><br />
<track id="d6118046-407d-4e06-a1ba-49c399a4c42f"><br />
<title>Silent All These Years</title><br />
<duration>253466</duration><br />
<puid-list><br />
<puid id="c2a2cee5-a8ca-4f89-a092-c3e1e65ab7e6"/><br />
<puid id="db5b66b3-fa97-4cfa-9296-de7e57ef05f4"/><br />
<puid id="fbb3d1b6-f9e7-49ed-834c-03e9ec9726e5"/><br />
<puid id="0e2e66e3-13d7-4138-af90-5ec8a4c2db99"/><br />
<puid id="4778d58b-50fe-4004-8cd6-462a816114c8"/><br />
<puid id="88541d46-9b74-4835-b8e8-d985fc77e02a"/><br />
<puid id="42ab76ea-5d42-4259-85d7-e7f2c69e4485"/><br />
</puid-list><br />
</track><br />
</metadata><br />
</pre><br />
<br />
There may also be an artist element, which is left out in this example. The <code><nowiki>puid-list</nowiki></code> lists all PUIDs (audio checksums) associated with this track. <br />
<br />
===The list elements===<br />
<br />
Additional to the elements discussed in the last section, MMD supports several list elements. The <code><nowiki>metadata</nowiki></code> element may contain <code><nowiki>artist-list</nowiki></code>, <code><nowiki>release-list</nowiki></code>, and <code><nowiki>track-list</nowiki></code> elements, the <code><nowiki>release</nowiki></code> element can (among others) contain a <code><nowiki>track-list</nowiki></code> element etc. <br />
<br />
Usually, a list contains other elements. A <code><nowiki>track-list</nowiki></code> contains <code><nowiki>track</nowiki></code> elements, a <code><nowiki>puid-list</nowiki></code> contains <code><nowiki>puid</nowiki></code> elements, and so on. In some cases, it is not possible to list all elements of the list because there would be too many. In this case, the <code><nowiki>count</nowiki></code> and <code><nowiki>offset</nowiki></code> attributes can be used, which are available for all lists in MMD. The following example shows a partial artist list: <br />
<br />
<pre><?xml version="1.0" encoding="UTF-8"?><br />
<br />
<metadata xmlns="http://musicbrainz.org/ns/mmd-1.0#"><br />
<track-list count="147" offset="0"><br />
<track id="748f2b79-8c50-4581-adb1-7708118a48fc"><br />
<title>Little Earthquakes</title><br />
<duration>457760</duration><br />
<artist id="c0b2500e-0cef-4130-869d-732b23ed9df5"><br />
<name>Tori Amos</name><br />
</artist><br />
<!-- ... --><br />
</track><br />
<track id="51d2c2ff-a5fd-44f9-9c1c-7ca9fdc7dd1d"><br />
<title>Little Earthquakes</title><br />
<duration>413693</duration><br />
<artist id="c0b2500e-0cef-4130-869d-732b23ed9df5"><br />
<name>Tori Amos</name><br />
</artist><br />
<!-- ... --><br />
</track><br />
</track-list><br />
</metadata><br />
</pre><br />
<br />
The full <code><nowiki>track-list</nowiki></code> would have 147 entries (the <code><nowiki>count</nowiki></code> attribute), and this partial list starts at the first element (<code><nowiki>offset</nowiki></code> is zero-based). <br />
<br />
===Relations===<br />
<br />
Relations are the most complex part of MMD. An artist, release, or track can be in a relation to any other artist, release, track, or URL. This is how it looks like: <br />
<br />
<pre><?xml version="1.0" encoding="UTF-8"?><br />
<br />
<metadata xmlns="http://musicbrainz.org/ns/mmd-1.0#"><br />
<artist id="c0b2500e-0cef-4130-869d-732b23ed9df5" type="Person"><br />
<name>Tori Amos</name><br />
<sort-name>Amos, Tori</sort-name><br />
<life-span begin="1963-08-22"/><br />
<relation-list target-type="Artist"><br />
<relation type="MemberOfBand" target="ee361394-914f-4074-891a-3b17b0f89a37"><br />
<artist id="ee361394-914f-4074-891a-3b17b0f89a37" type="Group"><br />
<name>Y Kant Tori Read</name><br />
<sort-name>Y Kant Tori Read</sort-name><br />
</artist><br />
</relation><br />
<relation type="Married" direction="backward" target="07538f3d-81d5-4c04-923e-4542b8ac9dbc" begin="1998"><br />
<artist id="07538f3d-81d5-4c04-923e-4542b8ac9dbc" type="Person"><br />
<name>Mark Hawley</name><br />
<sort-name>Hawley, Mark</sort-name><br />
</artist><br />
</relation><br />
</relation-list><br />
<relation-list target-type="Release"><br />
<relation type="Producer" target="5201f3a4-4a9e-4980-909e-4ee3262334d0"><br />
<release id="5201f3a4-4a9e-4980-909e-4ee3262334d0" type="Album Official"><br />
<title>From the Choirgirl Hotel</title><br />
<text-representation language="ENG" script="Latn"/><br />
</release><br />
</relation><br />
<relation type="Vocal" attributes="Lead" target="44a57f0f-3de5-4e5f-a4eb-9334b4eac4f0"><br />
<release id="44a57f0f-3de5-4e5f-a4eb-9334b4eac4f0" type="Album Official"><br />
<title>Y Kant Tori Read</title><br />
</release><br />
</relation><br />
</relation-list><br />
<relation-list target-type="Track"><br />
<relation type="Performer" target="0fcae62b-906c-4e61-b036-ed9c8fe8dd57"><br />
<track id="0fcae62b-906c-4e61-b036-ed9c8fe8dd57"><br />
<title>Blue Skies (feat. Tori Amos)</title><br />
<duration>306040</duration><br />
</track><br />
</relation><br />
<relation type="Performer" target="b6f882aa-6d53-4c2a-8bf2-d358e997a087"><br />
<track id="b6f882aa-6d53-4c2a-8bf2-d358e997a087"><br />
<title>Down by the Seaside (feat. Tori Amos)</title><br />
<duration>256414</duration><br />
</track><br />
</relation><br />
</relation-list><br />
<relation-list target-type="Url"><br />
<relation type="OfficialHomepage" target="http://www.toriamos.com/"/><br />
<relation type="Wikipedia" target="http://en.wikipedia.org/wiki/Tori_Amos"/><br />
<relation type="IMDb" target="http://www.imdb.com/name/nm0002169/"/><br />
<relation type="Fanpage" target="http://www.thedent.com/index.php"/><br />
<relation type="Discography" target="http://www.yessaid.com/albums.html"/><br />
<relation type="Discography" target="http://www.hereinmyhead.com/"/><br />
</relation-list><br />
</artist><br />
</metadata><br />
</pre><br />
<br />
In the XML document above, there are four <code><nowiki>relation-list</nowiki></code> elements, each representing relations from the artist Tori Amos to a different target type (<code><nowiki>Artist</nowiki></code>, <code><nowiki>Release</nowiki></code>, <code><nowiki>Track</nowiki></code>, and <code><nowiki>Url</nowiki></code>). <br />
<br />
==IDs and Types==<br />
<br />
The IDs and types used in the XML format are URIs. To keep the transmission overhead low, all URIs in the [[MusicBrainz]] namespace may be used in their ''relative'' form. So if a track's fully qualified <code><nowiki>id</nowiki></code> is <code><nowiki>http://musicbrainz.org/track/d6118046-407d-4e06-a1ba-49c399a4c42f</nowiki></code>, it may be shortened to <code><nowiki>d6118046-407d-4e06-a1ba-49c399a4c42f</nowiki></code> in the XML. Note that this shortening is only allowed for URIs from the [[MusicBrainz]] namespace. <br />
<br />
The following rules apply to create a fully qualified URI from a relative one: <br />
* The <code><nowiki>id</nowiki></code> attributes: <br />
** artist: <code><nowiki>http://musicbrainz.org/artist/</nowiki></code>'''relative URI''' <br />
** release: <code><nowiki>http://musicbrainz.org/release/</nowiki></code>'''relative URI''' <br />
** track: <code><nowiki>http://musicbrainz.org/track/</nowiki></code>'''relative URI''' <br />
<br />
* The <code><nowiki>type</nowiki></code> attributes: <br />
** artist: <code><nowiki>http://musicbrainz.org/ns/mmd-1.0#</nowiki></code>'''relative URI''' <br />
** release: <code><nowiki>http://musicbrainz.org/ns/mmd-1.0#</nowiki></code>'''relative URI''' (for each relative URI in the list) <br />
<br />
Due to their large number, relations are in a namespace on their own to avoid clashes: <br />
* Various relation attributes: <br />
** type: <code><nowiki>http://musicbrainz.org/ns/rel-1.0#</nowiki></code>'''relative URI''' <br />
** attributes: <code><nowiki>http://musicbrainz.org/ns/rel-1.0#</nowiki></code>'''relative URI''' (for each relative URI in the list) <br />
<br />
'''Note''': Don't confuse the URIs, especially the <code><nowiki>id</nowiki></code> URIs with URLs. The URIs are just names, they should not be used to query data from the server. But they are in a permanent format which will always be valid and can easily be transformed to URLs. Example: <br />
<br />
The following is an absolute, permanent [[MusicBrainz]] artist identifier which is the preferred representation. Shorter representations may be used for storing IDs in file tags or databases. <br />
<br />
<pre> http://musicbrainz.org/artist/c0b2500e-0cef-4130-869d-732b23ed9df5<br />
</pre><br />
<br />
This one is a URL created from the URI above, using a simple transformation. It can be used to request data from the [[MusicBrainz]] server via the webservice. URLs may change over time, the URIs will not. <br />
<br />
<pre> http://musicbrainz.org/ws/1/artist/c0b2500e-0cef-4130-869d-732b23ed9df5<br />
</pre><br />
<br />
'''Note''': When requesting XML data, you should specify the type to be xml using GET parameters. Currently only type xml is supported; in the future more might be supported. For example:<br />
<br />
<pre> http://musicbrainz.org/ws/1/artist/c0b2500e-0cef-4130-869d-732b23ed9df5?type=xml<br />
</pre><br />
<br />
==Using the XML format for other applications==<br />
<br />
The XML format format uses URIs for several IDs and types. The <code><nowiki>artist</nowiki></code> element, for example, has a <code><nowiki>type</nowiki></code> attribute which accepts a URI. Users of the format may use the URIs defined by [[MusicBrainz]] or use one from their own namespace. This example uses a definition from [[MusicBrainz]]: <br />
<br />
<pre> <artist id="c0b2500e-0cef-4130-869d-732b23ed9df5" type="http://musicbrainz.org/ns/mmd-1.0#Group"/><br />
</pre><br />
<br />
If an application needs "Orchestra" as an artist type, a different namespace has to be used: <br />
<br />
<pre> <artist id="c0b2500e-0cef-4130-869d-732b23ed9df5" type="http://example.org/ext-7.2#Orchestra"/><br />
</pre><br />
<br />
This method may be used in all places where the schema accepts an anyURI datatype. As mentioned earlier, there is a special rule for all URIs defined by [[MusicBrainz]]: They may be ''relative'', as you can see in the examples above. The complete artist ids have the form <code><nowiki>http://musicbrainz.org/artist/c0b2500e-0cef-4130-869d-732b23ed9df5</nowiki></code> and the <code><nowiki>type</nowiki></code> attribute in the first example could also be written as <code><nowiki>Group</nowiki></code>, without the namespace prefix. <br />
<br />
To extend the format even further, the schema has several extension points (see <code><nowiki>def_extension</nowiki></code>) which allows adding arbitrary XML elements from a user-defined namespace. Using the mmd-namespace or no namespace at all is not permitted. There are no namespace restrictions inside that element, however, and unlimited nesting is possible, too. <br />
<br />
If your private namespace is <code><nowiki>http://example.org/ext-9.1#</nowiki></code> and you want to add data from a rating system, for example, it could be coded like this: <br />
<br />
<pre><?xml version="1.0" encoding="UTF-8"?><br />
<metadata xmlns="http://musicbrainz.org/ns/mmd-1.0#" xmlns:ext="http://example.org/ext-9.1#"><br />
<track id="d6118046-407d-4e06-a1ba-49c399a4c42f"><br />
<title>Silent All These Years</title><br />
<duration>253466</duration><br />
<ext:rating value="9"/><br />
</track><br />
</metadata><br />
</pre><br />
<br />
Even more complicated things, like nested tags are possible. Note that the <code><nowiki>em</nowiki></code> doesn't belong to the <code><nowiki>ext</nowiki></code> namespace. <br />
<br />
<pre><?xml version="1.0" encoding="UTF-8"?><br />
<metadata xmlns="http://musicbrainz.org/ns/mmd-1.0#" xmlns:ext="http://example.org/ext-9.1#"><br />
<track id="d6118046-407d-4e06-a1ba-49c399a4c42f"><br />
<title>Silent All These Years</title><br />
<duration>253466</duration><br />
<ext:annotation>This is a <em>very</em> nice song.</ext:annotation><br />
</track><br />
</metadata><br />
</pre><br />
<br />
This is still valid according to the schema, but inside the extension elements, only well-formedness can be checked. <br />
<br />
==Credits==<br />
<br />
The [[MusicBrainz]] XML Metadata Format has been designed by [[User:MatthiasFriedrich|Matthias Friedrich]] and [[User:RobertKaye|Robert Kaye]]. Most of the schema as well as the test suite have been written by [[User:MatthiasFriedrich|Matthias Friedrich]]. <br />
<br />
----<br />
<br />
<br />
<br />
==TODO==<br />
<br />
* explain type, attributes, reading direction, dates in the relations section <br />
* what else? <br />
<br />
[[Category:To Be Reviewed]] [[Category:Development]]</div>ThomasVanderStichelehttps://wiki.musicbrainz.org/index.php?title=History:RDF&diff=31104History:RDF2009-07-23T10:05:20Z<p>ThomasVanderStichele: Since the URL's without the Id give 404, there is no point in making them hyperlinks, and it just confuses the people making them think that the complete URL's are outdated.</p>
<hr />
<div>==What is RDF?==<br />
<br />
[[Image:Attention.png]] This web service format has been deprecated! For details please see [[Web Service|WebService]]. <br />
<br />
'''RDF''' ('''R'''esource '''D'''escription '''F'''ramework) is a [http://www.w3.org/RDF/ W3C standard] for describing resources. RDF itself defines how information about these resources are linked together in abstract models though there are also specifications on how to serialize these models to XML and other forms (N-Triples to name one). <br />
<br />
==How does Music Brainz use RDF?==<br />
<br />
There are two different '''views''' on the [[Metadata|MetaData]] collected in the [[MusicBrainz]] data base. One is the website and the other one is the RDF export. Using the RDF export you can access the [[Metadata|MetaData]] as XML serialized RDF which can easily be processed by programs (so they don't have to parse the web page :) ). Programs doing this at the moment are the [[MusicBrainz Tagger|MusicBrainzTagger]] and the next generation [[Picard Tagger|PicardTagger]]. They lookup the [[Metadata|MetaData]] used for tagging files only through RDF. Both use [[libmusicbrainz]] written in C which you can also use to enhance your programs with [[MusicBrainz]] [[Metadata|MetaData]] (see the [[Client HOWTO|ClientHOWTO]] for more info on how this works; if you're looking for alternatives to the C library take a look at the others developer resources in [[MusicBrainz]] [[Products]]). <br />
<br />
The format used to describe the data is called '''[[MusicBrainz]] Metadata Initiative'''. The [http://musicbrainz.org/MM/index.html documentation] about this is rather incomplete and outdated. There are changes made to the format from time to time but due to the flexibility of RDF the export stays downward compatible. Though there is no guarantee this stays the same in the future. The relatively new format AR 1.0 used to describe [[Advanced Relationships|AdvancedRelationships]] lacks some features and is very buggy at the moment so it will surely be changed a lot. <br />
<br />
==How do I access the RDF data?==<br />
<br />
That depends on what you want to lookup. In general the RDF exports are accessed as XML streams via HTTP from the web server. Some can be accessed from URLs using the GET method, some require POSTing requests to a special URL. <br />
<br />
If you browse through the artists in MB and click on the [http://musicbrainz.org/track/57ee036f-6b2c-4725-9b9e-f6151ff3c18b.html View Info] links you can find some of the links used to address RDF resources about the entities in the [[MusicBrainz]] data base. Namely they are: <br />
* The artist resource: http://musicbrainz.org/mm-2.1/artist/<Artist MB Id> <br />
* The album resource: http://musicbrainz.org/mm-2.1/album/<Album MB Id> <br />
* The track resource: http://musicbrainz.org/mm-2.1/track/<Track MB Id> <br />
<br />
Note: you can extend the results of these queries by adding the '''depth''' parameter at the end of the URL after a slash (example: [http://musicbrainz.org/mm-2.1/track/57ee036f-6b2c-4725-9b9e-f6151ff3c18b/4 http://musicbrainz.org/mm-2.1/track/57ee036f-6b2c-4725-9b9e-f6151ff3c18b/4]). <br />
<br />
Other resources that can be accessed via GET: <br />
* Information about TRM Ids: http://musicbrainz.org/mm-2.1/trmid/<TRM Id> <br />
* Artist relationships: http://musicbrainz.org/mm-2.1/artistrel/<Artist MB Id> <br />
* Album relationships: http://musicbrainz.org/mm-2.1/albumrel/<Album MB Id> <br />
* Track relationships: http://musicbrainz.org/mm-2.1/trackrel/<Track MB Id> <br />
<br />
Other queries can be performed by sending RDF requests to the server, POSTing them to the URL [http://musicbrainz.org/cgi-bin/mq_2_1.pl http://musicbrainz.org/cgi-bin/mq_2_1.pl]. These are (only the names of them): <br />
* GetCDInfo <br />
* TrackInfoFromTRMId <br />
* QuickTrackInfoFromTrackId <br />
* FindArtist <br />
* FindAlbum <br />
* FindTrack <br />
* FindDistinctTRMID <br />
* FileInfoLookup <br />
* AuthenticateQuery <br />
* SubmitTrack <br />
* SubmitTRMList <br />
<br />
Please consult the [[libmusicbrainz]] [http://users.musicbrainz.org/~luks/docs/mb_client-2.1.2/queries_8h.html documentation] for detailed info.<br />
<br />
[[Category:To Be Reviewed]] [[Category:Terminology]]</div>ThomasVanderStichele