eidr api overview

EIDR SYSTEM VERSION 1.0

API OVERVIEW

2011 APRIL 11

Copyright © 2011 by the Entertainment ID Registry Association

EIDR API Overview.

The content of this manual is furnished for information use only and is subject to change without notice and should not be construed as a commitment by the Entertainment ID Registry Association. The Entertainment ID Registry Association assumes no responsibility or liability for any errors or inaccuracies that may appear in this document.

Products and company names mentioned may be trademarks of their respective owners.

Feedback on this document can be sent to [email protected]

EIDR API Overview P a g e | 2 Version 1.01 –2011‐04‐07

TABLE OF CONTENTS 1. DOCUMENT SCOPE..............................................................................................................................5

2. GENERAL CONVENTIONS..................................................................................................................5

2.1 Errors ............................................................................................................................................................ 5

2.2 Asynchronous and Immediate Calls................................................................................................................ 7

2.3 Batch Transactions ........................................................................................................................................ 7

2.4 Mode Summary............................................................................................................................................. 8

3. OBJECTS..................................................................................................................................................8

3.1 Create and Modify......................................................................................................................................... 8 3.1.1. Cheat Sheet – Object Types ............................................................................................................................. 9 3.1.2. Cheat Sheet ‐‐ Relationships .......................................................................................................................... 10 3.1.3. Create............................................................................................................................................................. 12 3.1.4. Adding and Removing Relationship ............................................................................................................... 12 3.1.5. Modifying Objects.......................................................................................................................................... 14 3.1.6. Promote ......................................................................................................................................................... 14 3.1.7. Delete............................................................................................................................................................. 15 3.1.8. Alias................................................................................................................................................................ 15 3.1.9. Request Status ............................................................................................................................................... 16

3.2 Object Information ...................................................................................................................................... 18 3.2.1. Resolution ...................................................................................................................................................... 19 3.2.2. Traversal......................................................................................................................................................... 21 3.2.3. Queries........................................................................................................................................................... 24 3.2.4. Virtual Fields .................................................................................................................................................. 29 3.2.5. Provenance .................................................................................................................................................... 30

4. PARTIES, USERS, AND PERMISSIONS......................................................................................... 30

4.1 Parties......................................................................................................................................................... 31 4.1.1. Create............................................................................................................................................................. 31 4.1.2. Modify............................................................................................................................................................ 32 4.1.3. Administrative Tasks ...................................................................................................................................... 33 4.1.4. Retrieving Information................................................................................................................................... 33

4.2 Permissions ................................................................................................................................................. 36



5. UTILITIES............................................................................................................................................ 38

5.1 DOI Proxy .................................................................................................................................................... 38

6. PREDEFINED OBJECTS AND CONSTANTS ............................................................................... 39

6.1 Tombstones................................................................................................................................................. 39

6.2 Error handling.............................................................................................................................................. 39

6.3 Pre‐defined Parties ...................................................................................................................................... 39

6.4 Handle Prefixes ........................................................................................................................................... 39

7. APPENDICES....................................................................................................................................... 40

7.1 Seasons and Episodes .................................................................................................................................. 40

7.2 Complex Inheritance.................................................................................................................................... 40 7.2.1. ResourceName............................................................................................................................................... 40 7.2.2. Languages ...................................................................................................................................................... 41

7.3 Modifying Objects ....................................................................................................................................... 42

7.4 Text Processing............................................................................................................................................ 42 7.2.3. Field Rules ...................................................................................................................................................... 42 7.2.4. Language‐Specific Filtering ............................................................................................................................ 44

7.5 Escaping XML Characters ............................................................................................................................. 46

7.6 Mapping EIDR fields to DOI fields................................................................................................................. 46


1. DOCUMENT SCOPE

This is an overview of the public and administrative APIs for EIDR. It does not cover

• De‐duplication (an internal interface)

• Bulk registration (an API extension provided by an EIDR application)

• Analytics

• Low‐level database mirroring. With this privileged API a client can request periodic updates from the registry and ask for details of changes made during a particular time window. The combination of these two allows for priming a copy of the data and then keeping it up to date, as well as taking a simple snapshot of the registry at any particular instant. (Simple bulk read of objects can be implemented at the application level.)

• User account management (though this may be included in a future version if third parties are allowed to develop applications that create accounts)

The registry interface itself is REST‐based. This document presents it as a traditional procedural API, such as might be used in a Java or JavaScript interface built on top of the underlying HTTP and XML.

2. GENERAL CONVENTIONS

2.1 ERRORS

Standard errors are:

• Authentication: The system could not authenticate the user and/or group in the request.

• Authorization: The requester is not authorized to perform the action, or access one or more of the DOIs in the request

• RegistryReadOnly: The Registry is in read‐only mode. If the primary system goes down, the mirror systems are still available for reading. Certain system administration tasks (synchronization with a backup, bulk export, etc.) may also have this result.

• SystemError: The registry is unable to deal with the request for some internal reason.1

• InvalidRequest: The request URL is invalid, or contains unrecognized or invalid HTTP headers, or contains unrecognized or invalid information.

1 In some cases these may set the registry into read-only mode until the problem is addressed.

• BadDOI: The request contains a DOI that is syntactically correct but has an invalid checksum or is not recognized by the system. Syntactically malformed DOIs generate a SyntaxError. The bad DOI is included as a detail.

• SyntaxError: The XML in the request does not pass schema validation.

• ValidationError: The XML in the request is syntactically correct but fails other validation rules, or the request would result in an object that violates the validation rules, or the object passed in is inappropriate for the call. The detail field can be:

o IncompatibleCreationTypes: A call to GetModificationBase() failed because metadata needed for the requested type is not present on the object.

o NotRemovable: Returned on failed attempt to remove a relationship. This can occur either when the relationship does not exist, or when its removal would result in an invalid object or hierarchy.

o AliasNotAllowed: An aliased DOI was passed to a function that doesn’t accept aliases.

o IncompatibleAliasTarget: A DOI is being aliased to an incompatible object.

o NotInDev: the call failed because an attempt was made to promote an object that was not in the InDev state. Also includes the offending DOI as a detail. See Promote().

Other errors are:

• BadToken:The token sent to GetStatus() was not recognized.

• BadQuery: The query string was malformed.

• NoParent: The object sent to GetParent() is itself the root of the tree.

• NoChildren: The object sent to GetChildren() is itself a leaf of the tree.

• ResultTooLong: A result was too large to fit in a REST response. This can be caused by requesting too large a page size in queries.

• DuplicateParty: Returned by CreateParty() if the request is to create a duplicate Party. The duplicate party is returned as a detail.

• DuplicateUser: Returned by CreateUser() if the request is to create a duplicate User. The duplicate user is returned as a detail.

• BadParty: The partyID submitted as part of a request was invalid.

• BadUser: The userID submitted as part of a request was invalid.


2.2 ASYNCHRONOUS AND IMMEDIATE CALLS

Calls can be immediate (the result is returned immediately) or asynchronous (the call returns a token which is used to discover the status of the request). Not all calls support asynchronous results; those that do have a flag in the interface specifying which mode to use.

All calls must be explicitly specified as immediate or asynchronous; there is no defaulting mechanism.

In general, only calls that require confirmation from the de‐duplication system can be asynchronous.

• Create()

• Promote()

• AddRelationship()

• RemoveRelationship()

• RemoveSpecificRelationship()

• ReplaceRelationship()

• Modify()

All other calls are immediate‐mode only. (These calls may still have some delay, based on the load on the Registry, but it should be assumed to be minimal.)

• Delete()

• Alias()

• GetModificationBase()

• Queries, traversals, resolution

2.3 BATCH TRANSACTIONS

The asynchronous versions of Create(), Promote(), Modify() , and Delete() take one or more sets of input parameters. This means a batch can only contain one kind of operation. A status token is returned for each item in the batch, and one for the batch itself. If the batch contains only one item, the batch token and the item token are the same. Each item in the batch is processed separately, and there is no guarantee that the items will be processed in the same order as they exist in the batch. Thus, batches with operations that depend on each other (e.g. , creating a series and its seasons in a single batch) will have unpredictable results.


Submission of the batch is authenticated; authorization checks are done on each element of the batch. If there is an error processing an item in the batch, that item fails, and querying its status will return appropriate information. Processing of the other items in the batch is not affected.

2.4 MODE SUMMARY

Note: In case of lack of clarity in the text for individual functions, this table is definitive for batch and immediate/asynchronous support for each function.

Function Batchable? Mode

Create() Yes Immediate or Asynchronous

Promote() Yes Immediate or Asynchronous

AddRelationship() No Immediate or Asynchronous

RemoveRelationship() No Immediate or Asynchronous

