This article assumes that the reader is familiar with the ISAN metadata schema.
Note: for compatibility reasons with the new ISAN System, Groups and Version records are not supported in this version of the API. References to versions have been removed from this article, refer to ISAN API - developper guide (v1.4 - deprecated)
1. Data Schema
Both XML and JSON data format respect the following schemas:
- Main schema for non episodic (single) works: http://www.isan.org/schema/v1.11/common/common.xsd
- Main schema for serial headers (series) and episodic works (serial episodes): http://www.isan.org/schema/v1.21/common/serial.xsd
- Other dependent schemas:
2. Data Types
2.1 Main ISAN data type: ISANDataType
ISANDataType is the main type definition used for most of the API requests or responses. It is defined in the xml schema: http://www.isan.org/schema/v1.11/common/common.xsd .
ISANDataType is the common base definition for audiovisual content, i.e. single works, serial episodes, and serial headers (series).
ISANDataType provides readable only information about the status of a work, then specific descriptive metadata for series or works is addressed by specialised type definition:
- WorkMetadataType : for non episodic works
- EpisodeMetadataType: for episodic works
- SerialHeaderType: for serial headers
- VersionsType: for versions of works
2.2. Status of a work: StatusType
StatusType provides readable only information about the status of a work (see ISANDataType)
A StatusType contains the following elements:
- DataType : Describes the type of metadata that is processed
- ISAN : The ISAN associated to the record
- WorkStatus : Status of the work in the ISAN registry
- ActiveISAN : this is the Active ISAN aliased to an Inactive ISAN. Applies only when above WorkStatus element has the value INACTIVE.
- MatchingISANs : List of ISAN that match with the above ISAN element. Applies when above WorkStatus element has the value MATCH or PENDING_MATCH.
- Description : provides a description or error message in case of error.
2.2.1 DataType element
Type: String ; Occurrence : 1
Indicates the nature of the record and the data type used to encode the metadata, possible values are:
- WORK_METADATA_TYPE : Single Work metadata
- SERIAL_HEADER_TYPE: Serial Header (series) metadata
- EPISODE_WORK_METADATA_TYPE: Serial Episode metadata
- VERSION_TYPE: Version of a work metadata
#XML example: <common:DataType> </common:DataType>
#JSON example: "dataType": "
2.2.2 ISAN element
Type: isan:isanType ; Occurrence : 1
The ISAN associated to the record, contains the following elements: root, episodeOrPart, checkDigit1, version, checkDigit2
#XML example:
<common:ISAN check2="" version="" check1="" episodeOrPart="" root=""/>
#JSON example:
"isan": { "root": "", "episodeOrPart": "", "check1": "", "version": "", "check2": "" }
2.2.3. WorkStatus element
Type: String ; Occurrence : 1
Status of the work in the ISAN registry, possible values are:
- ACTIVE : the ISAN is an active registration in the ISAN registry.
- INACTIVE : the ISAN has been inactivated in the ISAN registry and aliased (or linked) to an active ISAN. Refer to ActiveISAN element for the aliased active ISAN.
- INDEV : the ISAN identifies a work in development (or Project ISAN). Only limited information (unchanged after completion of the project) is available. The full set of metadata will only be available at activation of the ISAN (completion of the project) by the producer (i.e. status will then be ACTIVE).
- PENDING (registration service only): the registration processes is pending as the work is potentially already registered with ISAN, i.e. the submitted work is matching with one or several other works in the ISAN registry; a duplicate check (manual action on the web interface) is required to finalise the registration process.
- NO_MATCH (matching service only): no ISAN is matching in the ISAN registry.
- MATCH (matching service only): a unique matching ISAN has been found in the ISAN registry. Refer to MatchingISANs element for the matching ISAN.
- PENDING_MATCH (matching service only): Several ISAN are matching in the ISAN registry. A manual conformation is required to identify the correct match. Refer to MatchingISANs element for the list matching ISAN.
#XML example: <common:WorkStatus> </common:WorkStatus>
#JSON example: "workStatus":""
2.2.4. ActiveISAN element
Type: isan:isanType ; Occurrence : 0 or 1
This is the Active ISAN aliased to an Inactive ISAN. Applies only when above WorkStatus element has the value INACTIVE. Contains the following elements: root, episodeOrPart, checkDigit1, version, checkDigit2
#XML example:
<common:ActiveISAN check2="" version="" check1="" episodeOrPart="" root=""/>
#JSON example:
"activeIsan": { "root": "", "episodeOrPart": "", "check1": "", "version": "", "check2": "" }
2.2.5 MatchingISANs element
Type: isan:isanListType ; Occurrence : 0 or n...
List of ISAN that match with the above ISAN element. Applies when above WorkStatus element has the value MATCH or PENDING_MATCH.
#XML exemple
<common:WorkStatus>PEND_MATCH</common:WorkStatus>
<common:MatchingISANs>
<isan:ISAN check2=".." version=".." check1=".." episodeOrPart=".." root=".."/>
<isan:ISAN check2=".." version=".." check1=".." episodeOrPart=".." root=".."/>
</common:MatchingISANs>
</common:status>
#JSON example
"workStatus": "PEND_MATCH",
"matchingISANs": {
"isans": [ "java.util.ArrayList",
[
{ "root": "", "episodeOrPart": "", "check1": "", "version": "", "check2": "" },
{ "root": "", "episodeOrPart": "", "check1": "", "version": "", "check2": "" },
]
]}}
2.2.6. Description element
Type: String ; Occurrence : 0,1
Provides a description or error message in case of error.
2.2.7. XML example
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<common:isanDataType
xmlns:isan="http://www.isan.org/ISAN/isan" xmlns:serial="http://www.isan.org/schema/v1.21/common/serial" xmlns:title="http://www.isan.org/schema/v1.11/common/title" xmlns:externalid="http://www.isan.org/schema/v1.11/common/externalid" xmlns:common="http://www.isan.org/schema/v1.11/common/common" xmlns:participant="http://www.isan.org/schema/v1.11/common/participant" xmlns:language="http://www.isan.org/schema/v1.11/common/language" xmlns:country="http://www.isan.org/schema/v1.11/common/country">
<common:status>
<common:DataType>WORK_METADATA_TYPE</common:DataType>
<common:ISAN check2="C" version="0000-0000" check1="X" episodeOrPart="0000" root="0000-0000-3566"/>
<common:Description>INACTIVE</common:Description>
<common:ActiveISAN check2="P" version="0000-0000" check1="4" episodeOrPart="0000" root="0000-0000-7F8D"/>
</common:status>
</common:isanDataType>
2.2.8. JSON example
{ "@type": "ISANDataType",
"status": {
"dataType": "WORK_METADATA_TYPE",
"description": "MATCH",
"matchingISANs": {
"isans": [
"java.util.ArrayList",
[{
"root": "0000-0002-163F",
"episodeOrPart": "0000",
"check1": "R",
"version": "0000-0000",
"check2": "U"
}]
]}}
}
2.3. Single Work metadata: WorkMetadataType
The WorkMetadataType element extends ISANDataType in the xml schema http://www.isan.org/schema/v1.11/common/common.xsd.
The element WorkMetadataType defines descriptive metadata for single works (non-episodic), it includes:
- the work status description inherited from ISANDataType,
- all descriptive information of the single work such as the work classification (type, code), year of reference, duration, titles, participants, languages, production companies, countries, ….
WorkMetadataType is returned by the lookup service when the record is a Single Work.
WorkMetadataType is required when submitting Single Work registrations or updates.
WorkMetadataType is required when submitting Single Work metadata matching requests.
XML example of a single work description
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<common:workMetadataType
xmlns:isan="http://www.isan.org/ISAN/isan" xmlns:title="http://www.isan.org/schema/v1.11/common/title" xmlns:externalid="http://www.isan.org/schema/v1.11/common/externalid" xmlns:common="http://www.isan.org/schema/v1.11/common/common" xmlns:participant="http://www.isan.org/schema/v1.11/common/participant" xmlns:language="http://www.isan.org/schema/v1.11/common/language" xmlns:country="http://www.isan.org/schema/v1.11/common/country">
<common:status> ... </common:status>
<common:ISAN check2="" version="" check1="" episodeOrPart="" root=""/>
<common:Type> ... </common:Type>
<common:Kind> ... </common:Kind>
<common:ExternalIdList> ... </common:ExternalIdList>
<common:TitleList> ... </common:TitleList>
<common:YearOfReference> ... </common:YearOfReference>
<common:Duration> ... </common:Duration>
<common:ColorKind> ... </common:ColorKind>
<common:OriginalLanguageList> ... </common:OriginalLanguageList>
<common:ParticipantList> ... </common:ParticipantList>
<common:ReferenceCountryList> ... </common:ReferenceCountryList>
<common:CompanyList> ... </common:CompanyList>
<common:CompositeList> ... </common:CompositeList>
</common:workMetadataType>
JSON example for a single work description
{"@type": "WorkMetadataType",
"status": {…},
"isan": {…},
"type": " ",
"kind": " ",
"externalIdList": {…},
"titleList": {…},
"yearOfReference": " ",
"duration": {…},
"colorKind": " ",
"originalLanguageList": {…},
"referenceCountryList": {…},
"participantList": {…},
"companyList": {…},
"compositeList": {…}
}
2.4. Serial Header (series) metadata: SerialHeaderType
Note: The SerialHeaderType will disappear from the upcoming version of the ISAN API, it will be replaced by a SeriesMetadataType (high similarities with WorkMetadataType). Refer to New Episodic Schema for more information on series.
The SerialHeaderType element extends ISANDataType, it is defined in the xml schema http://www.isan.org/schema/v1.21/common/serial.xsd.
The element SerialHeaderType defines descriptive metadata for serial headers (series), it includes:
- the work status description inherited from ISANDataType,
- all descriptive information of the serial header such as the titles, the total number of episodes registered in the serial, the total number of seasons registered in the serial, the duration of shortest episode, the duration of longest episode, the year of reference of oldest episode, the year of reference of most recent episode, the most recurring participants, the most recurring production companies.
SerialHeaderType is returned by the lookup service when the retrieved work is a serial header (serie).
SerialHeaderType is required when submitting serial headers registrations or serial headers metadata update requests.
XML example of a serial header work description
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<serial:serialHeaderType
xmlns:isan="http://www.isan.org/ISAN/isan" xmlns:title="http://www.isan.org/schema/v1.11/common/title" xmlns:serial="http://www.isan.org/schema/v1.21/common/serial" xmlns:externalid="http://www.isan.org/schema/v1.11/common/externalid" xmlns:common="http://www.isan.org/schema/v1.11/common/common" xmlns:participant="http://www.isan.org/schema/v1.11/common/participant" xmlns:language="http://www.isan.org/schema/v1.11/common/language" xmlns:country="http://www.isan.org/schema/v1.11/common/country">
<common:status>…</common:status>
<serial:SerialHeaderId root=""/>
<serial:MainTitles> ... </serial:MainTitles>
<serial:TotalEpisodes> ... </serial:TotalEpisodes>
<serial:TotalSeasons> ... </serial:TotalSeasons>
<serial:MinDuration> ... </serial:MinDuration>
<serial:MaxDuration> ... </serial:MaxDuration>
<serial:MinYear> ... </serial:MinYear>
<serial:MaxYear> ... </serial:MaxYear>
<serial:MainParticipantList> ... </serial:MainParticipantList>
<serial:CompanyList> ... </serial:CompanyList>
</serial:serialHeaderType>
JSON example of a serial header work description
{ "@type": "SerialHeaderType",
"status": {…},
"serialHeaderId": {"root": ""},
"mainTitles": {…},
"totalEpisodes": …,
"totalSeasons": …,
"minDuration": {…},
"maxDuration": {…},
"minYear": " ",
"maxYear": " ",
"mainParticipantList": {…},
"companyList": {…}
}
2.5. Episodic work metadata: EpisodeWorkMetadataType
The EpisodeWorkMetadataType element extends WorkMetadaType , it is defined in the xml schema http://www.isan.org/schema/v1.21/common/serial.xsd.
The element EpisodeWorkMetadataType defines descriptive metadata for Serial Episodes, it includes:
- the work status description inherited from ISANDataType,
- the same descriptive information as Single Works such as the work classification (type, code), year of reference, duration, titles, participants, languages, production companies, countries, ….
- specific information for episodes: season number, episode number, the reference to the series / serial header ( = the root ISAN shared by the ISAN of all episodes of the series).
EpisodeWorkMetadataType is returned by the lookup service when the record is a Serial Episode.
EpisodeWorkMetadataType is required when submitting Serial Episodes registrations or updates.
XML example of an episode work description
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<serial:episodeWorkMetadataType
xmlns:isan="http://www.isan.org/ISAN/isan" xmlns:serial="http://www.isan.org/schema/v1.21/common/serial" xmlns:title="http://www.isan.org/schema/v1.11/common/title" xmlns:externalid="http://www.isan.org/schema/v1.11/common/externalid" xmlns:common="http://www.isan.org/schema/v1.11/common/common" xmlns:participant="http://www.isan.org/schema/v1.11/common/participant" xmlns:language="http://www.isan.org/schema/v1.11/common/language" xmlns:country="http://www.isan.org/schema/v1.11/common/country">
<common:status> ... </common:status>
<common:ISAN check2="" version="" check1="" episodeOrPart="" root=""/>
<common:Type> ... </common:Type>
<common:Kind> ... </common:Kind>
<common:ExternalIdList> ... </common:ExternalIdList>
<common:TitleList> ... </common:TitleList>
<common:YearOfReference> ... </common:YearOfReference>
<common:Duration> ... </common:Duration>
<common:ColorKind> ... </common:ColorKind>
<common:OriginalLanguageList> ... </common:OriginalLanguageList>
<common:ParticipantList> ... </common:ParticipantList>
<common:ReferenceCountryList> ... </common:ReferenceCountryList>
<common:CompanyList> ... </common:CompanyList>
<common:CompositeList> ... </common:CompositeList>
<serial:EpisodeDetails>
<serial:SerialHeaderId root=""/>
<serial:Season> ... </serial:Season>
<serial:Episode> ... </serial:Episode>
</serial:EpisodeDetails>
</serial:episodeWorkMetadataType>
JSON example for an episode work description:
{ "@type": "EpisodeWorkMetadataType",
"status": {…},
"isan": {…},
"type": " ",
"kind": " ",
"externalIdList": {…},
"titleList": {…},
"yearOfReference": " ",
"duration": {…},
"colorKind": " ",
"originalLanguageList": {…},
"referenceCountryList": {…},
"participantList": {…},
"companyList": {…},
"compositeList": {…}
"episodeDetails": {
"serialHeaderId": {…},
"season": " ",
"episode": " "
}
}