JSON Specification

SECTION

DESCRIPTION

Sub Objects

Ref

REQ?

Album

releaseId

2.21

Y

action

2.22

Y

upc

2.23

Y

grid

2.24

N

type

2.25

Y

title

display

2.26

Y

language

artistId

2.27

Y

artistName

display

2.28

Y

language

genre

genreName

2.29

N

subGenreName

contributors

id

2.69

N

role

name

discCount

2.30

Y

trackCount

2.31

Y

recordLabel

labelOwnerId

2.32

Y

labelOwnerName

subRecordLabel

labelOwnerId

2.33

N

labelOwnerName

displayLabel

2.34

Y

provisionProducerLine

2.35

N

distFlg

2.36

Y

originalReleaseDate

2.37

Y

rights

startDate

2.38

Y

endDate

country

type

mediaFlg

2.39

Y

explicit

2.40

Y

contentLanguage

2.70

N

custom1

2.41

N

custom2

2.42

N

custom3

2.43

N

custom4

2.44

N

custom5

2.45

N

imageLocation

2.46

N

Track

discNumber

2.47

Y

trackNumber

2.48

Y

trackId

2.49

Y

grid

2.50

N

isrc

2.51

Y

duration

2.52

Y

title

display

2.53

Y

language

artistId

2.54

Y

artistName

artistName.display

2.55

Y

artistName.language

Y

genre

genreName

2.56

Y*

subGenreName

distFlg

2.57

Y

displayLabel

2.58

Y

contributors

id

2.69

N

role

name

provisionProducerLine

2.59

N

rights

startDate

2.60

Y

endDate

country

type

mediaFlg

2.61

Y

explicit

2.62

Y

audioLocation

2.68

N

contentLanguage

2.71

N

pubRights

2.72

N

custom1

2.63

N

custom2

2.64

N

custom3

2.65

N

custom4

2.66

N

custom5

2.67

N