RemoveSpecificRelationship() No Immediate or Asynchronous

ReplaceRelationship() No Immediate or Asynchronous

Modify() Yes Immediate or Asynchronous

Delete() Yes Immediate only

Alias() No Immediate only

GetModificationBase() No Immediate only

Queries, traversals, resolution No Immediate only

3. OBJECTS

3.1 CREATE AND MODIFY

Objects are categorized in four ways:

• Type: Types are of two sorts – basic and derived. The Basic Type covers the minimal possible object. It is sufficient for describing a wide variety of assets. Derived Types include all the information in the Basic Type, and add extra information for describing more complex objects. The Derived Types in EIDR are Edit, LanguageVariant, Series, Season, Episode, Composite, Clip, Encoding, and InteractiveMaterial.


• Inheritance: Objects in the registry are logically a graph. An object can only have one parent. Only information from the parent's basic type fields can be inherited. This worldview uses standard computer science terminology ‐‐ ancestors and descendents, root objects and leaf nodes.

• Dependence: An object may depend on another object in some way, by including a reference to it. There is no inheritance, and the metadata of dependents and objects on which they depend have only coincidental relationship to each other. For example, when encoding A refers to encoding B by reference, A is dependent on B, and when Composite C includes Clip K, C is dependent on K.

• Relationships: A relationship is a casual term for the way in which two objects are connected. Relationships are described using two or more objects and some metadata. They are classified as:

o Lightweight relationships ‐ which have no inheritance; the objects to which they refer do not influence the underlying nature of the object on which the relationship exists. These relationships are used primarily when moving around the object tree and connecting object trees to each other. The lightweight relationships are IsPackagingOf, IsPromotionFor, IsAdjunctTo, and IsAlternateContentFor.

o Dependence relationships ‐ where the objects to which the relationship refers have a strong bearing on the basic nature of the object on which the relationship exists. Importantly, this means that the objects referred to in the relationship need to be taken into account when checking for duplicates when an object is created or modified. The dependence relationships are IsCompositeOf and IsEncodingOf.

o Inheritance relationships ‐ where the object on which the relationship exists can inherit basic metadata fields from the object to which the relationship refers. With the exception is IsLanguageVariantOf, only one inheritance relationship may exist on an object. The Inheritance relationships are IsSeasonOf, IsEpisodeOf, IsEditOf, IsLanguageVariantOf, IsEncdoingOf, and IsClipOf.

Not all combinations of type, inheritance, and dependence are legal. The Validation Rules are the normative description of legal and illegal combinations.

3.1.1. CHEAT SHEET – OBJECT TYPES

In order to reduce complexity, the API to create and modify objects is constrained in several ways, rather than exposing a generic data structure to be filled in. Nonetheless, all legal combinations of type and inheritance can be created and modified using the API, and all legitimate relationships to other objects can be added and removed.

These are the flavors of the Create() call, which uses CreationType as one if its arguments.


Creation of Objects Creation Type

Basic Objects Referent type can be: TV Show, Movie, Short, Web CreateBasic

with IsSeasonOf inheritance relationship

Only way to create Season referent type CreateSeason

with information for derived type InteractiveMaterial

Only way to create InteractiveMaterial referent type CreateInteractive

with information for derived type Series

Only way to create Series referent type CreateSeries

with IsEncodingOf inheritance relationship

Only way to create an object that has IsEncodingOf relationship CreateEncoding

with IsEditOf inheritance relationship

Only way to create an object that has IsEditOf relationship CreateEdit

with IsClipOf inheritance relationship

Only way to create an object that has IsClipOf relationship CreateClip

with IsLanguageVariantOf inheritance relationship

Creates a child with a IsLanguageVariantOf relationship CreateLanguageVariant

with IsEpisodeOf inheritance relationship

Only way to create an object that has IsEpisodeOf relationship CreateEpisode

with IsCompositeOf dependent relationship

Only way to create an object of referent type Composite CreateComposite

Once an object is created, there is no way to change its nature. For example, there is no call to remove series information from an object and be left with a basic object.

An object's referent type is immutable after the object is created.

3.1.2. CHEAT SHEET ‐‐ RELATIONSHIPS

Here is the summary of how relationships can interact with each other.

Relationship Type Can co-exist with

Can be added after creation

Removable?

IsSeasonOf Inheritance No No

IsEpisodeOf Inheritance IsCompositeOf No No

IsEditOf Inheritance IsLanguageVariant No No

IsClipOf Inheritance IsLanguageVariant No No



Relationship Type Can co-exist with

Can be added after creation

Removable?

IsCompositeOf Dependence IsEpisodeOf to episodes

to basic objects not of referent type Composite

Yes, if the referent type is not Composite

IsEncodingOf Inheritance Dependence

IsLanguageVariant No No

IsLanguageVariant Inheritance Clip

Encoding

Edit

Yes, provided some other inheritance relationship already exists on the object; both relationships must have the same Parent

Can be removed if it is not the only inheritance relationship on an object; this can occur if another creation type is used and a language variant is added to it after the fact; if the language variant is created first, there are no legal additions to make to it.

IsPromotion Lightweight Any Yes Multiple instances allowed on an object

IsPackaging Lightweight Any Yes Multiple instances allowed on an object

IsAlternateContent Lightweight Any Yes Multiple instances allowed on an object

IsAdjunctContent Lightweight Any Yes Multiple instances allowed on an object

Here are the legal ways to add relationships after object creation:

Addition of IsLanguageOf Inheritance Relationship

Basic Object with Clip inheritance relationship Language and Clip must have same parent

Basic Object with Encoding inheritance relationship Language and Encoding must have same parent

Basic Object with Edit inheritance relationship Language and Clip must have same parent

Addition of IsCompositeOf Dependent Relationship

Basic Object Base object will not be of referent type Composite

Basic Object with IsEpisodeOf inheritance relationship

The lightweight relationships ‐‐ IsPromotion, IsPackaging, IsAlternateContent, and IsAdjuctContent ‐‐ can be added to any object at any time.

Any relationship that can be added can be removed, with the following exceptions:

• IsLanguageOf is not removable if it is the object's only inheritance relationship. This is the case when the language variant was supplied at creation time.

• IsCompositeOf is not removable if the object's referent type is Composite. This will be the case when the composite information was supplied at language creation time.

See the appendix for examples of modifying objects.

3.1.3. CREATE

Create(creationType, creationData, mode)

Returns a status token, for use in GetStatus() calls. Objects that are created with a status of InDev are not checked by the de‐duplication service; they are sent for de‐duplication when they are promoted to Valid. (See the Promote() call.)

Mode is of type eidr:requestModeType and can be either asynchronous or immediate. In the REST implementation, this is passed in the http headers rather than in the XML for the request.

Batch input allowed.

There is a data type defined in the schema for each creationType, and the two must match in the call. For example, to create a series you would use CreateSeries and CreateSeriesData. These types are subsets of FullObjectInfoType and are used to limit the scope for mistakes for common operations.

Errors: Standard errors; also see GetStatus()

3.1.4. ADDING AND REMOVING RELATIONSHIP

Adding, removing, and replacing relationships is limited to those relationships that are not determinants of the object's nature. For example, you can't add IsSeasonOf, or remove IsEpisodeOf.

AddRelationship(DOI, relationshipType, relationshipData)

Returns: a status token, for use in GetStatus() calls. A ValidationError is returned (via the status) if the relationship cannot be legally added to the object.

relationshipType and relationshipData are one of the following pairs:

• CompositeRelationship, compositeInfoType

• LanguageRelationship, languageConstructionInfoType


• PackagingRelationship, packaginInfoType

• AdjunctRelationship, adjunctContentInfoType

• PromotionalRelationship, promotionInfoType

• AlternateContentRelationship, alternateContentInfoType

RemoveRelationship(DOI, relationshipType)

Returns: a status token, for use in GetStatus() calls. A NotRemovable error is returned (via the status) if the relationship cannot be legally removed from the object.

Legal types are as for AddRelationship().

All relationships of the specified type are removed. (Only lightweight relationships can exist multiply on an object, however.)

IsCompositeOf is only removable if the object's referent type is not Composite.

Errors: standard errors

RemoveSpecificRelationship(DOI, relationshipType, targetDOI)

Returns: a status token, for use in GetStatus() calls. A NotRemovable error is returned (via the status) if the relationship cannot be legally added to the object.

relationshipType must be one of the lightweight relationships. If there is a relationship of that type with targetDOI, it is removed.


ReplaceRelationship(DOI, relationshipType, relationshipTypeData)

Returns: a status token, for use in GetStatus() calls.

relationshipType and relationshipData are one of the following pairs:

• CompositeRelationship, compositeInfoType

• LanguageRelationship, languageConstructionInfoType

