Candidate Standard

Skip to end of metadata
Go to start of metadata
This section of the DDEX Knowledge Base contains version 1.0 of the "Letters of Direction Choreography Standard for the US Market"

1 Introduction

This standard was developed by the member organisations of the Digital Data Exchange, LLC (DDEX) and provides a uniform mechanism for a Licensor (a music publisher or an agent for such) that has acquired a Catalogue of Musical Works and/or Right Shares thereof (the Acquiring Publisher) from another Licensor (also a music publisher or an agent for such; the Relinquishing Publisher) to inform licensees such as a record company and/or DSP about the acquisition and the label/DSP to confirm that it has received information about the transfer and made suitable consequential amendments to the data contained in its systems.

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

 2.1 Introduction

An important element in the management of rights in Musical Works in the US, particularly in the context of mechanical licensing for physical and digital products is the concept of “Letters of Direction” (LoD). These documents are usually sent by new owners or administrators of Musical Works (Acquiring Publisher) to record companies and other users, notifying them of the new ownership or administration of a Catalogue of one or more Musical Works. The reason for this is that many licences, issued by owners or administrators of Musical Works, have an on-going royalty payment obligation. Therefore where the ownership or administration of one or more musical works moves from one company, usually a music publisher, to another the Letters of Direction notify the recipient that they need to change the identity of the company entitled to receive such on-going royalty payment obligations in their accounting systems.

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.

 2.2 Organisation of the Document

This DDEX Standard has six clauses. Clause 1 and 2 provide a general introduction and the scope of this standard. Clauses 3 and 4 give a set of normative references as well as terms, definitions and abbreviations that are used in this standard.

3 Normative References

 Click here to expand...

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

 4.1 Terms and Definitions

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 

A Music Publisher that has relinquished Right Shares of Musical Works, typically collated into a Catalogue, to another Music Publisher (the Acquiring Music Publisher).

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.

 4.2 Abbreviations

AMEPAutomated Message Exchange Protocol
ACAAppointed Certification Agency
AVSAllowed Value Set
BPBusiness Profile
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)

CACertification Agency
CTConformance Tester
DAWDigital Audio Workstation
DDEX

Digital Data Exchange

DSIGDigital Signature
DSPDigital Service Provider (incudes Mobile Service Providers)
DSRDigital Sales Reporting
ERNElectronic Release Notification
FTPFile Transfer Protocol (FTP specifically includes SFTP)
GRidGlobal Release Identifier
HTTPHypertext Transport Protocol  (HTTP specifically includes HTTPS)
HTTPSSecure Hypertext Transport Protocol
IECInternational Electrotechnical Commission (see iec.ch)
ISOInternational Organisation for Standardisation (see iso.org)
MIMEMultipurpose Internet Mail Extensions
MWLMusical Works Licensing
MWNMusical Works Notification
MRBV

Multi-Record-Block Variant

PCAPrivate Certification Agency
PDFPortable Document Format
RESTREpresentational State Transfer
RINRecording Information Notification
SFTPSecure FTP
SRBV

Single-Record-Block Variant

TISTerritory Information System (a CISAC Standard)
TLSTransport Layer Security
UGCUser-generated content
URLUniform Resource Locator
XMLeXtensible Markup Language
XSDXML Schema Definition
W3CWorld Wide Web Consortium (see w3c.org)
WSWeb Service

5 Letters of Direction Choreography for the US Market

 5.1 Direct Communication
 5.1.1 Core Choreography

The diagram below depicts the choreography defined by this standard.

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 LoDMessage, has ingested the information in its systems and identified the Resources and/or Releases that are affected[1]. It then wishes to confirm that it has acted in accordance with the information received and to communicate the resulting changes.

The Licensee will include all Resources and Releases that it knows are affected by the catalogue transfer.

The LoDConfirmationMessage only confirms that Works (and affected Resources and Releases) have been transferred in accordance with the LoDMessage received. The LoDConfirmationMessage is not intended to allow sending updates of the metadata about these entities.