TunedGlobal`s unique album identifier ID.  Use this ID for access to album assets such as artwork (via catalogue delivery API)

FORMAT: String

MANDATORY: Y

This object will describe the delivery.  Options are New, Update or Takedown.  Recommended best practice is;

• New Action:  Add all metadata to your system as a new item.  Best practice is to test for the existence of this ID, even though it is denoted as new.
  • Note that to make an album or track active on your system you must still check the Album Rights (2.38) and Track Rights (2.60) and ensure that you are complying with the startDate (in a territory for which you have a license) to give people access to the asset.  Note: This is a critical requirement of your licensing, otherwise you will be in Breach of your agreement.
• Update Action; Treat an update as a New, being to delete the metadata in your system and re-insert as per a New.  This includes fetching new objects as they may have been updated by the label.
  • Notes 
    • An update can be a takedown in that the endDate in rights has been updated to be a past, today or future date.  You must check these dates and manage the availability of the products on your system.  This means that if an endDate is past or today, then the album or track should NOT be available.  If it is a future date, you must create a system to make this product unavailable at that time.  TUNED will not send through an additional update for this item.
    • To make an album or track active on your system you must still check the Album Rights (2.38) and Track Rights (2.60) and ensure that you are complying with the startDate (in a territory for which you have a license) to give people access to the asset.  
    • Rights management is a critical requirement of your licensing, otherwise you will be in Breach of your agreement.
• If an Takedown, you can assume you can remove all the rights to this item immediately and make it unavailable on your system.

I=INSERT (NEW), U=UPDATE, X=TAKEDOWN

FORMAT: String

MANDATORY: Y

The UPC that identifies this release.  Note that a UPC is not unique, multiple labels may deliver the same UPC.  This is for information only, rely on the releaseId as a unique property.

FORMAT: String

MANDATORY: Y

The GRID that identifies this release.  

FORMAT: String

MANDATORY: N

Denotes the type of release, Album, Single, EP etc.

FORMAT: String

MANDATORY: Y

This is an array denoting the title of the album.  The array supports multiple languages.

The objects are; 

• display: The Title to display 
• language: denoting the ISO code for the language.

display

FORMAT: String

MANDATORY: Y

language

FORMAT: String (ISO 3166-1 alpha-2)

MANDATORY: Y

Denotes the artist ID.  Use this ID to build your own Artist Data System.

FORMAT: String

MANDATORY: Y

This is an array denoting the name of the artist.  The array supports multiple languages.

The objects are; 

• display: The Artist Name to display 
• language: denoting the ISO code for the language.

display

FORMAT: String

MANDATORY: Y

language

FORMAT: String (ISO 3166-1 alpha-2)

MANDATORY: Y

This is an array denoting the genre of the album.  The array supports multiple genres.

The objects are; 

• genreName: A primary genre for this album 
• subGenreName: denoting a sub genre to the primary genre.

genreName

FORMAT: String

MANDATORY: N

subGenreName

FORMAT: String 

MANDATORY: N

Denotes number of discs for this Album.

FORMAT: Number

MANDATORY: Y

Denotes number of tracks for this Album.

FORMAT: Number

MANDATORY: Y

This is a parent tag denoting the record label of the album.  The objects are; 

• labelOwnerID: This is the TG id of delivering party 
• labelOwnerName: denoting the name of the delivering party.

labelOwnerId

FORMAT: Number

MANDATORY: Y

labelOwnerName

FORMAT: String 

MANDATORY: Y

This is a parent tag denoting the delivering sub label. This is used where the main delivering party is an aggregator (i.e. Merlin) and the actual label  is then the sub record label.

The objects are; 

• labelOwnerID: This is the TG id of delivering party 
• labelOwnerName: denoting the name of the delivering party

labelOwnerId

FORMAT: Number

MANDATORY: Y

labelOwnerName

FORMAT: String 

MANDATORY: Y

Display label (eg. LaFace records).

FORMAT: String

MANDATORY: Y

C Line for display only

FORMAT: String

MANDATORY: Y

Denotes general avail;ability of this album for display purposes.  Streaming rights are at a track level.  

0 = Album Distribution is available, 1 = Album Distribution is NOT available

FORMAT: String

MANDATORY: Y

Denotes original release date of album.  If unavailable the release date will be used. 

FORMAT:  String, yyyy-mm-dd

MANDATORY: Y

This is an array denoting the availability of the album.  Granular streaming rights are at a track level.   The array supports multiple territories. Note: The JSON feed shall often contain more territories than you have licensed. You need to ensure that you check that you have a license for the RecordLabelID (2.32) for the applicable territory.

The objects are; 

• startDate: the start date for access, sent with UTC offset  
• endDate: the end date for access
• country: the applicable territory in ISO 3166 format(WW denotes worldwide)
• type: the usage type such as streaming or download, streaming is the default.

startDate

FORMAT: String, YYYY-MM-DD

MANDATORY: Y

endDate

FORMAT: String, YYYY-MM-DD

MANDATORY: Y

country

FORMAT: String, (ISO 3166-1 alpha-2 includes WW)

MANDATORY: Y

type

FORMAT: String

MANDATORY: Y

Denotes if the Album is a video or audio album 

1: Audio only

2: Video only

FORMAT:  Number

MANDATORY: Y

Denotes if the album contains explicit lyrics 

Options are True or False

FORMAT:  String

MANDATORY: Y

Custom field for client (eg.  BPM or key).  This custom field is currently used to send BPM 

FORMAT:  String

MANDATORY: N

Custom field for client (eg.  BPM or key) 

FORMAT:  String

MANDATORY: N

Custom field for client (eg.  BPM or key) 

FORMAT:  String

MANDATORY: N

Custom field for client (eg.  BPM or key) 

FORMAT:  String

MANDATORY: N

Custom field for client (eg.  BPM or key) 

FORMAT:  String

MANDATORY: N

No longer used.  Use the Catalogue Delivery API to request the asset

FORMAT:  String

MANDATORY: N

This denotes the language of the performance.  It is only made available if it is explicitly sent through by the Licensor, otherwise this will be NULL

FORMAT: String (ISO 639-2 alpha-3)

MANDATORY: N

The disc number of this release

FORMAT: Number

MANDATORY: Y

The track number of this release.  Note if there are 2 discs the numbering will continue as a total track count, not per disc.

FORMAT: Number

MANDATORY: Y

TunedGlobal`s unique track identifier ID.  Use this ID for access to track assets such as audio or video files (via catalogue delivery API)

FORMAT: String

MANDATORY: Y

The GRID that identifies this track.  

FORMAT: String

MANDATORY: N

The ISRC that identifies this track.  Note that an ISRC is not unique, labels may deliver the same ISRC on different albums.  This is for information only, rely on the trackId as a unique property.

FORMAT: String

MANDATORY: Y

The duration of the track in seconds  

FORMAT: Number

MANDATORY: Y