Note that relationshipType must not be one of the lightweight relationships – there could be multiple of them, and so the API supports this through a remove followed by an add (rather than encrufting the API with an extra parameter to differentiate them). This remove and add procedure is not recommended for the relationships that are involved in uniquely identifying an asset, since the remove operation could cause the record in its intermediate state to be a duplicate of another object.



The existing relationship information for relationshipType on the object is replaced by the new relationshipTypeData.

If the replaced relationship is LanguageRelationship, the Parent field of any other inheritance relationship on the object is replaced with the Parent field of relationshipTypeData.


3.1.5. MODIFYING OBJECTS

Modifying objects is done by getting current information on the object, modifying it, and re‐submitting it.

GetModificationBase(DOI, creationType)

Returns object metadata for creationType. The schemas used for the return are the same as the one used for creating an object of that type.

For example, consider an object created using CreateSeries. GetModificationBase(DOI, CreateBasic) returns just the field on the basic object, and GetModificationBase(DOI, CreateSeries) returns all the metadata needed to create a series.

The underlying object must be able to support all the fields needed by creationType. It is incorrect to call GetModificationBase(DOI, CreateComposite) on the object in the previous example.

Errors: standard errors and IncompatibleCreationTypes.

Modify(DOI, creationType, creationTypeData)

Returns: a status token, for use in GetStatus() calls. The request is passed to the de‐duplication system in the same way as a regular Create() call2. It is possible, though not necessarily safe, to pass in data not returned from GetModificationBase().If the object has multiple inheritance relationships and Parent is changed in creationTypeData, the Parent field of the other inheritance relationships is changed as well.


Errors: standard errors and IncompatibleCreationTypes.

3.1.6. PROMOTE

This call turns an InDev object to a Valid object. Once it is made, the referenced object is visible to the world at large.

2 Note that children of the modified object are not passed to de-duplication, even though they might inherit the changed values.

InDev objects do not go through the de‐duplication system when they are created, but are checked for duplicates when promoted. The returned token can be used in GetStatus() calls.

Promote(DOI, mode)

Returns: status token.

Mode is of type eidr:requestModeType and can be either asynchronous or immediate. In the REST implementation, this is passed in the http headers rather than in the XML for the request.


InDev objects do not go through the de‐duplication system, but are checked for duplicates when promoted. The returned token can be used in GetStatus() calls.

If the call is successful, the Promote and View ACLs are removed from the object, and it is viewable by any user.

Returns standard errors and NotInDev.

3.1.7. DELETE

Ideally, every DOI is permanent. Sometimes, however, an item really does need to be deleted (for example, a cancelled project at a defunct production house), or is so badly wrong it should be removed.

EIDR does not delete the DOI itself; rather, it makes the DOI an alias (see below) for a standard tombstone object.

Delete(DOI)

Returns status token for use in GetStatus()

Forces the DOI to resolve to a tombstone.

The LastModified field in the provenance for a deleted DOI is the time at which the object was deleted.

Only an object with no relationships and no dependents can be deleted. Use FindDescendents() and GetLightweightRelationships() (or resolve to eidr:simpleDataInfoType) to find the relationships and Get Dependents() for dependent items.

Batch input allowed

Errors: standard error set, and dependency errors

3.1.8. ALIAS

An alias is a simple indirection from one DOI to another. An alias is not intended as a general tool; rather, it should only be used for correcting errors. For example, if a film mistakenly gets two IDs (perhaps because of problems involving workflow and working titles) the incorrect one can be aliased to the correct one. As a concrete example, if a wrong ID gets burned onto a BD‐live disk and is subsequently corrected by aliasing,


that ID can still be resolved by the server in response to client requests for the deprecated ID. The server can treat the content as valid simply because the ID is resolvable, or add extra checking.

There are constraints placed on the types of the old and new objects:

• Anything can alias to a basic object.

• A series object must alias to a series object or a base object.

• A season object must alias to a season object or a base object.

ConvertToAlias(OldIdentity, NewIdentity)

Subsequent reads of OldIdentity return data from NewIdentity. Any other action (such as a traversal or a rooted query) requested on OldIdentity will generate an error.

OldIdentity remains a valid ID in the system, and it is still resolvable.

After this call:

• Reading data

o All resolutions related to OldIdentity will return data from NewIdentity, unless the call has a followAlias flag set to false.

o All other calls return an error; the application should follow the alias to get the actual DOI, and then use it.

o The LastModified field in the provenance for an aliased DOI is the time at which the object was aliased.

o Application hint: if the DOI in the metadata from a resolution is not the same as the input DOI, the input DOI has been aliased.

• Queries: All queries relative to the aliased DOI will return an error.

Only an object with no relationships and no dependents can be aliased. Use FindDescendents() and GetLightweightRelationships() (or resolve to simpleDataInfoType) to find the relationships and Get Dependents() for dependent items.

Errors: standard error set, HasDependents, and IncompatibleAliasTarget

3.1.9. REQUEST STATUS

All asynchronous calls return a token that can be used to query the status of the request.

GetStatus(token, page, pageSize, continuationToken)

Errors: standard errors, BadQuery, and ResultTooLong

The paging parameters are used as follows:


• Results are returned with pageSize objects per batch.

• The page‐th page of that size is returned. Page 1 is the first page. Page 0 is a request for all results.

• ContinuationToken should be a value returned by the previous call using this query string, or empty if this is the first call in the set.

Returns (token, status) element if token is not a batch token.

If token is a batch token, returns

• PageSize – max size of returned chunks (same as input parameter pageSize)