If both parties involved agree, a Licensee may need to send multiple LoDConfirmationMessages in response to a single LoDMessage (e.g. when the process of identifying affected Resources and Releases is iterative or takes too long and an interim response is deemed necessary).

In those cases, a subsequent LoDConfirmationMessage shall include all prior information and completely replace any LoDConfirmationMessages sent earlier.

 

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.

 5.1.2 Extended Choreography

The diagram below depicts an extended choreography which makes use of subsets of two messages defined in the latest version of the Musical Work Notification as well as messages defined in this standard. In this extended choreography, each of the Musical Work Notification must contain information specifically designed to support the Letters of Direction process defined herein.

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 MusicalWorkClaimRequestMessage serves as a request for confirmation of a catalogue transfer to enable the Acquiring Music Publisher to contact relevant Licensees.

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 MusicalWorkClaimNotificationMessage serves as a confirmation of the catalogue transfer to the Acquiring Music Publisher to enable the Acquiring Music Publisher to contact relevant Licensees

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   LoDMessage and wishes to confirm the transfer with the Relinquishing Music Publisher in order to redirect any future payments and/or licence requests.

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 LoDMessage from a Licensee and wishes to confirm (or not) the catalogue of Musical Works (or Right Shares thereof) that have been transferred. 

When sent from a Relinquishing Music Publisher to a Licensee, the  LoDConfirmationMessage serves as a confirmation of the catalogue transfer to the Acquiring Music Publisher and enables the Licensee to redirect any future royalty payments or licence requests.

The LoDConfirmationMessage only confirms that Works (and affected Resources and Releases) have been transferred in accordance with the LoDMessage received. The LoDConfirmationMessage is not intended to allow sending updates of the metadata about these entities.

If both parties involved agree, a Relinquishing Music Publisher may need to send multiple LoDConfirmationMessages in response to a single LoDMessage (e.g. when the process of identifying affected Resources and Releases is iterative or takes too long and an interim response is deemed necessary).

In those cases, a subsequent LoDConfirmationMessage shall include all prior information and completely replace any LoDConfirmationMessages sent earlier.

 5.2 Communication via a Hub

In cases where share ownership changes are being communicated, the same choreographies as above apply with the following changes:
  1. A Hub shall support receiving information about ownership changes in the form of an LoDMessage or MusicalWorkClaimRequestMessage from an Acquiring Music Publisher;
  2. 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 or MusicalWorkClaimNotificationMessage), the Hub shall update its internal view of the ownership situation; and 
  3. 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 


 5.3 Disputing Letters of Directions

Letters of Directions, whether communicated directly in accordance with Clause 5.1 or via a hub in accordance with Clause 5.2, can be disputed by:
  1. 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:
    1. Reply with an Exception in the ConfirmedCatalogTransfer that uses an ExceptionReason of DisputedByLicensee and
    2. 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.
  2. 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 the LoDMessage is rejected or (b) when the Works listed in the LoDMessage are, in the view of the Relinquishing Publisher, not part of the catalogue transfer. This shall be signalled in the LoDConfirmationMessage through 
    1. A CatalogTransferException that references the identifier of the disputed catalogue or 
    2. An Exception in the ConfirmedCatalogTransfer that references the Right Share that is disputed.
    In both cases an ExceptionReason of DisputedByRelinquishingPublisher shall be used.

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.

 5.4 Scope of Message

Each 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.)

 5.5 Cover Letter for LoD Cycle (informative)

The Acquiring Music Publisher may, in addition to sending the 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.

 5.6 Communicating Resource and Release Information to Licensees
 5.6.1 Full Catalogue Transfers

When sending an 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, to false.

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.

 5.6.2 Partial Catalogue Transfers

A partial Catalogue transfer should be described either by specifying directly the Works that are part of the transfer:
  • 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, to true.

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, to true.

 5.6.3 Ingestion of a Catalogue Transfer