This is an array denoting the title of the track.  The array supports multiple languages.

The objects are; display: The Title to display and Language: denoting the ISO code for the language.

display

FORMAT: String

MANDATORY: Y

language

FORMAT: String (ISO 3166-1 alpha-2)

MANDATORY: Y

Denotes the artist ID.  Use this ID to build your own Artist Data System.

FORMAT: String

MANDATORY: Y

This is an array denoting the name of the artist.  The array supports multiple languages.

The objects are; display: The Artist Name to display and Language: denoting the ISO code for the language.

display

FORMAT: String

MANDATORY: Y

language

FORMAT: String (ISO 3166-1 alpha-2)

MANDATORY: Y

This is an array denoting the genre of the track.  The array supports multiple genres.

The objects are; genreName: A primary genre for this album and subGenreName: denoting a sub genre to the primary genre.

genreName

FORMAT: String

MANDATORY: N

subGenreName

FORMAT: String 

MANDATORY: N

Denotes general availability of this album for display purposes.  Streaming rights are at a track level.  

0 = Album Distribution is available, 1 = Album Distribution is NOT available

FORMAT: String

MANDATORY: Y

Display label (eg. LaFace records).

FORMAT: String

MANDATORY: Y

P Line for display only

FORMAT: String

MANDATORY: Y

This is an array denoting the availability of a track in regards to its Master Rights only (not Publishing Rights).  Granular streaming rights are at a track level.   The array supports multiple territories and usage types. Note: The JSON feed shall often contain more territories than you have licensed. You need to ensure that you check that you have a license for the RecordLabelID (2.32) for the applicable territory.

The objects are; 

• startDate: the start date for access, sent with UTC offset  
• endDate: the end date for access
• country: the applicable territory in ISO 3166 format (WW denotes worldwide)
• type: the usage type such as streaming or download, streaming is the default.

Dates are formatted as follows:

   YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00)

where:

    YYYY = four-digit year

     MM   = two-digit month (01=January, etc.)

     DD   = two-digit day of month (01 through 31)

     hh   = two digits of hour (00 through 23)

     mm   = two digits of minute (00 through 59)

     ss   = two digits of second (00 through 59)

     TZD  = time zone designator (Z or +hh:mm or -hh:mm)

startDate

FORMAT: String, YYYY-MM-DDThh:mm:ssTDZ

MANDATORY: Y

endDate

FORMAT: String, YYYY-MM-DDThh:mm:ssTDZ

MANDATORY: Y

country

FORMAT: String, (ISO 3166-1 alpha-2 includes WW)

MANDATORY: Y

type

FORMAT: String

MANDATORY: Y

Denotes if the Album is a video or audio album 

1: Audio only

2: Video only

FORMAT:  Number

MANDATORY: Y

Denotes if the track contains explicit lyrics 

Options are True or False

FORMAT:  String

MANDATORY: Y

Custom field for client (Currently used to provide BPM) 

FORMAT:  String

MANDATORY: N

Custom field for client (eg.  Tag Value, such as mood) 

FORMAT:  String

MANDATORY: N

Custom field for client (eg.  Tag Value, such as mood) 

FORMAT:  String

MANDATORY: N

Custom field for client (eg.  Tag Value, such as mood, usually used for LyricFind id, if licensed) 

FORMAT:  String

MANDATORY: N

Custom field for client (eg.  Tag Value, such as mood) 

FORMAT:  String

MANDATORY: N

No longer used.  Use the Catalogue Delivery API to request the asset

FORMAT:  String

MANDATORY: N

This is an array denoting the contributor.  The array supports multiple contributors.

The objects are; 

• id: artist id if the name exist in the artist table, else the value will be 0  
• role: contributor role
• name: contributor name

id

FORMAT: Number

MANDATORY: N

role

FORMAT: String 

MANDATORY: N

name

FORMAT: String 

MANDATORY: N

This denotes the language of the performance.  It is only made available if it is explicitly sent through by the Licensor, otherwise this will be NULL

FORMAT: String (ISO 639-2 alpha-3)

MANDATORY: N

This is an array denoting the availability of a track in regards to its Publishing Rights only (not Master Rights). The array supports multiple territories and is only displayed for a territory where it has been denoted that 100% of Publishing Rights are available.

The object within the array is; 

• country: the applicable territory in ISO 3166 format

country

FORMAT: String, (ISO 3166-1 alpha-2)

MANDATORY: N