• MySize – size of this chunk (equal to pageSize except for the last page

• TotalPages – total number of pages that can be returned

• PageNum – number of the returned page

• TotalResults – total number of available results

• ContinuationToken – returned by implementations that internally cache request state. It should be passed in as the ContinuationToken argument on subsequent calls as an accelerator.

• A list of the(token, status) element for each item in the batch that falls in the returned page of results

Values for a token representing a batch

• BatchReceived – the batch has been fully read in, but no status for its sub‐elements is available

• BatchQueued – the batch is being processed, and status is available for all its sub‐elements

• BatchInvalid – there was an error in the batch; one of the standard errors is also returned as a detail

Values for tokens for individual items in the batch:

• Success: When the request has succeeded, for example by creating a new object or deleting an old one. The detail field contains the DOI associated with the successful operation: a new DOI for creation, and the passed‐in DOI in other cases.

• Duplicate: When a duplicate or potential duplicates are found during create, modify, or promote. The detail field contains one or more DOIs of items detected as duplicates; the IDs for all duplicates are returned.

• Pending: When the registry is waiting to finish an operation, but has not yet had any errors; in the case of create, modify, and promote it may have as a detail a list of DOIs for one or more potential duplicates.


• Failure: When the request fails, for example after an attempt to create a duplicate item.

• Error: Adds one of the error values as a detail.

The call itself can return any of the standard errors or a BadToken error.

GetStatus(Registrant, filter, token, page, pageSize, continuationToken)

GetStatus(User, filter, token, page, pageSize, continuationToken)

The last four arguments are treated as they are for GetStatus().

Filter can be:

• Status: legal-status-value : Only tokens that match the supplied value are returned.

• After: date-time : Only tokens issued after the supplied time are returned.

• Range: date-time-start date-time-end : Only tokens generated between the two dates are returned.

Legal combinations are:

• No filter

• Status only

• After only

• Range only

• Status and after

• Status and Range

Registrant returns a paginated list of (token, status) for every token belonging to Registrant that matches Filter. A token belongs to a registrant if a user in Registrant‘s group made request with which it is associated.

User returns a paginated list of (token, status) for every token generated by a request from User and matching Filter.

3.2 OBJECT INFORMATION

There are several ways of getting information about a DOI:

• Resolution provides various views of the metadata associated with a particular DOI.

• Traversal provides information about how the DOI fits into the object hierarchy.


• Queries return DOIs with metadata matching certain criteria.

• Provenance returns information about the DOI's creation and modification. It is a special case of resolution.

3.2.1. RESOLUTION Resolve(DOI, resolutionType, followAlias)

Returns: metadata associated with the DOI.

If followAlias is true (the default), information returned is from the object to which an aliased refers, not from the aliased object itself.

If followAlias is false and the object is not aliased, the information likewise comes from the object itself.

If followAlias is false and the object is aliased, an AliasContinuation is returned.

Notes:

An alias can be detected as follows:

o When followAlias is true, by comparing the DOI field of the returned object with the input DOI; if they differ, the input DOI is aliased.

o When followAlias is false, by detecting that an AliasContinuation has been returned rather than formatted metadata.

o Aliases are followed for five levels. If the final item is still aliased, an AliasContinuation object is returned which contains the last aliased DOI found and the item to which it is aliased.

For resolutionType, the defined values and behavior are as follows:

ResolutionType Follow Alias?

Return Value

DOIKernel true Returns metadata formatted as doi:kernelMetadata.

If the alias chain is too deep, returns an AliasContinuation.

For an InDev object, returns a structural type of restricted. The object's name is "No information available".

For a deleted object, returns a structural type of 'Restricted', and field values from the standard tombstone object.




Return Value

DOIKernel false If the object is aliased this returns doi:kernelMetadata where:

• structural type is 'Restricted' • title is 'aliased' • referentCreation.identifier.type is DOI

• referentCreation.identifier.value is the DOI to which the object is aliased

For a deleted object, returns a structural type of 'Restricted', and field values from the standard tombstone object.

Simple true Returns metadata formatted as eidr:simpleDataInfoType. This is the format returned by queries and traversals.


Simple false If the object is not aliased, returns eidr:simpleDataInfoType.

If the object is aliased, returns AliasContinuation. (See above.)

Full true Returns metadata formatted as eidr:fullObjectInfoType.


Full false If the object is not deleted or aliased, returns eidr:fullObjectInfoType.


SelfDefined true Returns metadata formatted as eidr:allSelfDefinedInfoType.


SelfDefined false If the object is not deleted or aliased, returns eidr:allSelfDefinedInfoType.


Inherited true Returns metadata formatted as eidr:allInheritedInfoType.


Inherited false If the object is not deleted or aliased, returns eidr:allInheritedInfoType.

If the object is aliased, returns AliasContinuation. (See above.).



Return Value

Provenance true The provenance record for object (with the alias chain followed) as eidr:provenanceInfoType.

If the alias chain is more than 5 deep, returns an AliasContinuation object.

Provenance false The provenance record for the object itself as eidr:provenanceInfoType. The LastModificationDate field is the date the object was aliased or deleted.

See the Appendix for details on the complex inheritance types (for ResourceName and languages.)

3.2.2. TRAVERSAL

Traversals are used for discovering how the DOI fits in to the graph that represents its relationship to other objects.

Traversals stop at the first object for which the requester does not have read permission. The standard Permission error is used only for permission errors on the DOI in the original request.

Traversals always follow aliases.

All traversals return results in depth‐first order.

FindAncestors(DOI, list of referentTypes, list of structuralTypes, list of relationshipTypes)

Returns a list of (simpleData, generationsAbove) for all ancestors which match one of the referent types, one of the structural types, and one of the relationship types. Empty lists match anything. The search stops when an object has no ancestors, and only ancestors that count for inheritance are considered (i.e., none of the ‘lightweight relationships’ count).

generationsAbove is 1 for a parent, 2 for the parent's parent, etc.

The object itself is not returned.

Recall that objects can only inherit from one parent.

Examples:

• FindAncestors(DOI, "", "", "")finds all of the object's ancestors.

• FindAncestors(DOI, "", "", "IsEditOf")finds all ancestors that are edits of a predecessor.

FindDescendants(DOI, list referentTypes, list of structuralTypes, list of relationshipTypes)

Returns a list of (simpleData, generations above) for all descendants which match one of the referent types, one of the structural types, and one of the relationship types. Empty lists match anything. The search stops when an object has no descendants, and only items that can inherit considered (i.e., none of the ‘lightweight relationships’ count).

generationsBelow is 1 for a child, 2 for a child's child, etc.

The object itself is not returned.

Recall that objects can only inherit from one parent.

Examples:

• FindDescendants(DOI, "") finds all the DOI’s descendants.

• FindDescendants(DOI, "digital","","IsEncoding") finds all the encodings descended from the DOI.

• FindDescendents(DOI, "","season") finds all the seasons descended from DOI.

GetDependentObjects(DOI)

Returns a list of eidr:simpleDataInfoType for DOIs that depend on the input DOI that are not part of an inheritance relationship or a lightweight relationship.

This can be used to find composites and encodings that include a particular DOI.

The remaining traversal functions are provided as a convenience; they can all be implemented at the client by parsing the results of resolutions and the above traversals.

GetSeriesAncestry(DOI)

Returns eidr:seriesAncestryType, which is:

• eidr:simpleDataInfoType for the DOI

• eidr:simpleDataInfoType and eidr:episodeInfoType for the nearest ancestor (which can be the input DOI) that has episode data on it. Not present if there is no such ancestor.

• eidr:simpleDataInfoType and eidr:seasonInfoType for the nearest ancestor (which can be the input DOI) that has season data on it. Not present if there is no such ancestor.

• eidr:simpleDataInfoType and eidr:seriesInfoType for the nearest ancestor (which can be the input DOI) that has series data on it. Not present if there is no such ancestor.


The validation rules enforce that there can be no more than one ancestor of each of the types.

This function is intended for use by UIs, management reports, and so on.

GetLightweightRelationships(DOI)

Returns the list of DOIs to which the input DOI has a non‐inheriting (i.e. 'lightweight') relationship. Each element in the list contains:

eidr:simpleDataInfoType for the related DOI

the type of the relationship (IsAdjunct, etc.)

the class of the relationship (e.g., Outtake)

GetRemotestAncestor(DOI)

Returns eidr:simpleDataInfoType and generationsAbove for the most distant ancestor.

If the input object has no ancestors, the input object is returned.

If the object has ancestors, this is the equivalent of looking for the highest‐numbered generationsAbove in the return values from FindAncestors(DOI, "", "", "").

GetLeafDescendants(DOI)

Returns eidr:simpleDataInfoType and generationsBelow for all descendants that have no descendants of their own. Note that generationsBelow may not be the same for all leaf nodes.

If the input object has no descendants, the input object itself is returned.

If the object has descendants, This can also be done by interpreting the results from GetDescendants(DOI, "", "", ""), but that is a little tricky since not all leaf descendants will be at the same level; you really do have to build a simple tree from the returned values.

GetParent(DOI)

Returns eidr:simpleDataInfoType for the input DOI's parent.

Returns an error of NoParent if the input object is at the top of a tree.

This is useful if all you have is a DOI, not any of its metadata, and want to know its parent. It can be done anyway by looking for generationsAbove=1 in the results of GetAncestors(DOI, "", "", "").

GetChildren(DOI)


Returns eidr:simpleDataInfoType for all of the input DOI's immediate descendants.

Returns an error of NoChildren if the input object is a leaf of a tree.

This can be implemented by looking for generationsBelow=1 in the results of GetAncestors(DOI, "", "", "").

3.2.3. QUERIES

OVERVIEW

The query facility takes a set of metadata criteria as input and returns eidr:simpleDataInfoType for all objects that match those criteria. The simplest query tests a single metadata field. More complex queries can be built up by grouping simple queries together with standard logical expressions.

The metadata fields to be tested are represented with a subset of XPath notation that supports only complete paths to elements and attributes. The XPath used in query requests can be based on:

• /FullMetadata, which is of type fullObjectInfoType: This queries across objects' inherited metadata.

• /ProvenanceMetadata, which is of type provenanceInfoType: This queries across objects' provenance metadata

In these examples the parentheses are not strictly necessary, but improve legibility. Note that XML at the protocol level requires escaping of special characters (<, >, etc.), although procedural implementations of the API may hide that from the application.

This query finds all objects longer than 20 minutes and shorter than 40 minutes:

(/FullMetadata/BaseObjectData/ApproximateLength > PT20M00S) AND (/FullMetadata/BaseObjectData/ApproximateLength < PT40M00S)

This finds all records modified in 2010. (See below for the precision of date comparisons.)

(/ProvenanceMetadata/LastModificationDate = 2010)

There are several kinds of simple queries, not all of which are applicable to all fields.

Exact Value: These queries use IS and ISNOT. They are applicable to

• Fields containing DOIs

• Fields containing controlled vocabulary

• Certain text fields (see the Text Processing Appendix)

Exact Value‐language: This special case of Exact Value fields for language fields uses IS and ISNOT and behaves as follows:

• If only a pre‐dash component is supplied in the query, it matches anything with that prefix. • If the language code in the query has a – in it, it only matches another field that is exactly the same. • Examples:


o es matches objects that have es, es‐ES, and es‐419 o de‐CH matches de‐CH, but not de or de‐DE.

Order: Queries on these fields can be done using comparisons (<, <=, >=, >) as well as equality and inequality (=, <>)

• Fields containing Integers • Fields containing Dates • Fields containing Durations

Existence: The existence of a field can be queried. This is useful for optional elements that represent large optional sub‐blocks (e.g. the the component encodings in an Encoding.) Inversion 1.0 of the Registry, EXISTS is supported on these fields: SubtitleInfoBlock, AudioInfoBlock, VideoInfoBlock, InteractiveInfoBlock, WrapperInfoBlock, LanguageVariantInfo/Add, LanguageVariantInfo/Replace

For example, this finds all objects that have information about separately encoded subtitles:

(/FullMetadata/ExtraObjectMetadata/EncodingInfo/SubtitleInfoBlock EXISTS)

Text Matching:

• Text queries are case‐insensitive.

• Both the text in the query string and the text stored in the registry are generally processed into tokens before matching. Tokenization consists of one or more of the following steps.

o Normalization: Sequences of whitespace are collapsed into a single space; some punctuation is converted to spaces; and some punctuation is removed (causing concatenation of the string before it with the string after it). This gives a series of tokens.

o Two filters can be applied to the tokens that result from normalization: o Stop words (small, common words, such as 'the' or 'in' in English or 'la' and 'en' in

Spanish) are filtered. o Words are stemmed; stemming removes plurals, turns inflected words into the

appropriate root, and so on.

Please see the Text Processing Appendix for language dependencies and details of which of the rules are applied to each metadata field.

There are two kinds of text queries:

• The form <field> <string1>…<stringN> is true for any field that has one or more of the strings. It is equivalent to <field> <string1> OR <field> <string2> OR ... OR <field> <stringN>

• The form <field> "<string>" is true for any field that has exactly <string> in it. <string> is tokenized before the comparison. Stated another way, the token sequence generated by <string> must appear exactly in <field>. The tokenization rules applied to applied to <string> are those applied to <field>.



The grammar for query expressions is:3

<expression> ::= <term> | <expression> OR <term> | <expression> AND <term> | NOT <term> <term> ::= <field> EXISTS | <field> <string> <string>* | <field> "<string>" | <field> IS "<string>" | <field> ISNOT "<string>" | <field> <logop> <value> | ( <expression> ) <field> ::= legal xpath attribute | legal xpath element <value> ::= number | date | time | duration <logop> ::= = | <> | < | <= | > | >=

NOTES AND EXAMPLES

• The types on each side of a <logop> must be compatible.

• Wildcards are not currently supported; normalization and stemming cover the problems for which wildcards are generally used.

• Comparison operations for dates and times truncate to the lowest precision in the expression.

• Language fields are not tokenized in any way. For example,

• /FullMetadata/BaseObjectData/PrimaryLanguage/Language "en"

Will match records whose primary language is en, but not en-US, since en-US is retained as the single token en-US, not the two token sequence en US.

• Although ranges are not directly supported, they can be implemented using two simple queries combined by AND.

• Fields that contain controlled vocabulary are tokenized, with punctuation characters removed.

• The empty string matches nothing, rather than everything.

• For non‐existent fields, all ISNOT comparisons evalauate as True. For example, if there is no CountryOfOrigin field, (/FullMetadata/BaseObjectData/CountryOfOrigin ISNOT fr) is True.

• IS and ISNOT apply to Value, Value‐language, and Text fields.

3 NOTE: * is the equivalent of EBNF {} and "<term> || NOT <term>" could be EBNF "[NOT]<term>"

o For Value fields, they are useful for testing for controlled vocabulary words, equality of DOIs, and equality of non‐tokenized fields such as HouseSequence, AlternateID, and the various private data fields.

o For Value‐language, they are used as described above.

o For text fields, the field and the string have the same tokenization rules applied (see Text Processing Appendix for individual fields).

• Comparisons are done to the precision of the least precise argument. For example, a date field containing 2010 is >=, <=, and = to 10‐10‐2010. Comparing a date of 2010 to 10 is not <>, <, or > 10‐10‐2010

• Some applications may want to do queries across only metadata on the object itself, as opposed to the full metadata. This can be useful for applications whose main purpose is dealing with the metadata, rather than dealing with the objects defined by the metadata. This can be done by doing a regular query, calling Resolve() to return only self‐defined metadata, and then examining those results.

• As an example, imagine a Registry that has objects with the following titles in the ResourceName fields:

o Batman: The Dark Knight

o Knight of Dark Stories

o Dancing In The Dark

o Darkness At Noon

o Darkness Waits

o The Ghost and The Darkness

o Shanghai Knights

o Shanghai Noon

o Sinbad: The Battle of the Dark Knights

o First Knight

Querying on /FullMetadata/BaseObjectData/ApproximateLength (abbreviated field in the table) gives these results:

Expression Results Notes

field Dark Batman: The Dark Knight

Knight of Dark Stories

Dancing In The Dark

Sinbad: The Battle of the Dark Knights

Anything with 'Dark'

field "Dark Knight"

Batman: The Dark Knight

Anything with exactly the sequence 'Dark Knight'. Sinbad: The Battle of the Dark Knights is not included because titles are not stemmed.



Expression Results Notes

field Dark Knight



Dancing In The Dark


First Knight

Any title that has 'Dark' or 'Knight'.

field Knights Shanghai Knights


Any title with 'Knights'

(field Dark) AND (field Knight)



Any title with both Dark and Knight, in any order and any position

(field Dark) AND NOT (field The)


Sinbad: The Battle of the Dark Knights is not included because comparison is case‐insensitive.

• The ISNOT, NOT, and <> operators can be inefficient when applied globally, but it is possible to rewrite queries to work around this. For example,

(/FullMetadata/BaseObjectData/ApproximateLength > PT45M0S AND NOT /FullMetadata/BaseObjectData/ApproximateLength = PT50M0S)

will be more responsive than

NOT (/FullMetadata/BaseObjectData/ApproximateLength = PT50M00S)

API

RootedQuery(DOI, queryExpression, page, pageSize, continuationToken)

GeneralQuery(queryExpression, page, pageSize, continuationToken)

Returns type eidr:queryResults, which contains:







• ContinuationToken – returned by implementations that internally cache query results. It should be passed in as the token argument on subsequent calls as an accelerator.

• A list of eidr:simpleDataInfoType for all objects that match queryExpression, chunked up based on the last four parameters. A malformed or empty queryExpression returns a BadQuery error

Errors: standard errors, BadQuery, and ResultTooLong





The only difference between the two query functions is that RootedQuery() only returns results that are the children of the DOI argument.

The results are sorted by language code of the primary title, and then by title within each language code.

Errors: standard errors, BadQuery, ResultTooLong

3.2.4. VIRTUAL FIELDS

Besides individual fields, an object contains two 'virtual' string fields that combine multiple other fields. Both of these are normalized (punctuation stripped, spaces collapsed) and tokenized using the default (English) rules. Stop‐word filtering and stemming are not applied.4 This also applies to strings as queries on the virtual fields.

• FullString – composed of these fields from FullObjectMetadataType

o BaseObjectData/ResourceName

o BaseObjectData/AlternateResourceName

o BaseObjectData/DisplayName

o BaseObjectData/Description

o BaseObjectData/Credits/Director/DisplayName

o BaseObjectData/Credits/Actor/DisplayName (using all that are present)

4 Many of the components of the virtual field are names and titles, which are not filtered or stemmed on their own, and this rule applies to the whole virtual field.

SelfDefinedString –as FullString, but only those fields that are not inherited

In queries, the virtual fields are

/VirtualField/Full

/VirtualField/SelfDefined

The order of the tokens within each of the constituent fields is preserved, but the order in which the constituent fields are added to the virtual field is not defined. This means that an exact match query (using <field> "<string">) returns unpredictable results when the exact query might match token sequences that cross fields. It matches token sequences within individual fields predictably as it would on the single field.

The values of the virtual fields can be retrieved using GetVirtualFields(). This can be useful for debugging, but is not intended to be used for presentation to an end user.

GetVirtualFields(DOI)

Returns a structure of type eidr:VirtualFields containing the two strings

Errors: standard errors only

3.2.5. PROVENANCE

An object's provenance information can be retrieved by calling Resolve(DOI, "Provenance", followAlias.

When an object is created, its LastModificationDate is set equal to its CreationDate.

Times in the provenance are stored as UTC with the explicit timezone marker Z.

4. PARTIES, USERS, AND PERMISSIONS

A Party represents an entity such as a registrant or a producing agent. A User is an individual (or an abstract thing that can be treated as an individual.) Note: for historical reasons, the initial implementation sometimes calls a Party a 'Group.'

All Users are associated with a Party. The current version of the registry supports only this single level of hierarchy; future versions may add sub‐entities, as well, for representing different organization within a single Entity.

All requests to the registry contain authentication information for a party and a user.

The User requesting the creation of a new object must be associated with the Registrant (a Party) given in the registration data.

Only Parties have permissions in the system; a User has all the permissions associated with its parent Party.

Note: Only the Registration Authority has the ability to create or modify parties .


4.1 PARTIES

There is a predefined Party representing the Registration Authority.

An entity can be one or more of the following:

• ProducingAgent: These bring forth the object being registered: a studio in the case of an abstract work; or an encoding house for the work in a final digital form; or even an anti‐piracy vendor for registering a new illegal copy of a work. The important thing to remember about this field is that it refers to the entity that most recently ‘touched’ the item.

• Registrants, who register items. A registrant may be a principal agent, such as a studio or an encoding house, or it may be an external entity doing bulk registration of back‐catalogue items.

• CurrentAssetHolder: This party may be included optionally by the registrant to indicate the entity the registrant thinks is most likely to have some authority over this object. For example, a metadata provider doing bulk registration may make this field the same as the Producing Agent for objects reasonably sure to be under the control of that entity, and leave it blank otherwise.

• BackupContact: Optionally registered entities that may be able to sort out things that are otherwise beyond the ken of the Registrant.

• EncodingVersionAgent: optional entity used when registering encodings.

Additionally, an entity can be registered as

• Writer: can read and modify objects, but not create them.

• Reader: if on an object's ACL, can read objects and metadata that would otherwise be hidden. This matters for InDev objects only.

As an example, an encoding house that registers new encodings will be the Registrant for the object. In the strictest sense, they could be the ProducingAgent as well, but that is not mandated; for example, the rights holder could require that the ProducingAgent for the encoding be the same as that for the parent object. The encoding house will also probably be the EncodingAgent for each item, unless some aspect has been subcontracted out elsewhere (e.g., to a specialist subtitle shop.)

A Party can be either Active or Inactive. An inactive Party may not make any modifications to the database; that is, it may not be a Registrant or a Writer, and all Users associated with it are similarly restricted.

4.1.1. CREATE CreateParty(partyData)

Returns a DOI of type eidr:partyDOIType for the newly created party. The parameter partyData is of type eidr:partyCreationType.

The suffix of the returned DOI is the PartyAccountName field from partyData. It must not match any other PartyAccountName in the system.

Errors: Standard errors or DuplicateParty.


Note: In the initial version of the Registry, only minimal checking is done for duplicates of Parties. Applications using CreateParty() should be accordingly cautious.

CreateUser(userData)

Returns a DOI of type eidr:userDOIType for the newly created user.

userData is of type eidr:userCreationType, with the following constraints:

• userData.Username is of type eidr:usernameType and must not match any other username in the system.

• userData.ParentParty is of type eidr:partyDOIType

• userData.Password must be 6‐32 characters long

The suffix of the returned DOI is the Username field from userData.

Errors: Standard errors, DuplicateUser, or BadParty.

Note: The initial version of the Registry only checks for an exact duplicate of username.

4.1.2. MODIFY

ModifyParty(partyData)

Returns success or an error.

partyData is of type eidr:partyResolutionType. ResolveParty(partyID, "full") returns an appropriate base for modifications.

Note that this does not include the password field. partyData.ID cannot be modified.

Errors: Standard errors or BadParty.

ChangePartyPassword(partyID, newPartyPassword)

Changes the Party's password. The old password is not sent separately; it is already with the credential sent with the call.

Errors: Standard errors or BadParty.

ModifyUser(userInfo)

Returns success or an error.

userInfo is of type eidr:userResolutionType. ResolveUser(userID, "full") returns an appropriate base for modifications.

Note that this does not include the password field. userInfo.ID cannot be modified.

Errors: Standard errors or BadUser.

ChangeUserPassword(userID, newUserPassword)

Changes the User's password. The old password is not sent separately; it is already with the credential sent with the call.


Errors: Standard errors or BadUser.

ReparentUser(userID, newPartyID)

Returns Success, Standard Errors, BadParty, or BadUser.

If successful, removes the user from its previous group and assigns it to the new one.

4.1.3. ADMINISTRATIVE TASKS

Note: Only the Registration Authority can perform the following tasks.

DeactivateParty(partyID)

Returns Success, Standard Errors or BadParty.

If successful, users associated with the party are no longer allowed to do anything that requires presence on an ACL. partyID is virtually removed from ACLs (the Registry checks the active/inactive state of entries in the ACL), not actually removed; this allows easy deactivation and reactivation of parties for administrative reasons.

ActivateParty(partyID)

Returns Success, Standard Errors or BadParty. If successful, the Party is made active.

DeactivateUser(userID)

Returns Success, Standard Errors or BadUser.

If successful, the user is no longer allowed to do anything; authentication of the user's credentials will fail.

ActivateUser(userID)

Returns Success, Standard Errors or BadUser.

If successful, the user's credentials are valid and authentication of them succeeds.

ValidateCredentials(partyID, userID, password)

partyID is of type eidr:partyDOITYpe

userID is of type eidr:userDOIType

password is of type eidr:simplePasswordType.

Returns:

• 'all valid' if the userID and password are correct and userID is associated with partyID.

• 'wrong party' if the user and password match but userID is not associated with partyID

• 'invalid' is the user and password don’t match.

Errors: Standard errors.

4.1.4. RETRIEVING INFORMATION

ResolveParty(partyID, type)


Returns metadata for the party; the format of the result is dependent on the type parameter.

Type Format

DOIKernel DOI kernel metadata for a Party

Full eidr:partyResolutionType; see the schema.

The PartyAccountName field will match the suffix of the DOI

Errors: Standard errors, or BadParty

ResolveUser(userID, type)

Returns metadata for the user; the format of the result is dependent on the type parameter.

Type Format

DOIKernel DOI kernel metadata for a Creation, with structural type of restricted. The object's name is "No information available".

Full eidr:userResolutionType; see the schema.

The Username field will match the suffix of the DOI.

Errors: Standard errors, or BadUser

GetUsers(partyID)

Returns list of eidr:userDOIType for all Users associated with partyID, which must be of type eidr:partyDOIType.


FindPartiesByName(string, roleFilter, activeFilter, page, pageSize, continuationToken)

See below for use of paging parameters and string.

roleFilter is an optional list of strings of type eidr:administratorTypeType.

activeFilter is 'active', 'inactive', or 'all'.

Returns type eidr:partyQueryResults, which contains:








• A list of eidr:partyDOIType for all parties

o whose DisplayName field or AlternatePartyName field contains string,

o that match activeFilter, and

o whose AllowedRoles contains one or more of the elements of roleFilter. If roleFilter is not present, any role will match.

For example, "Fox" would return the records for Fox Television and 20th Century Fox.

For the search, String, DisplayName and SortName are normalized (spaces collapsed, punctuation removed) but not tokenized, filtered for stop words, or stemmed.

Errors: standard errors and ResultTooLong


• Results are returned with pageSize objects per batch



Internally, the Registry keeps a list of Parties sorted by SortName (or DisplayName of SortName is not present.) Sections of this sorted list are returned using the FindPartiesFromCatalog() call.

FindPartiesFromCatalog(string, roleFilter, activeFilter, page, pageSize, continuationToken)

See below for use of paging parameters and string.

roleFilter is an optional list of strings of type eidr:administratorTypeType.

activeFilter is 'active', 'inactive', or 'all'.

Returns type eidr:partyQueryResults, which contains:








• A list of eidr:partyDOIType, in lexical order by SortName (or DisplayName if SortName does not exist), for all parties found matching these criteria: A list of eidr:partyDOIType for all parties

o whose DisplayName field contains string

o that match activeFilter

o whose AllowedRoles contains one or more of the elements of roleFilter. If roleFilter is not present, any role will match

o string is used as follows:

The empty string matches all Parties

Lettersequence: returns all parties whose SortName (or DisplayName if there is not SortName) starts with the letter sequence. For example "BBC" would return the records for BBC, BBC Worldwide, BBC Cymru, BBC Scotland, and BBC America.

Lettersequence1‐lettersequence2: returns all parties whose SortName (or DisplayName if there is not SortName) starts with something between lettersequence1 and lettersequence2, inclusive. If lettersequence2 is not lexically greater than lettersequence1, all items from lettersequence1 though the end of the sorted list of Parties are returned. For instance, "A‐B" returns all Parties whose names start with A or B.

Note that if lettersequence1 and lettersequence2 are identical, the behavior is the same as for the single lettersequence.

For the search, string, DisplayName and SortName are normalized (spaces collapsed, punctuation removed) but not tokenized, filtered for stop words, or stemmed.

Errors: standard errors and ResultTooLong





4.2 PERMISSIONS

A regular record can be created, modified, aliased, or deleted. An In‐Development record can also be promoted. It is also possible to read certain types of administrative information about a record.

A Party (and its Users) can only create a new record if it has 'Registrant' in the AllowedRoles field.


A Party (and its Users) must be able to read an object in order to create or modify any inheritance, dependence, or lightweight relationships involving it. For example, an IsAdjunctTo relationship cannot be made to an InDev object by a Party that is not on the InDev object's ReadACL.

Other actions are gated by ACLs on the individual records. Each regular record has an ACL for:

• Modify: can contain entities that are of type Registrant or Writer. Required to modify an object.

• Delete: can contain entities that are of type Registrant or Writer. Required to alias or delete an object.

• ReadACL: can contain entities that are of type Registrant, Writer, or Reader. Required to read any ACL.

• WriteACL: can contain entities that are of type Registrant. Required to modify any ACL.

• ReadProvenance: can contain entities that are of type Registrant, Writer, or Reader. Required to read the provenance metadata. Only the Registration Authority can modify a record's Provenance information.

In‐Development records have two more ACLs:

• Promote: entities on this list must be of type Registrant. Only entities on this list can promote an InDev object to Valid.

• View: entities on this list can be of any type. Only entities on this list can view an InDev object or have them returned from a query.

The following table summarizes possible permissions based on the Role. For a given Object, the associated permissions for a particular Party (with a Role) may be more restrictive than what’s specified in the table.

Role/Permission View Read ACL

Read Provenance

Modify Delete Write ACL

Promote

Registrant Yes Yes Yes Yes Yes Yes Yes

Writer Yes Yes Yes Yes Yes Yes Yes

Reader Yes Yes Yes

PrincipalAgent Yes

CurrentAssetHolder Yes

BackupContact Yes

EncodingAgent Yes

If a Role is removed from a party, any ACL that depends on the presence of that role will disallow the action, even if the Party is in the ACL. For example, if the Writer role is removed from a Party, that Party and its associated Users will not be able to modify records for which it was already on the ACLs for Modify, Delete,


WriteACL, and Promote, and will not subsequently be able to be added to the ACLs for Modify, Delete, WriteACL, or Promote on any other objects.

ReadACL (assetID, aclType)

Returns a list of the Parties on the specified ACL for assetID, which must be of type eidr:assetDOIType.


ClearACL(assetID, aclType)

Removes all Parties from the specified ACL for assetID, which must be of type eidr:assetDOIType.


AddToACL(assetID, aclType, partyID)

Adds partyID to the specified ACL for assetID, which must be of type eidr:assetDOIType. PartyID is of type eidr:partyDOIType.

Errors: Standard errors, and BadParty if partyID is not valid.

RemoveFromACL(assetID, aclType, partyID)

Removes partyID from the specified ACL for assetID, which must be of type eidr:assetDOIType. PartyID is of type eidr:partyDOIType.

Errors: Standard errors, and BadParty if partyID was not on the ACL.

5. UTILITIES

5.1 DOI PROXY

EIDR resolutions can be requested from the standard DOI proxy. Resolution requests are of the form:

http://dx.doi.org/<Handle prefix>/<Handle suffix>

Object resolutions have the standard optional resolution type specifier, e.g.,

http://dx.doi.org/10.5240/5551-2125-5512-1255-7FFF-3?locatt=type:Full

In the following table, 'Resolution Type' is the string after the colon in the ?locatt=type: construction. (none) means that the type specifier is not provided.

Proxy resolutions follow alias chains, and behave like the Resolve() call with followAlias set to true. See Resolve() for information on special cases for deleted objects, over‐nested aliases, etc.

EIDR item Prefix Resolution Type Returns



EIDR item Prefix Resolution Type Returns

Party 10.5237 (none) doi:kernelMetadata with a doi:referentParty element

User 10.5238 (none) doi:kernelMetadata with referent type of Restricted

doi:referentParty element with a name of "EIDR User"

Object 10.5240 (none) Returns metadata formatted as eidr:fullObjectInfoType.

Object 10.5240 Full Returns metadata formatted as eidr:fullObjectInfoType.

Object 10.5240 SelfDefined Returns metadata formatted as eidr:allSelfDefinedObjectInfoType.

Object 10.5240 Simple Returns metadata formatted as eidr:simpleDataInfoType

Object 10.5240 DOIKernel Returns metadata formatted as doi:kernelMetadata.

6. PRE‐DEFINED OBJECTS AND CONSTANTS

6.1 TOMBSTONES

Deleted objects are aliased to a 'tombstone.' Because the tombstone object is of type 'Restricted', only three of its fields have guaranteed values. Other fields should not be used.

Field Value

ID 10.5240/ 0000‐0000‐0000‐0000‐0000‐X

Structural Type Restricted

Resource Name "EIDR Tombstone Object"

The tombstone object is not indexed, so it will never be returned from queries.

6.2 ERROR HANDLING

The structures used for returning errors are in api.xsd

Error strings and numeric error codes are in api‐common.xsd

6.3 PRE‐DEFINED PARTIES

The party 10.5237/superparty is predefined and has all allowed roles. It has a predefined user 10.5238/superuser.

10.1000/ra‐5 is the DOI for the EIDR Registration Authority; it is used in the DOIKernel resolution format.

6.4 HANDLE PREFIXES

The Handle prefixes used by the registry are:

• 10.5237 – parties

• 10.5238 – users

• 10.5240 – assets/objects

7. APPENDICES

7.1 SEASONS AND EPISODES

The interactions between name, number, and the IsOrdered flag in seasons and series is:

Seasons:

• SequenceNumber is required for seasons.

• ResourceName is required for a season if parent.IsOrdered is false.

Episodes:

• SequenceNumber is required for episodes if parent.IsOrdered is true.

• ResourceName is required for episodes if parent.IsOrdered is false.

• It is legal for both SequenceNumber and ResourceName to be present.

7.2 COMPLEX INHERITANCE

Most inheritable fields use simple inheritance – the value is taken directly from the parent, which in turn may have taken it from its parent, and so on up the inheritance chain until an object is found that defines the field. In these cases, a field's value is one of either the self‐defined metadata or the inherited metadata.

ResourceName and Primary and secondary languages behave differently, because languages and titles can be replaced in a particular object (providing a new value) or accreted (adding a new value to a pre‐existing set). In these cases, the value found in the object's full metadata is not necessarily the same as either the self‐defined or the inherited metadata, but can be a combination of things.

7.2.1. RESOURCENAME

ResourceName is cardinality 1 in baseObjectInfoType ‐‐ it must exist in a fully resolved object ‐‐ and 0‐1 in selfDefinedBaseObjectInfoType and inheritedBaseObjectInfoType, where it can be either present on the object or inherited. A resource name specifies the language of the name, and the class of the name – Release, Working, Acronym, and so on.

The ReplacedAlternateResourceNames flag behaves as follows:

• If true, the alternate titles in the object replace all others. It can be true, with no AlternateNames provided, which results in an empty alternate title list. If it is false, the names provided are added to the list of inherited alternate names.


• It is itself an inheritable field. Although the alternate names on a root object behave the same no matter which way the flag is set, since replacing an empty list and adding to an empty list are equivalent, the value in a root object should be one that supports downstream practices for alternate names, for example for edits and encodings.

AlternateResourceName is a list of alternate names for the object, of type titleType. 0 or more of these are provided when an object is created. In records returned from the registry:

• In selfDefinedBaseObjectInfo, the elements are the set of items provided when the object was created or modified.

• In inheritedBaseObjectInfo, the elements are any that are inherited. Note that if ReplacedAlternateNames is true, this list is empty; if it is false, it contains only the items provided by ancestors

• In baseObjectInfoType, it is the collated list of alternate titles (adding or replacing as stated above.)

7.2.2. LANGUAGES

PrimaryLanguage and SecondaryLanguage in the base type are provided only when creating a root object.

A root object defines a PrimaryLanguage element, and a set of optional SecondaryLanguage elements. These contain only language information; titles are specified separately using the ResourceName and AlternateResourceName elements.

These two fields are not directly modifiable in non‐root objects. Instead, extra languages are specified with an IsLanguageVariant dependence relationship, which comes in two forms:

• Add: only secondary languages can be specified, and they are added to any inherited secondary languages. The primary language is unchanged.

• Replace: This supports three variants:

o Primary language only: The primary language is replaced, and all secondary languages are removed.

o Primary and one or more secondary languages: The primary language is replaced, all existing secondary languages are removed, and the secondary languages in the request are added.

o Secondary languages only: All secondary languages are removed, and replaced with the secondary languages in the request. The set is allowed to be empty, in which case all secondary languages are removed.

When resolving an object, the behavior is as follows:

• In selfDefinedBaseObjectInfo, the PrimaryLanguage and SecondaryLanguage elements are never present, unless the object is a root object.


• In inheritedBaseObjectInfo, the languages elements are any that are inherited. These inherited values may be directly inherited from the root object, or generated by following add/replace rules in the ancestors. This list does not include the languages in any LanguageVariant relationship on the object itself.

• In baseObjectInfoType, the PrimaryLanguage and SecondaryLanguage elements contain collated languages, starting from the root and following the add/replace instructions in any IsLanguageVariant relationships in the chain, including any on the object itself. This is sometimes called the rolled‐up set of languages, or fully inherited languages, and represents the languages actually present on the object.

7.3 MODIFYING OBJECTS

Modifying objects has two components:

• Changing metadata for the type with which the object was created or could have been created.

• Changing metadata for relationships which have been added or could have been added to the object.

In all of these examples, 'legal' is contingent on the new data passing the validation rules. This table is not exhaustive.

Initial creationType

Subsequent additions Legal modification bases Legal replace/remove relationship

CreateBasic none CreateBasic none

CreateSeries none CreateBasic, CreateSeries none

CreateClip LanguageRelationship CreateBasic, CreateClip, CreateLanguageVariant

LanguageRelationship

7.4 TEXT PROCESSING

7.2.3. FIELD RULES

There are three kinds of matches:

• Token Match – the check is made for the existence of the tokens in any order in the candidate string. This uses the <field> <string> <string> syntax.

• Exact Match – the check is done for the existence of an ordered sequence of tokens in the candidate string. This uses the <field> "<string>" syntax.

• Complete Match – checks for the exact existence of the exact query string or not. This is generally used for fields containing controlled vocabulary or IDs, but can also be used on some text fields. For


a non‐tokenized field, the query string and the field must be identical. A tokenized field must be identical to the tokenized query string. This uses the IS and ISNOT operators.

Controlled vocabulary fields have punctuation replaced by a space, and are then tokenized.

Field Match type Normalize Filter Stop Words

Stem

Token Yes No No ResourceName

Exact Yes No No

Token Yes No No AlternateResourceName

Exact Yes No No

Token Yes No No DisplayName

Exact Yes No No

Token Yes No No VirtualField (Full and self‐defined)

See description of Virtual Fields. Exact Yes No No

Token Yes No No md:PersonName‐type/DisplayName

Exact Yes No No

Token Yes No No md:PersonName‐type/SortName

Exact Yes No No

Token Yes No No md:PersonName‐type/FirstGivenName

Exact Yes No No

Token Yes No No md:PersonName‐type/SecondGivenName

Exact Yes No No

Token Yes No No md:PersonName‐type/FamilyName

Exact Yes No No

Token Yes No No md:PersonName‐type/Suffix

Exact Yes No No

Token Yes No No md:PersonName‐type/Moniker

Exact Yes No No

Token Yes Yes Yes Description

Exact Yes No No

Token Yes Yes Yes WrapperDetails

Exact Yes No No



Field Match type Normalize Filter Stop Words

Stem

HouseSequence Complete No No No

RegistrantExtra Complete No No No

RegistrantPrivate Complete No No No

AlternateID Complete No No No

Any field of type componentReferenceType:

EncodingInfo/xxxInfoBlock/ComponentReference and

EncodingInfo/WrapperInfoBlock/ComponentInfo/componentReference

Total No No No

FindPartiesByName See function definition

Yes No No

FindPartiesFromCatalog See function definition

Yes No No

7.2.4. LANGUAGE‐SPECIFIC FILTERING

There are language‐specific lists for English, French, Spanish, Italian, and German for:

• Punctuation that turns into spaces

• Punctuation that collapses two words together

• Stop words that get filtered out

Language‐specific rules are given in the table below. If a field has a language attribute, then the language‐specific rules are applied; otherwise, English rules are applied. The query string is processed based on the language field in the queried field; if there is no language attribute, English rules are applied.

Note that the dash in language fields (e.g. de‐CH) is not removed.

Language Spacing Punctuation Collapsing Punctuation

Stop Words

English . , ; : ^ & ! + ‐ = ( ) [ ] { } < > ~ # $ / * @ / € £

' (single quote)

" (double quote)

‐ (hyphen)

’ (apostrophe)

a, the, this, that, these, some, is, are, and, or, but, so, as, at, by, of, on, for, in, into, to, with, I, you, he, she, it, we, they, them, its, theirs

French . , ; : ^ & ! + ‐ = ( ) [ ] { } < > ~ un, une, le, la, les, l, ce, ces, c, de, du, des, d, est,


Language Spacing Punctuation Collapsing Punctuation

Stop Words

# $ / * @ / € £

' (single quote)

" (double quote)

‐ (hyphen)

’ (apostrophe)

« »

sont, a, ont, ne, pas, n,et, ou, mais, que, qui, qu, à, aux, sur, dans, en, par, avec, y, il, elle, ils, ells, lui, leurs, son, sa, ses, leur

Italian . , ; : ^ & ! + ‐ = ( ) [ ] { } < > ~ # $ / * @ / € £

' (single quote)

" (double quote)

‐ (hyphen)

’ (apostrophe)

« »

ad, al, allo, ai, agli, all, agl, alla, alle, con, col, coi, da, dal, dallo, dai, dagli, dall, dagl, dalla, dalle, di, del, dello, dei, degli, dell, degl, della, delle, in, nel, nello, nei, negli, nell, negl, nella, nelle, su, sul, sullo, sui, sugli, sull, sugl, sulla, sulle, per, tra, contro, lui, lei, noi, loro, suo, sua, suoi, sue, lo, la, li, le, gli, ne, il, un, uno, una, ma, ed, se, perché, anche, come, dov, dove, che, chi, cui, non, più, quale, quanto, quanti, quanta, quante, quello, quelli, quella, quelle, questo, questi, questa, queste, si, a, c, e, i, l, o, sono, è

Spanish . , ; : ^ & ! + ‐ = ( ) [ ] { } < > ~ # $ / * @ / € £

' (single quote)

" (double quote)

‐ (hyphen)

’ (apostrophe, but it's not used in Spanish)

« »

¿

¡

un, unos, una, unas, el, los, la, las, este, esta, esto, estos, estas,ese, esa, eso, esos, esas, es, son, está, están, hay, y, o, pero, de, en, para, como, con, por, sobre, el, ella, ellos, ellas, se, su, sus, suyo, suya, suyos, suyas

German

. , ; : ^ & ! + ‐ = ( ) [ ] { } < > ~ # $ / * @ / € £

' (single quote)

" (double quote)

‐ (hyphen)

„ “

« »

’ (apostrophe)

[Note: this means that an apostrophe at the end of a word is dropped, and one in the middle of a word for abbreviations collapses the two parts together.]

ein, einer, eine, eines, einem, einen, der, die, das, den ist, sein und, oder durch, als, von, mit, für, am, in, aus er, sie, es, sie ihn ihm, ihr, ihnen sein, siene, ihre

7.5 ESCAPING XML CHARACTERS

Special XML characters in a Registry response are escaped as appropriate, regardless of the technique (escaping or CDATA) used in the original request. The special characters and their escaped representation are

Character Escape

" "

' '

< <

> >

& &

7.6 MAPPING EIDR FIELDS TO DOI FIELDS

Note:

• BaseObjectData is of type eidr:baseObjectInfoType.

• Provenance is of type eidr:provenanceInfoType

• PrincipalAgent is of type eidr:principalAgentType

• PartyResolution is of type eidr:partyResolutionType

DOI kernelMetadata Field DOI Kernel Subfield EIDR Field (Assets only)

referentDoiName /BaseObjectData/ID

primaryReferentType Creation

registrationAgencyDoiName 10.1000/ra‐5

issueDate /Provenance/CreationDate

issueNumber /Provenance/IssueNumber

referentCreation.name primaryLanguage /BaseObject/ResourceName@lang

value /BaseObject/ResourceName

type Always 'title'

In future versions, derived from

/BaseObject/ResourceName@titleClass



DOI kernelMetadata Field DOI Kernel Subfield EIDR Field (Assets only)

referentCreation.identifier Currently used only for aliased objects. (See Resolve().)

Used for AlternateIDs in a future version of this spec.

referentCreation.structuralType /BaseObject/StructuralType

referentCreation.mode /BaseObject/Mode

AudioVisual results in two DOI modes.

referentCreation.character Based on /BaseObject/Mode

Audio ‐> Language

Video ‐>Image

AudioVideo ‐> Both

Exception: object of ReferentType InteractiveMaterial ‐> Other

referentCreation.type /BaseObject/ReferentType

Series ‐> Series

Season ‐> Series

All others ‐> MovingImage (with apologies to InteractiveMaterial and Audio‐only items.

referentCreation.PrincipalAgent name.value /PartyResolution/PartyName/DisplayName

name.type 'Name'

identifier /PrincipalAgent

role based on /PrincipalAgent@role

broadcaster, distributor ‐> Publisher

all others ‐> CorporateCreator

linkedCreation Reserved for future use based on an object's relationships

eidr api overview

Documents