As part of the choreography defined herein, Licensees are requested to identify all of their current Resources (e.g. Sound Recordings or videos) and Releases that make use of works subject to the Catalogue  Transfer they have been informed about in an 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.

 

 5.7 Processes when receiving a message regarding a catalogue transfer (informative)

Relinquishing Music Publishers receiving a 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).

 5.8 SFTP Choreography
 5.8.1 Introduction

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.

 5.8.2 Folder Naming Convention

To ensure sequential processing, a Batch is identified by the date and time of its creation in the form YYYYMMDDhhmmssnnn with
  • YYYY being the year of Batch creation;
  • MM being the month of Batch creation;
  • DD being the day of Batch creation;
  • hh being the hour of Batch creation;
  • mm being the minute of Batch creation;
  • ss being the second of Batch creation; and
  • nnn being the millisecond of Batch creation.

 5.8.3 XML File Naming Convention

Each message sent in the Batch shall be named as follows:
  • 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;
  • SSSSS being a zero padded serial number within that Batch.

 5.8.4 Supporting File Naming Convention

Any document supporting a DDEX message in a Batch shall be placed into the same folder as the XML message and be named as follows: FFFF_NNNN.ext with
  1. FFFF being the file name (without extension) of the file to which supporting information is provided;
  2. NNNN being a serial number; and
  3. ext being an extension suitable to the data type (e.g. xml for an XML file or csv for a comma-separated value flat file).

 5.8.5 Manifest

Once the message sender has uploaded all files of the Batch, the sender shall upload a manifest file. The manifest file shall be called manifest.xml and shall be placed into the same folder as all other files.

Its syntax is defined in Clause 6.

 5.8.6 Acknowledgement

Once the message recipient has downloaded a file from within the Batch, the recipient shall upload an acknowledgement file. The acknowledgement file shall be called 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.

 5.8.7 Size of Batch

Each file within a Batch should contain up to 500 Musical Works. Sender and recipient may agree other limits.

The maximum number of files to be part of a Batch is not limited but may be agreed by Sender and recipient.

 5.8.8 Hybrid Batches

It is possible to place messages defined in other DDEX Choreography Standards relating to Musical Works in the same Batch as messages defined in accordance with this standard.

 5.9 Web Services Choreography
 5.9.1 Introduction

There are three approaches to communicating LoDs in the LoD Cycle and the Confi rmation Cycle:

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 Symmetric Direct Choreography

5.9.2.1 LoD Cycle

The process of symmetric communication between Acquiring Music Publisher and Licensee contains these steps:

  1. The Acquiring Music Publisher calls the Web Service endpoint published by the Licensee using the POST LoD call with an LoDMessage;  
  2. 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
  3. 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 requested LoDConfirmationMessage 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:

  1. The Licensee calls the Web Service endpoint published by the Relinquishing Music Publisher using the POST LoD call with an LoDMessage;  
  2. 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
  3. 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 requested LoDConfirmationMessage once it has assembled the information. 

5.9.2.3 Diagram

These steps are depicted below.

 

 5.9.3 Asymmetric Direct Choreography

5.9.3.1 LoD Cycle

The process of asymmetric communication between Acquiring Music Publisher and Licensee contains these steps:

  1. The Acquiring Music Publisher calls the Web Service endpoint published by the Licensee using the POST LoD call with an LoDMessage;  
  2. The Licensee replies to this call with an Acknowledgement;
  3. The Acquiring Music Publisher regularly calls the Web Service endpoint published by the Licensee using the GET LoDConfirmationList call;
  4. The Licensee replies to this with an Atom feed providing a URLs for all LoDConfirmationMessages that are ready to be collected; and
  5. 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 requested LoDConfirmationMessage.

5.9.3.2 Confirmation Cycle

The process of asymmetric communication between Licensee and  Relinquishing Music Publisher contains these steps:

  1. The Licensee calls the Web Service endpoint published by the Relinquishing Music Publisher using the POST LoD call with an LoDMessage;  
  2. The Relinquishing Music Publisher replies to this call with an Acknowledgement;
  3. The Licensee regularly calls the Web Service endpoint published by the Relinquishing Music Publisher using the GET LoDConfirmationList call;
  4. The Relinquishing Music Publisher replies to this with an Atom feed providing a URLs for all LoDConfirmationMessages that are ready to be collected; and
  5. 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 requested LoDConfirmationMessage.

