- Created by DDEX Secretariat, last modified on 2020-08-17
Download Standard (PDF)
Download/Print standard tables (XLS)
XML Schema Definition Files (ZIP)
LoD 1.0 is a "Candidate Standard", which is a formal standard approved by DDEX for which DDEX has not had any information about live implementations. Once DDEX has received such input, it is expected that LoD 1.0 will be promoted to "DDEX Standard".
Before starting an implementation, DDEX recommends to read Starting an Implementation and Licensing DDEX Standards.
General Index
The general index contains all terms used in the latest AVS (Version 4) as well as all terms from RIN 2.0, MEAD 1.1, PIE 1.0 and RDR-N 1.5. Other standards will be added over time. Clicking on an entry in the general index will take you to the relevant edition of the DDEX Data Dictionary.
Message Editions
... for the Electronic Release Notification (ERN 4.3)
... for Recording Information Notification (RIN 2.0)
... for Media Enrichment and Description (MEAD 1.1)
... for Party Identification and Enrichment (PIE 1.0)
... for the Recording Data and Rights Notification Standard (RDR-N, Version 1.5).
Allowed Value Set Editions
... for the Allowed Value Sets (Version 4)
... for the Allowed Value Sets (Version 3)
... for the Allowed Value Sets (Version 2)
... for the Allowed Value Sets (Version 1)
Data Dictionary editions published before 2022
... for the Recording Data and Rights Choreography Standard (RDR-C, Version 1.0): Message Structure and AVSs
... for the US Letters of Direction Choreography Standard (LoD, Version 1.0): Message Structure and AVSs
... for the Electronic Release Notification Message Suite Standard (ERN, Version 4.2): Message Structure and AVSs
... for the US Musical Work Licensing Choreography Standard (MWL, Version 1.0): Message Structure and AVSs
... for the Standard for the Communication of Media Enrichment and Description Information (MEAD): Message Structure and AVSs
... for the Musical Work Right Share Notification Choreography Standard (MWN, Version 1.1)
... for the Standard for communicating links between Resources and Musical Works (Version 1.1)
... for the Recording Data and Rights Standard (Version 1.4)
... for Release Deliveries using SFTP or Web Service (Version 1.7)
... for the Recording Information Notification (Version 1.1)
1 Introduction
The standard also supports the process by which an Acquiring Publisher can confirm the list of Musical Works and/or Right Shares it has acquired, with the Licensor from which it has acquired the Musical Works and/or Right Shares. Finally, the standard enables the Licensee to confirm the Acquiring Publisher's notification with the Relinquishing Publisher.
No organisation is compelled to use this Standard and nothing contained herein imposes any obligation on any organisation, nor relieves any organisation of any obligation, which may exist under law or by agreements between business partners, whether this occurs on a bi-lateral basis or as part of any collectively negotiated procedures.
This Standard is therefore “without prejudice” to any such agreements or negotiations that might lead to the establishments of such information flows or choices of message.
Any organisation wishing to implement this (or any other DDEX Standard) is required to apply for an Implementation Licence. The terms of the licence and an application form can be found at https://ddex.net/implementation/implementation-licence-and-ddex-party-identifiers.
2 Scope
The messages and the choreography defined in this standard, together with the messages defined in the Musical Work Notification Message Suite Standard, will allow information flow about the Works themselves (including information about the sound recordings or videos as well as Releases in which they are used) as well as information about who owns and controls what shares of such works.
The use of a Letters of Direction Message defined in this standard is based on a certain number of conditions, e.g. identification of the relevant entities needs to have been done and the data shared, e.g. in a Musical Work Notification Message. If there is not enough information for creating a Letters of Direction Message, this standard should not be used.
This standard does not address the process of establishing a licence in the first place. This is defined in the US Works Licensing Choreography Standard.
Clause 5 then provides the Letters of Direction Choreography and two Message Exchange Protocols: SFTP and Web Services. Finally, Clause 6 defines the messages for the Letters of Direction Choreography.
3 Normative References
The following normative documents contain provisions, which through reference in this text constitute provisions of this Standard. For dated references, subsequent amendments to, or revisions of, any of these publications do not apply. For undated references, the latest version applies.
- DDEX Musical Works Notification and Licensing Message Suite Standard. Latest Version
- DDEX Data Dictionary Standard. Latest Version
- DDEX Party Identifier (DPID) Standard. Latest Version
- W3C. XML Schema Part 1: Structures. Second Edition. 2004
- W3C. XML Schema Part 2: Datatypes. Second Edition. 2004
4 Terms and Abbreviations
Acquiring Music Publisher
A Music Publisher that has acquired Right Shares of Musical Works, typically collated into a Catalogue, from another Music Publisher (the Relinquishing Music Publisher).
Administrator
A Party administrating Rights on behalf of one or more RightsControllers (in the context of this standard a Collecting Publisher).
Batch
A grouping of one or more DDEX Messages to be processed by the recipient together.
Catalogue
A well-defined collection of items such as rights in Musical Works, Right Shares and/or Releases.
Note that the XML tags use the spelling “catalog” instead of catalogue.
Collecting Publisher
A RightsController who is, at the time of assertion, controlling the right to collect royalties for a specific RightsType in a specific Territory for a specific Musical Work. Collecting Publishers may ask Administrators to administer some of their rights. Note that a MusicalWork may have zero, one or many Collecting publishers.
Collection Share
A Right Share as calculated for the collection of money for Right Shares. It specifies the ratio (percentage) of a composition that a rights holder is contractually entitled to collect from a Licensee, by rights type, territory, and period.
In the context of the Letters of the Direction Choreography Standard, Collection Shares are the Right Shares that are being transferred from a Relinquishing Publisher to an Acquiring Publisher.
Hub
A service that acts as a broker for information exchange, typically using DDEX Messages. In the context of the Musical Works Notification, Musical Works Licensing and Letter of Direction Standards defined by DDEX, a Hub acts as an intermediary for information exchange to facilitate sharing of Right Share information. Hubs may also play a role in facilitating licensing processes between (prospective) Licensors and (prospective) Licensees. Hubs may also act as routers and/or provide data caching functionality.
Letter of Direction
A communication from a Rights Controller who has acquired a Catalogue of rights to Licensors of said Musical Works. An Administrator may carry out the communication on behalf of a Rights Controller.
Licensee
A Party that is granted a Licence in respect of rights in one or more Creations, by a Licensor. The Licensee may be a human being or other legal person or corporate entity. The Licensee may or may not be the Message Sender or Message Recipient of a message in a specific information exchange defined by a DDEX Standard.
Licensor
A Party that grants a Licence in respect of rights in one or more Creations to one or more Licensees in accordance with the authorities it has been granted to do so by one or more Rights Controller(s), Rights Administrator(s) (where applicable), Licensing Agent(s) (where applicable) or Rights Holder(s). The Licensor may be a human being or other legal person or corporate entity. The Licensor may or may not also be the Rights Controller, the Rights Administrator, the Licensing Agent or the Rights Holder in the Creation(s) that are the subject of the Licence granting the rights. The Licensor may or may not be the Message Sender or Message Recipient of a message in a specific information exchange defined by a DDEX Standard.
Manuscript Share
The proportion of a Musical Work written by a Writer, as agreed between the Writers. Typically represented as a percentage or a fraction. Manuscript Shares may occasionally vary by territory and/or rights type.
Musical Work
A Work intended to be perceivable as a combination of sounds, with or without accompanying text.
Any words that are intended to be expressed with a MusicalWork (often termed Lyrics) form part of that MusicalWork; not all MusicalWorks have Lyrics.
A MusicalWork may be expressed and fixed to become part of a SoundRecording or a Video Recording, or may be used to create notated music (sheet music, scores, instrumental parts) or sound generation codes (such as MIDI files).
In some cases, the MusicalWork comes into existence simultaneously with its expression. This is common in extemporised forms such as jazz music.
Original Publisher
A RightsController who is assigned rights directly by the Writer (as opposed to by another Publisher). Note that a writer may have zero, one or many Original Publishers.
Original Publisher Share
The proportion of the overall Musical Work that a writer has assigned to an Original Publisher. Note that each Writer can have zero, one or many Original Publishers, and hence zero, one or many Original Publisher Shares. As opposed to collection shares, an OriginalPublisherShare does not define a share for the collection of money.
Release
A Release is an abstract entity representing a bundle of one or more Resources compiled by an Issuer. The Resources in Releases are normally primarily sound recordings or music audio-visual recordings, but this is not invariably the case. The Release is not itself the item of trade (or “Product”). Products have more extensive attributes than Releases; one Release may be disseminated in many different Products.
Relinquishing Music Publisher
The label (i.e. the brand under which a Release and/or Resource is issued and marketed) in whose catalogue the transferred Catalogue appeared before the Catalogue Transfer.
Right Share
A percentage or fraction of a right for a Musical Work for a particular time and place in which a party claims a controlling interest. Note: controlling interest includes ownership and/or administration.
Rights Controller
A Party that controls rights in one or more Creations in respect of some or all rights for specific territories, time periods, Rights Types, Usage Types and Commercial Model Types (which may be anything up to and including all rights for the world, in perpetuity, for all types of Usage and for all types of Commercial Models). Creations include Musical Works, Sound Recordings and other Resources as well as Releases.
A Rights Controller is in many cases also the Licensor.
A Rights Controller may be a human being or other legal person or corporate entity.
A Rights Controller may or may not also be the Rights Administrator, the Licensing Agent or the Rights Holder.
A Rights Controller may or may not be the Message Sender or Message Recipient of a message in a specific information exchange defined by a DDEX Standard.
Sound Recording
An audible persistent manifestation of a subject (often but not necessarily of a performance).
Web Service
A modern set of web technologies that allow small pieces of information, typically in the form of XML files, to be exchanged. Augmented with FTP (or other file exchange mechanisms) they can be used to communicate Releases along the music supply chain.
Web Service Call
The sending of an XML document to a port/address on a web server, using HTTP or HTTPS.
Web Service Response
The sending of an XML document in direct response to a Web Service Call, using HTTP or HTTPS.
For the avoidance of doubt: the appropriate response is always the message indicated in the appropriate Choreography.
Writer
A creative creator of the musical or lyrical elements of a Musical Work. Writers include Adapters, Arrangers, Authors, Composers. ComposerLyricists, Librettists, Lyricists, NonLyricAuthors and Translators.
Writer Share
See Manuscript Share.
AMEP | Automated Message Exchange Protocol |
ACA | Appointed Certification Agency |
AVS | Allowed Value Set |
BP | Business Profile |
BWARM | Bulk Communication of Work and Recording Metadata |
CISAC | Confédération internationale des sociétés d'auteurs et compositeurs, the International Confederation of Societies of Authors and Composers (see cisac.org) |
CA | Certification Agency |
CT | Conformance Tester |
DAW | Digital Audio Workstation |
DDEX | Digital Data Exchange |
DSIG | Digital Signature |
DSP | Digital Service Provider (incudes Mobile Service Providers) |
DSR | Digital Sales Reporting |
ERN | Electronic Release Notification |
FTP | File Transfer Protocol (FTP specifically includes SFTP) |
GRid | Global Release Identifier |
HTTP | Hypertext Transport Protocol (HTTP specifically includes HTTPS) |
HTTPS | Secure Hypertext Transport Protocol |
IEC | International Electrotechnical Commission (see iec.ch) |
ISO | International Organisation for Standardisation (see iso.org) |
MEAD | Media Enrichment And Description |
MIME | Multipurpose Internet Mail Extensions |
MWL | Musical Works Licensing |
MWN | Musical Works Notification |
MRBV | Multi-Record-Block Variant |
PCA | Private Certification Agency |
Portable Document Format | |
PIE | Party Identification and Enrichment |
REST | REpresentational State Transfer |
RIN | Recording Information Notification |
SFTP | Secure FTP |
SRBV | Single-Record-Block Variant |
TIS | Territory Information System (a CISAC Standard) |
TLS | Transport Layer Security |
UGC | User-generated content |
URL | Uniform Resource Locator |
XML | eXtensible Markup Language |
XSD | XML Schema Definition |
W3C | World Wide Web Consortium (see w3c.org) |
WS | Web Service |
5 Letters of Direction Choreography for the US Market
Figure 1 – Core Choreography of the US Letters of Direction Choreography Standard
Table 1: Messages and Triggers in the core choreography of the US Letters of Direction Choreography Standard
Message Name | Initiating Event | |
1 | LoDMessage | A Works Licensor who has acquired a catalogue of Musical Works (or Right Shares thereof) and who may have confirmed the details with the Relinquishing Music Publisher wishes to inform the Licensee about the catalogue transfer. The Acquiring Music Publisher will include a set of Resources and/or Releases that it knows are affected by the catalogue transfer. |
2 | LoDConfirmationMessage | A Licensee has received a Letter of Direction in the form of an The Licensee will include all Resources and Releases that it knows are affected by the catalogue transfer. The If both parties involved agree, a Licensee may need to send multiple In those cases, a subsequent |
Table 2: Messages and Triggers in the US Letters of Direction Choreography Standard (Helper Messages)
Message Name | Initiating Event | |
ManifestMessage | A party has finished collating messages in accordance with this standard into a Batch and wishes its business partner to commence ingesting it. | |
| FtpAcknowledgement-Message | A party receives a Batch of messages in accordance with this standard. The party then acknowledges receipt of the Batch/each message (not agreement with its content). |
[1] The implementation of the LoD information in the Licensee’s system may lead to the finding of additional Works that the Acquiring Music Publisher did not communicate. If the Licensee wishes to send this information to the Acquiring Music Publisher, this should be managed outside of the current LoD choreography.
Note that some of the messages are used in different contexts and, thus, convey differing semantics. The figure below does not show the use of the Manifest message.
Figure 2 – Extended Choreography of the US Letters of Direction Choreography Standard
The tables below summarise the points in the three cycles of the Letters of Direction Choreography when each message is sent in addition to the messages of the core choreography discussed in Clause 5.1.1 (messages (3) and (4) in the above Figure 2).
Table 3 : Messages and Triggers in the Identification Cycle of the US Letters of Direction Choreography Standard
Message Name | Initiating Event | Note | |
1 | MusicalWorkClaim-RequestMessage | A Works Licensor who has acquired a catalogue of Musical Works (or Right Shares thereof) wishes to request, from the Relinquishing Music Publisher, confirmation of the catalogue and information regarding Resources and/or Releases that make use of any transferred Musical Works or Right Shares thereof. When sent by an Acquiring Music Publisher, the | The Identification Cycle is optional and may be effected by other means such as a simple email exchange. |
2 | MusicalWorkClaim-NotificationMessage | The Relinquishing Music Publisher wishes to confirm (or not) the catalogue of Musical Works (or Right Shares thereof) that have been transferred to an Acquiring Music Publisher. The Relinquishing Music Publisher also wishes to inform the Acquiring Music Publisher about Resources and/or Releases that make use of any transferred Musical Works or Right Shares thereof. When sent from a Relinquishing Music Publisher to an Acquiring Music Publisher, the The Relinquishing Music Publisher shall include all Resources and Releases that it knows are affected by the catalogue transfer. |
Table 4 : Messages and Triggers in the Confirmation Cycle of the US Letters of Direction Choreography Standard
Message Name | Initiating Event | Note | |
5 | LoDMessage | A Licensee has received an | The Confirmation Cycle is optional and may be effected by other means such as a simple email exchange. |
6 | LoDConfirmationMessage | A Works Licensor who has relinquished a catalogue of Musical Works (or Right Shares thereof) receives an When sent from a Relinquishing Music Publisher to a Licensee, the The If both parties involved agree, a Relinquishing Music Publisher may need to send multiple In those cases, a subsequent |
- A Hub shall support receiving information about ownership changes in the form of an
LoDMessage
orMusicalWorkClaimRequestMessage
from an Acquiring Music Publisher; - Once a Hub has received a confirmation of such a change in ownership by the relevant Relinquishing Music Publisher (e.g. in the form of an
LoDConfirmationMessage
orMusicalWorkClaimNotificationMessage
), the Hub shall update its internal view of the ownership situation; and - As a consequence, the Hub shall forward all received changes of ownership received to those companies who have, in the past, requested ownership information for the same Work or Share using the
LoDMessage
.
The diagram below depicts the Core Choreography via a Hub.
Figure 3 – Hub-based Core Choreography of the US Letters of Direction Choreography Standard
- A Licensee — e.g. when the transferred Right Share percentage exceeds the share the Licensee has allocated to the Relinquishing Publisher in its systems. In that case the Licensee shall:
- Reply with an
Exception
in theConfirmedCatalogTransfer
that uses anExceptionReason
ofDisputedByLicensee
and - Seek a complete and current share picture from all Rights Controllers with an interest in the relevant Musical Work(s) by sending
MusicalWorkClaimRequestMessages
, as defined in the Musical Work Right Share Notification Choreography Standard.
- Reply with an
- A Relinquishing Publisher when the
LoDConfirmationMessage
is used in the Confirmation Cycle of the Extended Choreography described in Figure 2 (Clause 5.1.2) — e.g. (a) when the inclusion of a whole catalogue in the transfer documented in theLoDMessage
is rejected or (b) when the Works listed in theLoDMessage
are, in the view of the Relinquishing Publisher, not part of the catalogue transfer. This shall be signalled in theLoDConfirmationMessage
through- A
CatalogTransferException
that references the identifier of the disputed catalogue or - An
Exception
in theConfirmedCatalogTransfer
that references the Right Share that is disputed.
ExceptionReason
ofDisputedByRelinquishingPublisher
shall be used. - A
In addition, it may be that a Licensee cannot find, for a specific Work that is part of a catalogue transfer, any recordings or Releases in its systems. In that case the Licensee shall use the ExceptionReason
of NotFound
to signal this fact to the Acquiring Publisher.
In the case of a communication via a hub, the hub shall forward the ExceptionReasons
it has received to the Acquiring Publisher.
LoDMessage
shall only be with respect to one catalogue being transferred from one Relinquishing Music Publisher to one Acquiring Music Publisher. This is done using the CatalogTransfer
composite.However, a single LoDMessage
may be used to convey multiple CatalogTransfer
composites for:
- Catalogue transfers initiated by a collective rights management organisation on behalf of multiple licensors;
- Joint catalogue transfers for a set of Musical Works that were jointly controlled by a set of Relinquishing Music Publishers to one Acquiring Music Publisher; and
- Other similar cases
In these cases multiple CatalogTransfer
composites should be sent in a single LoDMessage
. (Note: it is not possible to communicate multiple Relinquishing Music Publishers for a catalogue being transferred; therefore, a catalogue transfer involving several publishers has to be communicated using multiple CatalogTransfer
composites.)
LoDMessage
(number 3 in Figure 2 of Clause 5.1.2), also send a document to the Licensee. This document may serve as a legally binding notification and would typically not include any Work/Share/Resource/Release details. This letter may accompany the LoDMessage
by referencing it in the SupplementalDocument
tag within the Condition
composite.
LoDMessage,
an Acquiring Music Publisher can specify if a Catalogue is transferred fully (i.e. all of the Works) or partially (i.e. only sub-set of the Works). The transfer of a full Catalogue should be described by:- Communicating the commonly used name of the Catalogue;
- Listing all the Right Shares for all the Works;
- And setting the
IsPartial
flag, which tells the Licensee that it is a full Catalogue transfer, tofalse
.
Although the Acquiring Music Publisher should specify all the Right Shares, it may be possible that the list is not complete as the Acquiring Music Publisher may not have all the relevant data. Therefore, the recipient is expected to look for more data in their systems and would possibly find additional Right Shares that are in the same Catalogue, but that the Acquiring Music Publisher didn’t have in their system.
Setting the IsPartial
flag to false
tells the recipient that the transfer is meant to be for a full Catalogue. This is therefore a means to trigger, and facilitate communication on, research the recipient will need to do to confirm the matching.
The same applies to full Catalogue Transfers received from a central hub.
- Communicating the commonly used name of that Catalogue;
- Listing all the Right Shares for the Works that are part of the transfer;
- And setting the
IsPartial
flag, which tells the Licensee that it is a full Catalogue transfer, totrue
.
or by specifying them indirectly:
- Communicating the commonly used name of that Catalogue;
- Listing all the Right Shares for all the Works;
- Listing all the Resources and/or Releases that define the Works that are part of the transfer (i.e. Works not used in any of the Resources and/or Releases would not be part of the transfer);
- And setting the
IsPartial
flag, which tells the Licensee that it is a full Catalogue transfer, totrue
.
LoDMessage
. In the LoDConfirmationMessage
they are requested to supply a complete list of these Resources and Releases to the Acquiring Music Publisher. Licensees will, however, only be able to do this reliably if they receive all available data to help identify the affected works (using Work identifiers, Work contributors such as Writers and Catalogue names), accompanied by at least some of the existing Resources or Releases that have made use of the Work. Such Resource and Release information should be made available to the Licensee in the LoDMessage,
but there is no obligation to provide a complete list of Resources or Releases.
If a Licensee does not receive such information, its efforts to identify affected Releases and/or Resources would be significantly impeded which may mean that the Acquiring Music Publisher may not be able to update its internal works and royalty databases in a timely manner.
It is recognised that an Acquiring Music Publisher would typically only know about such Resources or Releases when being informed by the Relinquishing Music Publishers. Publishers are therefore strongly encouraged to share not only Work and RightShare information but also information regarding related Resources and Releases with one another when agreeing/administering the transfer of a Catalogue.
In cases where the Acquiring Music Publisher is unable to collate sufficient information regarding Resources or Releases affected by a Catalogue transfer, the Acquiring Music Publisher should send an alternative computer-readable format containing all available information to the Licensee outside of the DDEX message choreography in order to help to facilitate any manual research that will need to be done by the Licensee.
MusicalWorkClaimRequestMessage
in the Identification Cycle (and, to a lesser degree an LoDMessage
in the Confirmation Cycle) as well as Licensees receiving an LoDMessage
in the LoD Cycle will need to match the received information to the data they have stored in their internal databases.Upon receiving the DDEX message, the recipient would attempt to automatically match the entities contained in the message (i.e. Writers, publishers, Works, resources and Releases) to the data in their system.
All data not matched successfully, data matched with too low a confidence or information provided in a computer-readable report as discussed in the previous sub-clause, will then need to be presented to human staff for manual matching.
Once both matching stages are completed, a comprehensive response message in accordance with Tables 1-4 should be sent. (Actually, the standard allows to send a response message after the automatic matching, indicating which works have been processed and which require more work).
It is anticipated that, over time, the percentage of entities being automatically matched will increase, providing a significant increase in efficiency over today’s processes. In the early stages of use of this standard, however, it can be expected that a substantial proportion of entities will need to be manually matched and processed. During that stage the main benefit of the DDEX standards lies in a uniform method of exchanging the data.
As described in Clause 5.6.1, a Licensee, when looking for matching data in their systems, could potentially find additional Right Shares that are in the same Catalogue, but that the Acquiring Music Publisher did not include in the LoDMessage
. In this case the additional Works should be communicated to the Acquiring Music Publisher using a MusicalWorkClaimRequestMessage
defined in the Musical Work Right Share Notification Choreography Standard. This MusicalWorkClaimRequestMessage
should be included in the Batch and referenced in the ManifestMessage
and in the LoDConfirmationMessage
(in the ConfirmedCatalogTransfer/MusicalWorkClaimRequestMessageId
element).
The exchange of messages defined in this standard shall use the SFTP using the naming convention defined in this Clause.
The arrival of the Batch on the SFTP server shall be signified by placing a Manifest file at the appropriate location. The Manifest shall refer, indirectly or indirectly to all files that are part of the Batch. The Manifest may only be placed on the SFTP server, once all other files have been completely uploaded.
YYYYMMDDhhmmssnnn
with
RRRR_SSSSS.xml
with- “ID_Req” for the
MusicalWorkClaimRequestMessage
in the Identification Cycle; - “ID_Notif” for the
MusicalWorkClaimNotificationMessage
in the Identification Cycle; - “LoD_LoD” for the
LoDMessage
in the LoD Cycle that serves as the Letter of Direction; - “LoD_Conf” for the
LoDConfirmationMessage
in the LoD Cycle; - “Conf_LoD” for the
LoDMessage
that serves as confirmation in the Confirmaton Cycle; - “Conf_Conf” for the
LoDConfirmationMessage
in the Confirmation Cycle;
- “ID_Req” for the
SSSSS
being a zero padded serial number within that Batch.
FFFF_NNNN.ext
withFFFF
being the file name (without extension) of the file to which supporting information is provided;NNNN
being a serial number; andext
being an extension suitable to the data type (e.g.xml
for an XML file orcsv
for a comma-separated value flat file).
ACK_FFFF.xml
with FFFF
being the file name (without extension) of the message acknowledged.The acknowledgement shall be placed into the same folder as the acknowledged file. Its syntax is defined in Clause 6.
The maximum number of files to be part of a Batch is not limited but may be agreed by Sender and recipient.
- Asymmetric direct, where only one party needs to publish and maintain a Web Service and where the other party will need call these Web Services and thus initiate the communication. Depending on the cycle, this can be:
- In the LoD Cycle: the Licensee's Web Service which is called by the Acquiring Music Publisher;
- In the Confi rmation Cycle: the Relinquishing Music Publisher's Web Service which is called by the Licensee;
- Symmetric direct where both the parties publish and maintain a Web Service to support both cycles; and
- Indirect via a Hub.
They are described below.
Please note that this standard does not define the Web Service Choreography to exchange messages in the Identification Cycle as this is defined in the Musical Work Rights Share Notification Choreography Standard.
5.9.2.1 LoD Cycle
The process of symmetric communication between Acquiring Music Publisher and Licensee contains these steps:
- The Acquiring Music Publisher calls the Web Service endpoint published by the Licensee using the
POST LoD
call with anLoDMessage
; - The Licensee replies to this call with an
LoDConfirmationMessage
(if it has all information available – not shown in the diagram) or a HTTP status code which informs the Acquiring Music Publisher that the information will be provided at a later stage; and - For each LoD Message that has not been able to be fulfilled immediately, the Licensee can call the Acquiring Music Publisher's
POST LoDConfirmation
Web Service endpoint with the requestedLoDConfirmationMessage
once it has assembled the information.
5.9.2.2 Confirmation Cycle
The process of symmetric communication between Licensee and Relinquishing Music Publisher contains these steps:
- The Licensee calls the Web Service endpoint published by the Relinquishing Music Publisher using the
POST LoD
call with anLoDMessage
; - The Relinquishing Music Publisher replies to this call with an
LoDConfirmationMessage
(if it has all information available – not shown in the diagram) or a HTTP status code which informs the Licensee that the information will be provided at a later stage; and - For each LoD Message that has not been able to be fulfilled immediately, the Relinquishing Music Publisher can call the Licensee's
POST LoDConfirmation
Web Service endpoint with the requestedLoDConfirmationMessage
once it has assembled the information.
5.9.2.3 Diagram
These steps are depicted below.
5.9.3.1 LoD Cycle
The process of asymmetric communication between Acquiring Music Publisher and Licensee contains these steps:
- The Acquiring Music Publisher calls the Web Service endpoint published by the Licensee using the
POST LoD
call with anLoDMessage
; - The Licensee replies to this call with an Acknowledgement;
- The Acquiring Music Publisher regularly calls the Web Service endpoint published by the Licensee using the
GET LoDConfirmationList
call; - The Licensee replies to this with an Atom feed providing a URLs for all LoDConfirmationMessages that are ready to be collected; and
- The Acquiring Music Publisher can then call the Licensee's
GET LoDConfirmation
Web Service endpoint for each URL provided in Step 4 to which the Licensee will respond with the requestedLoDConfirmationMessage
.
5.9.3.2 Confirmation Cycle
The process of asymmetric communication between Licensee and Relinquishing Music Publisher contains these steps:
- The Licensee calls the Web Service endpoint published by the Relinquishing Music Publisher using the
POST LoD
call with anLoDMessage
; - The Relinquishing Music Publisher replies to this call with an Acknowledgement;
- The Licensee regularly calls the Web Service endpoint published by the Relinquishing Music Publisher using the
GET LoDConfirmationList
call; - The Relinquishing Music Publisher replies to this with an Atom feed providing a URLs for all LoDConfirmationMessages that are ready to be collected; and
- The Licensee can then call the Relinquishing Music Publisher's
GET LoDConfirmation
Web Service endpoint for each URL provided in Step 4 to which the Relinquishing Music Publisher will respond with the requestedLoDConfirmationMessage
.
5.9.3.3 Diagram
These steps are depicted below.
- The Acquiring Music Publisher informs a Hub of a catalogue transfer:
- The Acquiring Music Publisher calls the Web Service endpoint published by the Hub using the
POST LoD
call with anLoDMessage
; - The Hub replies with an Acknowledgement;
- The Acquiring Music Publisher calls the Web Service endpoint published by the Hub using the
- The Relinquishing Music Publisher can confirm a Hub of a catalogue transfer proactively (as per Steps 1a and 1b above) or via the Hub requesting the information:
- The Relinquishing Music Publisher regularly calls the Web Service endpoint published by the Hub using the
GET LoDList
call; - The Hub replies with an
LoDMessage
; - The Relinquishing Music Publisher regularly calls the Web Service endpoint published by the Hub using the
PUT LoDConfirmation
cal; - The Hub replies with an Acknowledgement;
- The Relinquishing Music Publisher regularly calls the Web Service endpoint published by the Hub using the
- The Hub informs a Licensee about a catalogue transfer:
- The Licensee regularly calls the Web Service endpoint published by the Hub using the
GET LoDList
call; - The Hub replies to this with an Atom feed providing a URLs for all
LoDMessages
that are ready to be collected; - The Licensee can then call the Hub's
GET LoD
Web Service endpoint for each URL provided in Step 4 to which the Hub will respond with the requestedLoDMessage
.
- The Licensee regularly calls the Web Service endpoint published by the Hub using the
A Hub may wish to use one Web Service endpoint for the GET LoDList
calls defined above and the GET ClaimRequestList
and GET ClaimNotificationList
calls defined in the Musical Work Right Share Notification Choreography Standard.
These steps are depicted below.
While it can be assumed that many URLs follow a common syntax there is no compulsion to use this approach. Similarly it is not compulsory that all URLs from a particular Web Service provider follow a common syntax.
All a company that wishes to offer a Web Service in accordance with this standard has to do, is to publish the URL for the relevant Web Service end points to its business partner(s) and make sure that the URLs placed in the responses to Web Service Calls are (i) valid and (ii) active.
Wherever this standard only mentions the HTTP protocol, it is to be understood to allow HTTPS communications.
For companies that wish to receive or send licences it is often essential that the web server of a company knows who is calling one of its web services. This can be done with or without formal authentication (see the next two sub-clauses). The benefit of using formal authentication is that it also allows to make the information exchange secure.
This standard does not define an authentication mechanism for the Web Service-based communication between companies. Should the two parties require their communication to be authenticated, they are free to use any of the existing web-based authentication methods including, but not limited to, Basic Auth, HTTP Digest Authentication, HTTPS Client Authentication, OAUTH, etc.
Establishing the identity of the caller of the Web Service can also be accomplished without formal authentication (although in that case the web service cannot be certain that the caller is who it claims to be) by including, for instance, the DDEX Party Identifier (DPID) of the web service caller into the URL syntax.
5.9.9.1.1 Purpose
This command can be used by a company to provide an LoDMessage
to a business partner.
The company will call, after appropriate authentication if needed, the Web Service address previously agreed between the business partners with an LoDMessage.
5.9.9.1.2 Syntax of Reply
The Web Service shall return one of the following standard HTTP status codes with their standard HTTP response code semantics:
- 200 (OK);
- 400 (Bad request);
- 401 (Unauthorised);
- 404 (Not found);
- 503 (Service unavailable due to a temporary overloading or maintenance of the server); and
- 500 (Internal server error)
Other standard HTTP status codes may be used on bilateral agreement between the business partners.
5.9.9.2.1 Purpose
This command can be used by a company to provide an LoDConfirmationMessage
to a business partner.
The company will call, after appropriate authentication if needed, the Web Service address previously agreed between the business partners with an LoDConfirmationMessage.
5.9.9.2.2 Syntax of Reply
The Web Service shall return one of the following standard HTTP status codes with their standard HTTP response code semantics:
- 200 (OK);
- 400 (Bad request);
- 401 (Unauthorised);
- 404 (Not found);
- 503 (Service unavailable due to a temporary overloading or maintenance of the server); and
- 500 (Internal server error)
Other standard HTTP status codes may be used on bilateral agreement between the business partners.
5.9.9.3.1 Purpose
This command can be used by a company to request a list of LoDMessages
from a business partner.
The company will call, after appropriate authentication if needed, the Web Service address previously agreed between the business partners.
5.9.9.3.2 Parameters
In order to allow the web service caller to request a specific list of items to be returned in response to this call, the web server shall support the following query syntax defined in RfC 3986. It is permissible to communicate multiple queries separated by ampersands (&). If multiple queries are provided they shall be deemed to be logically AND-combined.
from: Get items older than this time stamp (inclusive). The time stamp shall be provided in ISO 8601 format (yyyy-mm-dd);
to: Get items newer than this time stamp (inclusive). The time stamp shall be provided in 8601 format (yyyy-mm-dd);
offset: Offset into list of the first item to return; and
limit: Maximum number of items to return. If the limit is set to 0 it means "all" items.
The example below requests an Atom feed containing 10 entries starting from the 100th item generated in January 2016:
Other query formats may be used on bilateral agreement between between the business partners.
The GET LoDList
command may also be used without any parameters. In that case the web server will decide the items to send in the Atom feed.
5.9.9.3.3 Syntax of Reply
The web server shall return one of the following standard HTTP status codes with their standard HTTP response code semantics:
- 200 (OK);
- 400 (Bad request);
- 401 (Unauthorised);
- 404 (Not found);
- 406 (Not Acceptable query);
- 414 (Request-URI Too Long);
- 503 (Service unavailable due to a temporary overloading or maintenance of the server); and
- 500 (Internal server error)
Other standard HTTP status codes may be used on bilateral agreement between between the business partners.
The web server shall also return to the calling web service client an Atom feed document that meets any parameters (if provided) as defined elsewhere in this standard.
5.9.9.4.1 Purpose
This command can be used by a company to request a list of LoDConfirmationMessages
from a business partner.
The company will call, after appropriate authentication if needed, the Web Service address previously agreed between the business partners.
5.9.9.4.2 Parameters
In order to allow the web service caller to request a specific list of items to be returned in response to this call, the web server shall support the following query syntax defined in RfC 3986. It is permissible to communicate multiple queries separated by ampersands (&). If multiple queries are provided they shall be deemed to be logically AND-combined.
from: Get items older than this time stamp (inclusive). The time stamp shall be provided in ISO 8601 format (yyyy-mm-dd);
to: Get items newer than this time stamp (inclusive). The time stamp shall be provided in 8601 format (yyyy-mm-dd);
offset: Offset into list of the first item to return; and
limit: Maximum number of items to return. If the limit is set to 0 it means "all" items.
The example below requests an Atom feed containing 10 entries starting from the 100th item generated in January 2016:
Other query formats may be used on bilateral agreement between between the business partners.
The GET LoDConfirmationList
command may also be used without any parameters. In that case the web server will decide the items to send in the Atom feed.
5.9.9.4.3 Syntax of Reply
The web server shall return one of the following standard HTTP status codes with their standard HTTP response code semantics:
- 200 (OK);
- 400 (Bad request);
- 401 (Unauthorised);
- 404 (Not found);
- 406 (Not Acceptable query);
- 414 (Request-URI Too Long);
- 503 (Service unavailable due to a temporary overloading or maintenance of the server); and
- 500 (Internal server error)
Other standard HTTP status codes may be used on bilateral agreement between between the business partners.
The web server shall also return to the calling web service client an Atom feed document that meets any parameters (if provided) as defined elsewhere in this standard.
5.9.9.5.1 Purpose
This command can be used by a company to request a licence or licence renovation from a business partner.
The company will call, after appropriate authentication if needed, a Web Service address provided in response to a GET LoDList
call.
5.9.9.5.2 Syntax of Reply
The web server shall return one of the following standard HTTP status codes with their standard HTTP response code semantics:
- 200 (OK);
- 202 (Request accepted);
- 400 (Bad request);
- 401 (Unauthorised);
- 404 (Not found);
- 503 (Service unavailable due to a temporary overloading or maintenance of the server); and
- 500 (Internal server error)
Other standard HTTP status codes may be used on bilateral agreement between the business partners.
If the HTTP status codes is 200, the Web Service shall also return to the calling web service client an XML document containing a valid LoDMessage.
5.9.9.6.1 Purpose
This command can be used by a company to request a licence or licence renovation from a business partner.
The company will call, after appropriate authentication if needed, a Web Service address provided in response to a GET LoDConfirmationList
call.
5.9.9.6.2 Syntax of Reply
The web server shall return one of the following standard HTTP status codes with their standard HTTP response code semantics:
- 200 (OK);
- 202 (Request accepted);
- 400 (Bad request);
- 401 (Unauthorised);
- 404 (Not found);
- 503 (Service unavailable due to a temporary overloading or maintenance of the server); and
- 500 (Internal server error)
Other standard HTTP status codes may be used on bilateral agreement between the business partners.
If the HTTP status codes is 200, the Web Service shall also return to the calling web service client an XML document containing a valid LoDConfirmationMessage.
6 Message Definition
The hierarchical structure of the messages is provided through indentation in the tables below. In addition to the tabular description of the message, which should always be read in conjunction with Annex A, additional conformance rules, which go beyond XML Schema validation, are provided where necessary. The general conformance rules for all messages within this Standard are provided in Clause 6.2.
Specific business processes between sender and recipient may require even further conformance rules. These are, however, not part of the Standard and will need to be agreed by the business partners.
A message is conformant to this specification only when it validates against the set of XML Schema files provided.
http://ddex.net/xml/mc-us-lod/10
http://ddex.net/xml/avs/avs
The full namespace for the XML Schema document for the allowed-value sets is:
DDEX may regularly extend this list of allowed-value sets. Any such extensions to this list issued on a date later than the date on which this standard is issued form part of this standard. This clause contains the list of allowed-value sets valid on the date of issuance of this standard.
The messages defined in this standard contain fields with cardinality “0-1” or “0-n”. Therefore these fields are from the standard’s point of view, optional. Such fields may, however, be mandatory when a DDEX message is sent in a specific commercial context.
In such circumstances, a message is deemed conformant only if and when it contains all the “contractually mandatory” fields as agreed by MessageSender
and MessageRecipient.
All messages shall be sent in UTF-8.
The tabular rendering of the messages is provided in a separate document.
The Table of AVSs is provided in a separate document.
Evaluation Licence for DDEX Standards
Subject to your compliance with the terms and conditions of this Agreement, DDEX™ grants you a limited, nonexclusive, non-transferable, non-sublicenseable, royalty-free licence solely to reproduce, distribute within your organisation, and use the DDEX standard specifications (“DDEX Standards”) solely for the purpose of your internal evaluation. You may not make any commercial use of the DDEX Standards under this agreement. No other licences are granted under this agreement.
No representations or warranties (either express or implied) are made or offered by DDEX with regard to the DDEX Standards. In particular, but without limitation, no representations or warranties are made in relation to:
- The suitability or fitness of the standards for any particular purpose;
- The merchantability of the standards;
- The accuracy, completeness, relevance or validity of the standards; or
- The non-infringement of any third party intellectual property rights related to the DDEX Standards.
Accordingly, DDEX and/or its members shall not be liable for any direct, indirect, special, consequential or punitive loss or damages howsoever arising out of or in connection with the use of the standards. IN THE EVENT THAT ANY COURT OF COMPETENT JURISDICTION RENDERS JUDGEMENT AGAINST DDEX AND/OR ITS MEMBERS NOTWITHSTANDING THE ABOVE LIMITATION, THE AGGREGATE LIABILITY TO YOU IN CONNECTION WITH THIS AGREEMENT SHALL IN NO EVENT EXCEED THE AMOUNT OF ONE HUNDRED U.S. DOLLARS (US$ 100.00).
Users of the DDEX Standards are cautioned that it is subject to revision. Users are recommended to use the latest versions, which are available at http://www.ddex.net. The use of outdated versions of the standards is not recommended but may be required by agreement between implementers in particular cases.