5.9.3.3 Diagram

These steps are depicted below.

 

 5.9.4 Choreography via a Hub

The process of communication between Acquiring Music PublisherLicensee and Relinquishing Music Publisher via a Hub contains these steps:
  1. The Acquiring Music Publisher informs a Hub of a catalogue transfer:
    1. The Acquiring Music Publisher calls the Web Service endpoint published by the Hub using the POST LoD call with an LoDMessage;
    2. The Hub replies with an Acknowledgement;
  2. 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:
    1. The Relinquishing Music Publisher regularly calls the Web Service endpoint published by the Hub using the GET LoDList call;
    2. The Hub replies with an LoDMessage;
    3. The Relinquishing Music Publisher regularly calls the Web Service endpoint published by the Hub using the PUT LoDConfirmation cal;
    4. The Hub replies with an Acknowledgement;
  3. The Hub informs a Licensee about a catalogue transfer:
    1. The Licensee regularly calls the Web Service endpoint published by the Hub using the GET LoDList call;
    2. The Hub replies to this with an Atom feed providing a URLs for all LoDMessages that are ready to be collected;
    3. 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 requested LoDMessage.

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.

 5.9.5 URLs

The approach to Web Service-based information deliveries is based on URLs that are set at the discretion of the provider of the Web Service interface who publishes the Web Service to its business partners to share information with them.

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.

 5.9.6 Personalising the Feed

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.

 5.9.7 Web Server Set-up and Authentication

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.

 5.9.8 Identifying Web Service Callers Without Authentication

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 Web Service Commands
 5.9.9.1 POST LoD

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 POST LoDConfirmation

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 GET LoDList

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.

  1. from: Get items older than this time stamp (inclusive). The time stamp shall be provided in ISO 8601 format (yyyy-mm-dd);

  2. to: Get items newer than this time stamp (inclusive). The time stamp shall be provided in 8601 format (yyyy-mm-dd);

  3. offset: Offset into list of the first item to return; and

  4. 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 GET LoDConfirmationList

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.

  1. from: Get items older than this time stamp (inclusive). The time stamp shall be provided in ISO 8601 format (yyyy-mm-dd);

  2. to: Get items newer than this time stamp (inclusive). The time stamp shall be provided in 8601 format (yyyy-mm-dd);

  3. offset: Offset into list of the first item to return; and

  4. 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 GET LoD

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 GET LoDConfirmation

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

 6.1 Introduction

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. 

 6.2 General Conformance Rules
 6.2.1 Schema Validation

A message is conformant to this specification only when it validates against the set of XML Schema files provided.

 6.2.2 Namespace

The full namespace for the XML Schema document for this Standard is
http://ddex.net/xml/mc-us-lod/10
All messages developed within DDEX are based upon a common set of elements and their definitions. These are contained in the DDEX Data Dictionary available from kb.ddex.net.

 6.2.3 Allowed Value Lists

All messages defined in this standard make intensive use of allowed-value sets. These allowed value sets are shared between all DDEX standards and DDEX provides an XML Schema Definition file for all of these allowed values. These values are also contained in the DDEX Data Dictionary available from kb.ddex.net.
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.

 6.2.4 Contractually Mandatory

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.

 6.2.5 Character Coding

All messages shall be sent in UTF-8.

 6.3 Definition of Messages

The tabular rendering of the messages  is provided in a separate document.

 6.4 Allowed Value Sets

The table below lists all allowed value sets with their allowed values and definitions that are valid within this standard. Note, the allowed-value sets are maintained outside of this standard and DDEX may add to the list below.

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:

  1. The suitability or fitness of the standards for any particular purpose;
  2. The merchantability of the standards;
  3. The accuracy, completeness, relevance or validity of the standards; or
  4. 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.