EIDRSYSTEM VERSION1.

0 APIOVERVIEW
2011APRIL11

 Copyright2011bytheEntertainmentIDRegistryAssociation EIDRAPIOverview. Thecontentofthismanualisfurnishedforinformationuseonlyandissubjecttochangewithout noticeandshouldnotbeconstruedasacommitmentbytheEntertainmentIDRegistryAssociation. TheEntertainmentIDRegistryAssociationassumesnoresponsibilityorliabilityforanyerrorsor inaccuraciesthatmayappearinthisdocument. Productsandcompanynamesmentionedmaybetrademarksoftheirrespectiveowners. Feedbackonthisdocumentcanbesenttosupport@eidr.org

EIDRAPIOverview

P a g e |2

Version1.0120110407

TABLEOFCONTENTS
1. DOCUMENTSCOPE.............................................................................................................................. 5 2. GENERALCONVENTIONS.................................................................................................................. 5
2.1 2.2 2.3 2.4 Errors ............................................................................................................................................................ 5 AsynchronousandImmediateCalls................................................................................................................ 7 BatchTransactions ........................................................................................................................................ 7 ModeSummary ............................................................................................................................................. 8

3. OBJECTS.................................................................................................................................................. 8
3.1 CreateandModify......................................................................................................................................... 8 3.1.1. CheatSheetObjectTypes ............................................................................................................................. 9 3.1.2. CheatSheetRelationships .......................................................................................................................... 10 3.1.3. Create............................................................................................................................................................. 12 3.1.4. AddingandRemovingRelationship ............................................................................................................... 12 3.1.5. ModifyingObjects.......................................................................................................................................... 14 3.1.6. Promote ......................................................................................................................................................... 14 3.1.7. Delete............................................................................................................................................................. 15 3.1.8. Alias................................................................................................................................................................ 15 3.1.9. RequestStatus ............................................................................................................................................... 16 3.2 ObjectInformation ...................................................................................................................................... 18 3.2.1. Resolution ...................................................................................................................................................... 19 3.2.2. Traversal......................................................................................................................................................... 21 3.2.3. Queries........................................................................................................................................................... 24 3.2.4. VirtualFields .................................................................................................................................................. 29 3.2.5. Provenance .................................................................................................................................................... 30

4. PARTIES,USERS,ANDPERMISSIONS......................................................................................... 30
4.1 Parties......................................................................................................................................................... 31 4.1.1. Create............................................................................................................................................................. 31 4.1.2. Modify............................................................................................................................................................ 32 4.1.3. AdministrativeTasks ...................................................................................................................................... 33 4.1.4. RetrievingInformation................................................................................................................................... 33 4.2 Permissions ................................................................................................................................................. 36

EIDRAPIOverview

P a g e |3

Version1.0120110407

5. UTILITIES............................................................................................................................................ 38
5.1 DOIProxy .................................................................................................................................................... 38

6. PREDEFINEDOBJECTSANDCONSTANTS ............................................................................... 39
6.1 6.2 6.3 6.4 Tombstones................................................................................................................................................. 39 Errorhandling.............................................................................................................................................. 39 PredefinedParties ...................................................................................................................................... 39 HandlePrefixes ........................................................................................................................................... 39

7. APPENDICES....................................................................................................................................... 40
7.1 SeasonsandEpisodes .................................................................................................................................. 40

7.2 ComplexInheritance.................................................................................................................................... 40 7.2.1. ResourceName............................................................................................................................................... 40 7.2.2. Languages ...................................................................................................................................................... 41 7.3 ModifyingObjects ....................................................................................................................................... 42

7.4 TextProcessing............................................................................................................................................ 42 7.2.3. FieldRules ...................................................................................................................................................... 42 7.2.4. LanguageSpecificFiltering ............................................................................................................................ 44 7.5 7.6 EscapingXMLCharacters ............................................................................................................................. 46 MappingEIDRfieldstoDOIfields................................................................................................................. 46

EIDRAPIOverview

P a g e |4

Version1.0120110407

1.

DOCUMENTSCOPE

ThisisanoverviewofthepublicandadministrativeAPIsforEIDR.Itdoesnotcover Deduplication(aninternalinterface) Bulkregistration(anAPIextensionprovidedbyanEIDRapplication) Analytics Lowleveldatabasemirroring.WiththisprivilegedAPIaclientcanrequestperiodicupdatesfrom theregistryandaskfordetailsofchangesmadeduringaparticulartimewindow.Thecombination ofthesetwoallowsforprimingacopyofthedataandthenkeepingituptodate,aswellastakinga simplesnapshotoftheregistryatanyparticularinstant.(Simplebulkreadofobjectscanbe implementedattheapplicationlevel.) Useraccountmanagement(thoughthismaybeincludedinafutureversionifthirdpartiesare allowedtodevelopapplicationsthatcreateaccounts)

TheregistryinterfaceitselfisRESTbased.ThisdocumentpresentsitasatraditionalproceduralAPI,suchas mightbeusedinaJavaorJavaScriptinterfacebuiltontopoftheunderlyingHTTPandXML.

2. GENERALCONVENTIONS
2.1 ERRORS Standarderrorsare: Authentication: Thesystemcouldnotauthenticatetheuserand/orgroupintherequest. Authorization:Therequesterisnotauthorizedtoperformtheaction,oraccessoneormoreof theDOIsintherequest RegistryReadOnly: TheRegistryisinreadonlymode.Iftheprimarysystemgoesdown,the mirrorsystemsarestillavailableforreading.Certainsystemadministrationtasks(synchronization withabackup,bulkexport,etc.)mayalsohavethisresult. SystemError:Theregistryisunabletodealwiththerequestforsomeinternalreason. 1 InvalidRequest: TherequestURLisinvalid,orcontainsunrecognizedorinvalidHTTPheaders, orcontainsunrecognizedorinvalidinformation.

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

EIDRAPIOverview

P a g e |5

Version1.0120110407

BadDOI:TherequestcontainsaDOIthatissyntacticallycorrectbuthasaninvalidchecksumoris notrecognizedbythesystem.SyntacticallymalformedDOIsgenerateaSyntaxError.Thebad DOIisincludedasadetail. SyntaxError:TheXMLintherequestdoesnotpassschemavalidation. ValidationError:TheXMLintherequestissyntacticallycorrectbutfailsothervalidationrules, ortherequestwouldresultinanobjectthatviolatesthevalidationrules,ortheobjectpassedinis inappropriateforthecall.Thedetailfieldcanbe: o IncompatibleCreationTypes:AcalltoGetModificationBase() failed becausemetadataneededfortherequestedtypeisnotpresentontheobject. NotRemovable: Returnedonfailedattempttoremovearelationship.Thiscan occureitherwhentherelationshipdoesnotexist,orwhenitsremovalwouldresultin aninvalidobjectorhierarchy. AliasNotAllowed: AnaliasedDOIwaspassedtoafunctionthatdoesntaccept aliases. IncompatibleAliasTarget:ADOIisbeingaliasedtoanincompatibleobject. NotInDev:thecallfailedbecauseanattemptwasmadetopromoteanobjectthat wasnotintheInDevstate.AlsoincludestheoffendingDOIasadetail.See Promote().

o o

Othererrorsare: BadToken:ThetokensenttoGetStatus()wasnotrecognized. BadQuery: Thequerystringwasmalformed. NoParent: TheobjectsenttoGetParent()isitselftherootofthetree. NoChildren: TheobjectsenttoGetChildren()isitselfaleafofthetree. ResultTooLong: AresultwastoolargetofitinaRESTresponse.Thiscanbecausedby requestingtoolargeapagesizeinqueries. DuplicateParty:ReturnedbyCreateParty()iftherequestistocreateaduplicateParty.The duplicatepartyisreturnedasadetail. DuplicateUser:ReturnedbyCreateUser()iftherequestistocreateaduplicateUser.The duplicateuserisreturnedasadetail. BadParty:ThepartyIDsubmittedaspartofarequestwasinvalid. BadUser:TheuserIDsubmittedaspartofarequestwasinvalid. P a g e |6 Version1.0120110407

EIDRAPIOverview

 2.2 ASYNCHRONOUSANDIMMEDIATECALLS Callscanbeimmediate(theresultisreturnedimmediately)orasynchronous(thecallreturnsatokenwhich isusedtodiscoverthestatusoftherequest).Notallcallssupportasynchronousresults;thosethatdohave aflagintheinterfacespecifyingwhichmodetouse. Allcallsmustbeexplicitlyspecifiedasimmediateorasynchronous;thereisnodefaultingmechanism. Ingeneral,onlycallsthatrequireconfirmationfromthededuplicationsystemcanbeasynchronous. Create() Promote() AddRelationship() RemoveRelationship() RemoveSpecificRelationship() ReplaceRelationship() Modify()

Allothercallsareimmediatemodeonly.(Thesecallsmaystillhavesomedelay,basedontheloadon theRegistry,butitshouldbeassumedtobeminimal.) Delete() Alias() GetModificationBase() Queries,traversals,resolution

2.3 BATCHTRANSACTIONS TheasynchronousversionsofCreate(),Promote(),Modify(),andDelete()takeoneormore setsofinputparameters.Thismeansabatchcanonlycontainonekindofoperation.Astatustokenis returnedforeachiteminthebatch,andoneforthebatchitself.Ifthebatchcontainsonlyoneitem,the batchtokenandtheitemtokenarethesame.Eachiteminthebatchisprocessedseparately,andthereisno guaranteethattheitemswillbeprocessedinthesameorderastheyexistinthebatch.Thus,batcheswith operationsthatdependoneachother(e.g.,creatingaseriesanditsseasonsinasinglebatch)willhave unpredictableresults.

EIDRAPIOverview

P a g e |7

Version1.0120110407

Submissionofthebatchisauthenticated;authorizationchecksaredoneoneachelementofthebatch.If thereisanerrorprocessinganiteminthebatch,thatitemfails,andqueryingitsstatuswillreturn appropriateinformation.Processingoftheotheritemsinthebatchisnotaffected. 2.4 MODESUMMARY Note:Incaseoflackofclarityinthetextforindividualfunctions,thistableisdefinitiveforbatchand immediate/asynchronoussupportforeachfunction. Function

Create() Promote() AddRelationship() RemoveRelationship() RemoveSpecificRelationship() ReplaceRelationship() Modify() Delete() Alias() GetModificationBase() Queries,traversals,resolution

Batchable?
Yes Yes No No No No Yes Yes No No No

Mode
ImmediateorAsynchronous ImmediateorAsynchronous ImmediateorAsynchronous ImmediateorAsynchronous ImmediateorAsynchronous ImmediateorAsynchronous ImmediateorAsynchronous Immediateonly Immediateonly Immediateonly Immediateonly

3. OBJECTS
3.1 CREATEANDMODIFY Objectsarecategorizedinfourways: Type:Typesareoftwosortsbasicandderived.TheBasicTypecoverstheminimalpossibleobject.It issufficientfordescribingawidevarietyofassets.DerivedTypesincludealltheinformationinthe BasicType,andaddextrainformationfordescribingmorecomplexobjects.TheDerivedTypesinEIDR areEdit,LanguageVariant,Series,Season,Episode,Composite,Clip,Encoding,andInteractiveMaterial.

EIDRAPIOverview

P a g e |8

Version1.0120110407

Inheritance:Objectsintheregistryarelogicallyagraph.Anobjectcanonlyhaveoneparent.Only informationfromtheparent'sbasictypefieldscanbeinherited.Thisworldviewusesstandard computerscienceterminologyancestorsanddescendents,rootobjectsandleafnodes.

Dependence:Anobjectmaydependonanotherobjectinsomeway,byincludingareferencetoit. Thereisnoinheritance,andthemetadataofdependentsandobjectsonwhichtheydependhaveonly coincidentalrelationshiptoeachother.Forexample,whenencodingAreferstoencodingBby reference,AisdependentonB,andwhenCompositeCincludesClipK,CisdependentonK.

Relationships:Arelationshipisacasualtermforthewayinwhichtwoobjectsareconnected. Relationshipsaredescribedusingtwoormoreobjectsandsomemetadata.Theyareclassifiedas: o Lightweightrelationshipswhichhavenoinheritance;theobjectstowhichtheyreferdonot influencetheunderlyingnatureoftheobjectonwhichtherelationshipexists.Theserelationships areusedprimarilywhenmovingaroundtheobjecttreeandconnectingobjecttreestoeachother. ThelightweightrelationshipsareIsPackagingOf,IsPromotionFor,IsAdjunctTo,and IsAlternateContentFor. Dependencerelationshipswheretheobjectstowhichtherelationshiprefershaveastrong bearingonthebasicnatureoftheobjectonwhichtherelationshipexists.Importantly,thismeans thattheobjectsreferredtointherelationshipneedtobetakenintoaccountwhencheckingfor duplicateswhenanobjectiscreatedormodified.ThedependencerelationshipsareIsCompositeOf andIsEncodingOf. Inheritancerelationshipswheretheobjectonwhichtherelationshipexistscaninheritbasic metadatafieldsfromtheobjecttowhichtherelationshiprefers.Withtheexceptionis IsLanguageVariantOf,onlyoneinheritancerelationshipmayexistonanobject.TheInheritance relationshipsareIsSeasonOf,IsEpisodeOf,IsEditOf,IsLanguageVariantOf,IsEncdoingOf,andIsClipOf.

Notallcombinationsoftype,inheritance,anddependencearelegal.TheValidationRulesarethenormative descriptionoflegalandillegalcombinations. 3.1.1. CHEATSHEETOBJECTTYPES Inordertoreducecomplexity,theAPItocreateandmodifyobjectsisconstrainedinseveralways,rather thanexposingagenericdatastructuretobefilledin.Nonetheless,alllegalcombinationsoftypeand inheritancecanbecreatedandmodifiedusingtheAPI,andalllegitimaterelationshipstootherobjectscan beaddedandremoved. ThesearetheflavorsoftheCreate()call,whichusesCreationTypeasoneifitsarguments.

EIDRAPIOverview

P a g e |9

Version1.0120110407

Creation of Objects
BasicObjects withIsSeasonOfinheritance relationship withinformationforderived typeInteractiveMaterial withinformationforderived typeSeries withIsEncodingOfinheritance relationship withIsEditOfinheritance relationship withIsClipOfinheritance relationship withIsLanguageVariantOf inheritancerelationship withIsEpisodeOfinheritance relationship withIsCompositeOf dependentrelationship Referenttypecanbe:TVShow, Movie,Short,Web OnlywaytocreateSeasonreferent type Onlywaytocreate InteractiveMaterialreferenttype OnlywaytocreateSeriesreferent type

Creation Type

CreateBasic CreateSeason CreateInteractive CreateSeries

Onlywaytocreateanobjectthathas CreateEncoding IsEncodingOfrelationship Onlywaytocreateanobjectthathas CreateEdit IsEditOfrelationship Onlywaytocreateanobjectthathas CreateClip IsClipOfrelationship Createsachildwitha IsLanguageVariantOfrelationship CreateLanguageVariant

Onlywaytocreateanobjectthathas CreateEpisode IsEpisodeOfrelationship Onlywaytocreateanobjectof referenttypeComposite CreateComposite

Onceanobjectiscreated,thereisnowaytochangeitsnature.Forexample,thereisnocalltoremove seriesinformationfromanobjectandbeleftwithabasicobject. Anobject'sreferenttypeisimmutableaftertheobjectiscreated. 3.1.2. CHEATSHEETRELATIONSHIPS Hereisthesummaryofhowrelationshipscaninteractwitheachother. Relationship

IsSeasonOf IsEpisodeOf IsEditOf IsClipOf

Type
Inheritance Inheritance Inheritance Inheritance

Can co-exist with

IsCompositeOf IsLanguageVariant IsLanguageVariant

Can be added after creation

No No No No

Removable?
No No No No

EIDRAPIOverview

P a g e |10

Version1.0120110407

Relationship
IsCompositeOf

Type
Dependence

Can co-exist with

IsEpisodeOf

Can be added after creation

toepisodes tobasicobjects notofreferent typeComposite

Removable?
Yes,ifthereferenttypeisnot Composite

IsEncodingOf

Inheritance Dependence Inheritance

IsLanguageVariant

No

No

IsLanguageVariant

Clip Encoding Edit

Yes,provided someother inheritance relationship alreadyexistson theobject;both relationships musthavethe sameParent Yes

Canberemovedifitisnottheonly inheritancerelationshiponan object;thiscanoccurifanother creationtypeisusedandalanguage variantisaddedtoitafterthefact;if thelanguagevariantiscreatedfirst, therearenolegaladditionstomake toit.

IsPromotion

Lightweight

Any

Multipleinstancesallowedonan object Multipleinstancesallowedonan object Multipleinstancesallowedonan object Multipleinstancesallowedonan object

IsPackaging

Lightweight

Any

Yes

IsAlternateContent

Lightweight

Any

Yes

IsAdjunctContent

Lightweight

Any

Yes

Herearethelegalwaystoaddrelationshipsafterobjectcreation: Addition of IsLanguageOf Inheritance Relationship

BasicObject BasicObject BasicObject withClipinheritancerelationship withEncodinginheritancerelationship withEditinheritancerelationship LanguageandClipmusthavesameparent LanguageandEncodingmusthavesameparent LanguageandClipmusthavesameparent

Addition of IsCompositeOf Dependent Relationship

BasicObject BasicObject withIsEpisodeOfinheritancerelationship BaseobjectwillnotbeofreferenttypeComposite

EIDRAPIOverview P a g e |11 Version1.0120110407

ThelightweightrelationshipsIsPromotion,IsPackaging,IsAlternateContent,andIsAdjuctContentcanbe addedtoanyobjectatanytime. Anyrelationshipthatcanbeaddedcanberemoved,withthefollowingexceptions: IsLanguageOfisnotremovableifitistheobject'sonlyinheritancerelationship.Thisisthecase whenthelanguagevariantwassuppliedatcreationtime. IsCompositeOfisnotremovableiftheobject'sreferenttypeisComposite.Thiswillbethecase whenthecompositeinformationwassuppliedatlanguagecreationtime. Seetheappendixforexamplesofmodifyingobjects. 3.1.3. CREATE Create(creationType, creationData, mode) Returnsastatustoken,foruseinGetStatus()calls.Objectsthatarecreatedwithastatusof InDevarenotcheckedbythededuplicationservice;theyaresentfordeduplicationwhenthey arepromotedtoValid.(SeethePromote()call.) Modeisoftypeeidr:requestModeTypeandcanbeeitherasynchronousorimmediate. IntheRESTimplementation,thisispassedinthehttpheadersratherthanintheXMLforthe request. Batchinputallowed. ThereisadatatypedefinedintheschemaforeachcreationType,andthetwomustmatchin thecall.Forexample,tocreateaseriesyouwoulduseCreateSeriesand CreateSeriesData.ThesetypesaresubsetsofFullObjectInfoTypeandareusedtolimit thescopeformistakesforcommonoperations. Errors:Standarderrors;alsoseeGetStatus() 3.1.4. ADDINGANDREMOVINGRELATIONSHIP Adding,removing,andreplacingrelationshipsislimitedtothoserelationshipsthatarenotdeterminantsof theobject'snature.Forexample,youcan'taddIsSeasonOf,orremoveIsEpisodeOf. AddRelationship(DOI, relationshipType, relationshipData) Returns:astatustoken,foruseinGetStatus()calls.AValidationErrorisreturned(viathe status)iftherelationshipcannotbelegallyaddedtotheobject. relationshipTypeandrelationshipDataareoneofthefollowingpairs: CompositeRelationship, compositeInfoType LanguageRelationship, languageConstructionInfoType P a g e |12 Version1.0120110407

EIDRAPIOverview

PackagingRelationship, packaginInfoType AdjunctRelationship, adjunctContentInfoType PromotionalRelationship, promotionInfoType AlternateContentRelationship, alternateContentInfoType

RemoveRelationship(DOI, relationshipType) Returns:astatustoken,foruseinGetStatus()calls.ANotRemovable errorisreturned(via thestatus)iftherelationshipcannotbelegallyremovedfromtheobject. LegaltypesareasforAddRelationship(). Allrelationshipsofthespecifiedtypeareremoved.(Onlylightweightrelationshipscanexistmultiply onanobject,however.) IsCompositeOfisonlyremovableiftheobject'sreferenttypeisnotComposite. Errors:standarderrors RemoveSpecificRelationship(DOI, relationshipType, targetDOI) Returns:astatustoken,foruseinGetStatus()calls.ANotRemovable errorisreturned(via thestatus)iftherelationshipcannotbelegallyaddedtotheobject. relationshipTypemustbeoneofthelightweightrelationships.Ifthereisarelationshipof thattypewithtargetDOI,itisremoved. Errors:standarderrors ReplaceRelationship(DOI, relationshipType, relationshipTypeData) Returns:astatustoken,foruseinGetStatus()calls. relationshipTypeandrelationshipDataareoneofthefollowingpairs: CompositeRelationship, compositeInfoType LanguageRelationship, languageConstructionInfoType

NotethatrelationshipTypemustnotbeoneofthelightweightrelationshipstherecouldbe multipleofthem,andsotheAPIsupportsthisthrougharemovefollowedbyanadd(ratherthan encruftingtheAPIwithanextraparametertodifferentiatethem).Thisremoveandaddprocedure isnotrecommendedfortherelationshipsthatareinvolvedinuniquelyidentifyinganasset,since theremoveoperationcouldcausetherecordinitsintermediatestatetobeaduplicateofanother object. EIDRAPIOverview P a g e |13 Version1.0120110407

TheexistingrelationshipinformationforrelationshipTypeontheobjectisreplacedbythe newrelationshipTypeData. IfthereplacedrelationshipisLanguageRelationship,theParentfieldofanyother inheritancerelationshipontheobjectisreplacedwiththeParentfieldof relationshipTypeData. Errors:standarderrors 3.1.5. MODIFYINGOBJECTS Modifyingobjectsisdonebygettingcurrentinformationontheobject,modifyingit,andresubmittingit. GetModificationBase(DOI, creationType) ReturnsobjectmetadataforcreationType.Theschemasusedforthereturnarethesameas theoneusedforcreatinganobjectofthattype. Forexample,consideranobjectcreatedusingCreateSeries. GetModificationBase(DOI, CreateBasic)returnsjustthefieldonthebasicobject,and GetModificationBase(DOI, CreateSeries)returnsallthemetadataneededtocreatea series. TheunderlyingobjectmustbeabletosupportallthefieldsneededbycreationType.Itisincorrect tocallGetModificationBase(DOI, CreateComposite)ontheobjectintheprevious example. Errors:standarderrorsandIncompatibleCreationTypes. Modify(DOI, creationType, creationTypeData) Returns:astatustoken,foruseinGetStatus()calls.Therequestispassedtothededuplication systeminthesamewayasaregularCreate()call 2 .Itispossible,thoughnotnecessarilysafe,to passindatanotreturnedfromGetModificationBase().Iftheobjecthasmultipleinheritance relationshipsandParentischangedincreationTypeData,theParentfieldoftheother inheritancerelationshipsischangedaswell. Batchinputallowed. Errors:standarderrorsandIncompatibleCreationTypes. 3.1.6. PROMOTE ThiscallturnsanInDevobjecttoaValidobject.Onceitismade,thereferencedobjectisvisibletothe worldatlarge.

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

EIDRAPIOverview

P a g e |14

Version1.0120110407

InDevobjectsdonotgothroughthededuplicationsystemwhentheyarecreated,butarecheckedfor duplicateswhenpromoted.ThereturnedtokencanbeusedinGetStatus()calls. Promote(DOI, mode) Returns:statustoken. Modeisoftypeeidr:requestModeTypeandcanbeeitherasynchronousorimmediate. IntheRESTimplementation,thisispassedinthehttpheadersratherthanintheXMLforthe request. Batchinputallowed. InDevobjectsdonotgothroughthededuplicationsystem,butarecheckedforduplicateswhen promoted.ThereturnedtokencanbeusedinGetStatus()calls. Ifthecallissuccessful,thePromoteandViewACLsareremovedfromtheobject,anditis viewablebyanyuser. ReturnsstandarderrorsandNotInDev. 3.1.7. DELETE Ideally,everyDOIispermanent.Sometimes,however,anitemreallydoesneedtobedeleted(forexample, acancelledprojectatadefunctproductionhouse),orissobadlywrongitshouldberemoved. EIDRdoesnotdeletetheDOIitself;rather,itmakestheDOIanalias(seebelow)forastandardtombstone object. Delete(DOI) ReturnsstatustokenforuseinGetStatus() ForcestheDOItoresolvetoatombstone. TheLastModifiedfieldintheprovenanceforadeletedDOIisthetimeatwhichtheobjectwas deleted. Onlyanobjectwithnorelationshipsandnodependentscanbedeleted.Use FindDescendents()andGetLightweightRelationships()(orresolveto eidr:simpleDataInfoType)tofindtherelationshipsandGet Dependents()for dependentitems. Batchinputallowed Errors:standarderrorset,anddependencyerrors 3.1.8. ALIAS AnaliasisasimpleindirectionfromoneDOItoanother.Analiasisnotintendedasageneraltool;rather,it shouldonlybeusedforcorrectingerrors.Forexample,ifafilmmistakenlygetstwoIDs(perhapsbecauseof problemsinvolvingworkflowandworkingtitles)theincorrectonecanbealiasedtothecorrectone.Asa concreteexample,ifawrongIDgetsburnedontoaBDlivediskandissubsequentlycorrectedbyaliasing, EIDRAPIOverview P a g e |15 Version1.0120110407

thatIDcanstillberesolvedbytheserverinresponsetoclientrequestsforthedeprecatedID.Theserver cantreatthecontentasvalidsimplybecausetheIDisresolvable,oraddextrachecking. Thereareconstraintsplacedonthetypesoftheoldandnewobjects: Anythingcanaliastoabasicobject. Aseriesobjectmustaliastoaseriesobjectorabaseobject. Aseasonobjectmustaliastoaseasonobjectorabaseobject.

ConvertToAlias(OldIdentity, NewIdentity) SubsequentreadsofOldIdentityreturndatafromNewIdentity.Anyotheraction(suchas atraversalorarootedquery)requestedonOldIdentitywillgenerateanerror. OldIdentityremainsavalidIDinthesystem,anditisstillresolvable. Afterthiscall: Readingdata o o o o AllresolutionsrelatedtoOldIdentitywillreturndatafromNewIdentity, unlessthecallhasafollowAliasflagsettofalse. Allothercallsreturnanerror;theapplicationshouldfollowthealiastogetthe actualDOI,andthenuseit. TheLastModifiedfieldintheprovenanceforanaliasedDOIisthetimeatwhich theobjectwasaliased. Applicationhint:iftheDOIinthemetadatafromaresolutionisnotthesameasthe inputDOI,theinputDOIhasbeenaliased.

Queries:AllqueriesrelativetothealiasedDOIwillreturnanerror.

Onlyanobjectwithnorelationshipsandnodependentscanbealiased.Use FindDescendents()andGetLightweightRelationships()(orresolveto simpleDataInfoType)tofindtherelationshipsandGet Dependents()fordependent items. Errors:standarderrorset,HasDependents,andIncompatibleAliasTarget 3.1.9. REQUESTSTATUS Allasynchronouscallsreturnatokenthatcanbeusedtoquerythestatusoftherequest. GetStatus(token, page, pageSize, continuationToken) Errors:standarderrors,BadQuery,andResultTooLong Thepagingparametersareusedasfollows:

EIDRAPIOverview

P a g e |16

Version1.0120110407

ResultsarereturnedwithpageSizeobjectsperbatch. Thepagethpageofthatsizeisreturned.Page1isthefirstpage.Page0isarequestforall results. ContinuationTokenshouldbeavaluereturnedbythepreviouscallusingthisquery string,oremptyifthisisthefirstcallintheset.

Returns(token, status)elementiftoken isnotabatchtoken. Iftoken isabatchtoken,returns PageSizemaxsizeofreturnedchunks(sameasinputparameterpageSize) MySizesizeofthischunk(equaltopageSizeexceptforthelastpage TotalPagestotalnumberofpagesthatcanbereturned PageNumnumberofthereturnedpage TotalResultstotalnumberofavailableresults ContinuationTokenreturnedbyimplementationsthatinternallycacherequeststate. ItshouldbepassedinastheContinuationTokenargumentonsubsequentcallsasan accelerator.

Alistofthe(token, status)elementforeachiteminthebatchthatfallsinthe returnedpageofresults Valuesforatokenrepresentingabatch BatchReceivedthebatchhasbeenfullyreadin,butnostatusforitssub elementsisavailable BatchQueuedthebatchisbeingprocessed,andstatusisavailableforallitssub elements BatchInvalidtherewasanerrorinthebatch;oneofthestandarderrorsis alsoreturnedasadetail

Valuesfortokensforindividualitemsinthebatch: Success:Whentherequesthassucceeded,forexamplebycreatinganewobject ordeletinganoldone.ThedetailfieldcontainstheDOIassociatedwiththe successfuloperation:anewDOIforcreation,andthepassedinDOIinothercases. Duplicate:Whenaduplicateorpotentialduplicatesarefoundduringcreate, modify,orpromote.ThedetailfieldcontainsoneormoreDOIsofitemsdetectedas duplicates;theIDsforallduplicatesarereturned. Pending:Whentheregistryiswaitingtofinishanoperation,buthasnotyethad anyerrors;inthecaseofcreate,modify,andpromoteitmayhaveasadetailalist ofDOIsforoneormorepotentialduplicates.

EIDRAPIOverview

P a g e |17

Version1.0120110407

Failure:Whentherequestfails,forexampleafteranattempttocreatea duplicateitem. Error: Addsoneoftheerrorvaluesasadetail.

ThecallitselfcanreturnanyofthestandarderrorsoraBadToken error. GetStatus(Registrant, filter, token, page, pageSize, continuationToken) GetStatus(User, filter, token, page, pageSize, continuationToken) ThelastfourargumentsaretreatedastheyareforGetStatus(). Filtercanbe: Status: legal-status-value:Onlytokensthatmatchthesuppliedvalueare returned. After: date-time:Onlytokensissuedafterthesuppliedtimearereturned. Range: date-time-start date-time-end:Onlytokensgeneratedbetweenthe twodatesarereturned.

Legalcombinationsare: Nofilter Statusonly Afteronly Rangeonly Statusandafter StatusandRange

Registrantreturnsapaginatedlistof(token, status)foreverytokenbelongingto RegistrantthatmatchesFilter.AtokenbelongstoaregistrantifauserinRegistrants groupmaderequestwithwhichitisassociated. Userreturnsapaginatedlistof(token, status)foreverytokengeneratedbyarequestfrom UserandmatchingFilter. 3.2 OBJECTINFORMATION ThereareseveralwaysofgettinginformationaboutaDOI: ResolutionprovidesvariousviewsofthemetadataassociatedwithaparticularDOI. TraversalprovidesinformationabouthowtheDOIfitsintotheobjecthierarchy.

EIDRAPIOverview

P a g e |18

Version1.0120110407

QueriesreturnDOIswithmetadatamatchingcertaincriteria. ProvenancereturnsinformationabouttheDOI'screationandmodification.Itisaspecialcaseof resolution.

3.2.1. RESOLUTION Resolve(DOI, resolutionType, followAlias) Returns:metadataassociatedwiththeDOI. IffollowAliasistrue(thedefault),informationreturnedisfromtheobjecttowhich analiasedrefers,notfromthealiasedobjectitself. IffollowAliasisfalseandtheobjectisnotaliased,theinformationlikewisecomes fromtheobjectitself. IffollowAliasisfalseandtheobjectisaliased,anAliasContinuationis returned. Notes: Analiascanbedetectedasfollows: o WhenfollowAliasistrue,bycomparingtheDOIfieldofthereturnedobjectwiththe inputDOI;iftheydiffer,theinputDOIisaliased. WhenfollowAliasisfalse,bydetectingthatanAliasContinuationhasbeen returnedratherthanformattedmetadata. Aliasesarefollowedforfivelevels.Ifthefinalitemisstillaliased,an AliasContinuationobjectisreturnedwhichcontainsthelastaliasedDOIfoundand theitemtowhichitisaliased.

ForresolutionType,thedefinedvaluesandbehaviorareasfollows: ResolutionType
DOIKernel

Follow Alias?
true

Return Value
Returnsmetadataformattedasdoi:kernelMetadata. Ifthealiaschainistoodeep,returnsan AliasContinuation. ForanInDevobject,returnsastructuraltypeofrestricted.The object'snameis"No information available". Foradeletedobject,returnsastructuraltypeof'Restricted',and fieldvaluesfromthestandardtombstoneobject.

EIDRAPIOverview

P a g e |19

Version1.0120110407

ResolutionType
DOIKernel

Follow Alias?
false

Return Value
Iftheobjectisaliasedthisreturnsdoi:kernelMetadata where: structural type is 'Restricted' title is 'aliased' referentCreation.identifier.typeisDOI referentCreation.identifier.value is the DOI to which the object is aliased

Foradeletedobject,returnsastructuraltypeof'Restricted',and fieldvaluesfromthestandardtombstoneobject. Simple true Returnsmetadataformattedaseidr:simpleDataInfoType. Thisistheformatreturnedbyqueriesandtraversals. Ifthealiaschainistoodeep,returnsanAliasContinuation. Simple false Iftheobjectisnotaliased,returns eidr:simpleDataInfoType. Iftheobjectisaliased,returnsAliasContinuation.(See above.) Full true Returnsmetadataformattedaseidr:fullObjectInfoType. Ifthealiaschainistoodeep,returnsanAliasContinuation. Full false Iftheobjectisnotdeletedoraliased,returns eidr:fullObjectInfoType. Iftheobjectisaliased,returnsAliasContinuation.(See above.) SelfDefined true Returnsmetadataformattedas eidr:allSelfDefinedInfoType. Ifthealiaschainistoodeep,returnsanAliasContinuation. SelfDefined false Iftheobjectisnotdeletedoraliased,returns eidr:allSelfDefinedInfoType. Iftheobjectisaliased,returnsAliasContinuation.(See above.) Inherited true Returnsmetadataformattedas eidr:allInheritedInfoType. Ifthealiaschainistoodeep,returnsanAliasContinuation. Inherited false Iftheobjectisnotdeletedoraliased,returns eidr:allInheritedInfoType. Iftheobjectisaliased,returnsAliasContinuation.(See above.).

EIDRAPIOverview

P a g e |20

Version1.0120110407

ResolutionType
Provenance

Follow Alias?
true

Return Value
Theprovenancerecordforobject(withthealiaschainfollowed)as eidr:provenanceInfoType. Ifthealiaschainismorethan5deep,returnsan AliasContinuationobject.

Provenance

false

Theprovenancerecordfortheobjectitselfas eidr:provenanceInfoType.The LastModificationDatefieldisthedatetheobjectwas aliasedordeleted.

SeetheAppendixfordetailsonthecomplexinheritancetypes(forResourceNameand languages.) 3.2.2. TRAVERSAL TraversalsareusedfordiscoveringhowtheDOIfitsintothegraphthatrepresentsitsrelationshiptoother objects. Traversalsstopatthefirstobjectforwhichtherequesterdoesnothavereadpermission.Thestandard PermissionerrorisusedonlyforpermissionerrorsontheDOIintheoriginalrequest. Traversalsalwaysfollowaliases. Alltraversalsreturnresultsindepthfirstorder. FindAncestors(DOI, list of referentTypes, list of structuralTypes, list of relationshipTypes) Returnsalistof(simpleData, generationsAbove)forallancestorswhichmatchoneofthe referenttypes,oneofthestructuraltypes,andoneoftherelationshiptypes.Emptylistsmatch anything.Thesearchstopswhenanobjecthasnoancestors,andonlyancestorsthatcountfor inheritanceareconsidered(i.e.,noneofthelightweightrelationshipscount). generationsAboveis1foraparent,2fortheparent'sparent,etc. Theobjectitselfisnotreturned. Recallthatobjectscanonlyinheritfromoneparent. Examples: FindAncestors(DOI, "", "", "")findsalloftheobject'sancestors. FindAncestors(DOI, "", "", "IsEditOf")findsallancestorsthatareeditsofa predecessor.

FindDescendants(DOI, list referentTypes, list of structuralTypes, list of relationshipTypes) EIDRAPIOverview P a g e |21 Version1.0120110407

Returnsalistof(simpleData, generations above)foralldescendantswhichmatchoneof thereferenttypes,oneofthestructuraltypes,andoneoftherelationshiptypes.Emptylistsmatch anything.Thesearchstopswhenanobjecthasnodescendants,andonlyitemsthatcaninherit considered(i.e.,noneofthelightweightrelationshipscount). generationsBelow is1forachild,2forachild'schild,etc. Theobjectitselfisnotreturned. Recallthatobjectscanonlyinheritfromoneparent. Examples: FindDescendants(DOI, "")findsalltheDOIsdescendants. FindDescendants(DOI, "digital","","IsEncoding")findsalltheencodings descendedfromtheDOI. FindDescendents(DOI, "","season")findsalltheseasonsdescendedfromDOI. GetDependentObjects(DOI) Returnsalistofeidr:simpleDataInfoTypeforDOIsthatdependontheinputDOIthatare notpartofaninheritancerelationshiporalightweightrelationship. ThiscanbeusedtofindcompositesandencodingsthatincludeaparticularDOI. Theremainingtraversalfunctionsareprovidedasaconvenience;theycanallbeimplementedattheclient byparsingtheresultsofresolutionsandtheabovetraversals. GetSeriesAncestry(DOI) Returnseidr:seriesAncestryType,whichis: eidr:simpleDataInfoTypefortheDOI eidr:simpleDataInfoType and eidr:episodeInfoTypeforthenearest ancestor(whichcanbetheinputDOI)thathasepisodedataonit.Notpresentifthereisno suchancestor. eidr:simpleDataInfoType and eidr:seasonInfoTypeforthenearest ancestor(whichcanbetheinputDOI)thathasseasondataonit.Notpresentifthereisno suchancestor. eidr:simpleDataInfoType and eidr:seriesInfoTypeforthenearest ancestor(whichcanbetheinputDOI)thathasseriesdataonit.Notpresentifthereisno suchancestor. P a g e |22 Version1.0120110407

EIDRAPIOverview

Thevalidationrulesenforcethattherecanbenomorethanoneancestorofeachofthetypes. ThisfunctionisintendedforusebyUIs,managementreports,andsoon. GetLightweightRelationships(DOI) ReturnsthelistofDOIstowhichtheinputDOIhasanoninheriting(i.e.'lightweight')relationship. Eachelementinthelistcontains: eidr:simpleDataInfoType fortherelatedDOI thetypeoftherelationship(IsAdjunct,etc.) theclassoftherelationship(e.g.,Outtake) GetRemotestAncestor(DOI) Returnseidr:simpleDataInfoTypeandgenerationsAboveforthemostdistant ancestor. Iftheinputobjecthasnoancestors,theinputobjectisreturned. Iftheobjecthasancestors,thisistheequivalentoflookingforthehighestnumbered generationsAboveinthereturnvaluesfromFindAncestors(DOI, "", "", ""). GetLeafDescendants(DOI) Returnseidr:simpleDataInfoTypeandgenerationsBelowforalldescendantsthathave nodescendantsoftheirown.NotethatgenerationsBelow maynotbethesameforallleaf nodes. Iftheinputobjecthasnodescendants,theinputobjectitselfisreturned. Iftheobjecthasdescendants,Thiscanalsobedonebyinterpretingtheresultsfrom GetDescendants(DOI, "", "", ""),butthatisalittletrickysincenotallleaf descendantswillbeatthesamelevel;youreallydohavetobuildasimpletreefromthereturned values. GetParent(DOI) Returnseidr:simpleDataInfoTypefortheinputDOI'sparent. ReturnsanerrorofNoParentiftheinputobjectisatthetopofatree. ThisisusefulifallyouhaveisaDOI,notanyofitsmetadata,andwanttoknowitsparent.Itcanbe doneanywaybylookingforgenerationsAbove=1intheresultsofGetAncestors(DOI, "", "", ""). GetChildren(DOI)

EIDRAPIOverview

P a g e |23

Version1.0120110407

Returnseidr:simpleDataInfoType foralloftheinputDOI'simmediatedescendants. ReturnsanerrorofNoChildreniftheinputobjectisaleafofatree. ThiscanbeimplementedbylookingforgenerationsBelow=1intheresultsof GetAncestors(DOI, "", "", ""). 3.2.3. QUERIES OVERVIEW Thequeryfacilitytakesasetofmetadatacriteriaasinputandreturnseidr:simpleDataInfoTypefor allobjectsthatmatchthosecriteria.Thesimplestquerytestsasinglemetadatafield.Morecomplex queriescanbebuiltupbygroupingsimplequeriestogetherwithstandardlogicalexpressions. ThemetadatafieldstobetestedarerepresentedwithasubsetofXPathnotationthatsupportsonly completepathstoelementsandattributes.TheXPathusedinqueryrequestscanbebasedon: Intheseexamplestheparenthesesarenotstrictlynecessary,butimprovelegibility.NotethatXMLatthe protocollevelrequiresescapingofspecialcharacters(<,>,etc.),althoughproceduralimplementationsof theAPImayhidethatfromtheapplication. Thisqueryfindsallobjectslongerthan20minutesandshorterthan40minutes:
(/FullMetadata/BaseObjectData/ApproximateLength > PT20M00S) AND (/FullMetadata/BaseObjectData/ApproximateLength < PT40M00S)

/FullMetadata,whichisoftype fullObjectInfoType:Thisqueriesacrossobjects' inheritedmetadata. /ProvenanceMetadata,whichisoftype provenanceInfoType:Thisqueriesacross objects'provenancemetadata

Thisfindsallrecordsmodifiedin2010.(Seebelowfortheprecisionofdatecomparisons.)
(/ProvenanceMetadata/LastModificationDate = 2010)

Thereareseveralkindsofsimplequeries,notallofwhichareapplicabletoallfields. ExactValue:ThesequeriesuseISandISNOT.Theyareapplicableto FieldscontainingDOIs Fieldscontainingcontrolledvocabulary Certaintextfields(seetheTextProcessingAppendix)

ExactValuelanguage:ThisspecialcaseofExactValuefieldsforlanguagefieldsusesISandISNOTand behavesasfollows: Ifonlyapredashcomponentissuppliedinthequery,itmatchesanythingwiththatprefix. Ifthelanguagecodeinthequeryhasainit,itonlymatchesanotherfieldthatisexactlythesame. Examples: P a g e |24 Version1.0120110407

EIDRAPIOverview

o o

esmatchesobjectsthathavees,esES,andes419 deCHmatchesdeCH,butnotdeordeDE.

Order:Queriesonthesefieldscanbedoneusingcomparisons(<,<=,>=,>)aswellasequalityandinequality (=,<>) FieldscontainingIntegers FieldscontainingDates FieldscontainingDurations

Existence:Theexistenceofafieldcanbequeried.Thisisusefulforoptionalelementsthatrepresentlarge optionalsubblocks(e.g.thethecomponentencodingsinanEncoding.)Inversion1.0oftheRegistry,EXISTS issupportedonthesefields:SubtitleInfoBlock,AudioInfoBlock,VideoInfoBlock,

InteractiveInfoBlock,WrapperInfoBlock,LanguageVariantInfo/Add, LanguageVariantInfo/Replace

Forexample,thisfindsallobjectsthathaveinformationaboutseparatelyencodedsubtitles:
(/FullMetadata/ExtraObjectMetadata/EncodingInfo/SubtitleInfoBlock EXISTS)

TextMatching: Textqueriesarecaseinsensitive. Boththetextinthequerystringandthetextstoredintheregistryaregenerallyprocessedinto tokensbeforematching.Tokenizationconsistsofoneormoreofthefollowingsteps. o Normalization:Sequencesofwhitespacearecollapsedintoasinglespace;somepunctuationis convertedtospaces;andsomepunctuationisremoved(causingconcatenationofthestring beforeitwiththestringafterit).Thisgivesaseriesoftokens. Twofilterscanbeappliedtothetokensthatresultfromnormalization: o Stopwords(small,commonwords,suchas'the'or'in'inEnglishor'la'and'en'in Spanish)arefiltered. o Wordsarestemmed;stemmingremovesplurals,turnsinflectedwordsintothe appropriateroot,andsoon.

PleaseseetheTextProcessingAppendixforlanguagedependenciesanddetailsofwhichoftherulesare appliedtoeachmetadatafield. Therearetwokindsoftextqueries: Theform<field> <string1><stringN>istrueforanyfieldthathasoneormoreofthe strings.Itisequivalentto<field> <string1> OR <field> <string2> OR ... OR
<field> <stringN> Theform<field> "<string>"istrueforanyfieldthathasexactly<string>init.<string>

istokenizedbeforethecomparison.Statedanotherway,thetokensequencegeneratedby <string>mustappearexactlyin<field>.Thetokenizationrulesappliedtoappliedto <string>arethoseappliedto<field>.

EIDRAPIOverview

P a g e |25

Version1.0120110407

Thegrammarforqueryexpressionsis: 3
<expression> ::= | | | <term> ::= | | | <term> <expression> OR <term> <expression> AND <term> NOT <term> <field> <field> <field> <field>

EXISTS
<string> <string>* "<string>" IS "<string>"

| <field> ISNOT "<string>" | <field> <logop> <value> | ( <expression> ) <field> ::= legal xpath attribute | legal xpath element ::= number | date | time | duration ::= = | <> | < | <= | > | >=

<value> <logop>

NOTESANDEXAMPLES Thetypesoneachsideofa<logop>mustbecompatible. Wildcardsarenotcurrentlysupported;normalizationandstemmingcovertheproblemsforwhich wildcardsaregenerallyused. Comparisonoperationsfordatesandtimestruncatetothelowestprecisionintheexpression. Languagefieldsarenottokenizedinanyway.Forexample,

/FullMetadata/BaseObjectData/PrimaryLanguage/Language "en"

Willmatchrecordswhoseprimarylanguageisen,butnoten-US,sinceen-USisretainedasthe singletokenen-US,notthetwotokensequenceen US. Althoughrangesarenotdirectlysupported,theycanbeimplementedusingtwosimplequeries combinedbyAND. Fieldsthatcontaincontrolledvocabularyaretokenized,withpunctuationcharactersremoved. Theemptystringmatchesnothing,ratherthaneverything. Fornonexistentfields,allISNOTcomparisonsevalauateasTrue.Forexample,ifthereisno CountryOfOriginfield,(/FullMetadata/BaseObjectData/CountryOfOrigin ISNOT fr)is True. ISandISNOTapplytoValue,Valuelanguage,andTextfields.

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

EIDRAPIOverview

P a g e |26

Version1.0120110407

ForValuefields,theyareusefulfortestingforcontrolledvocabularywords,equalityofDOIs, andequalityofnontokenizedfieldssuchasHouseSequence,AlternateID,andthevarious privatedatafields. ForValuelanguage,theyareusedasdescribedabove. Fortextfields,thefieldandthestringhavethesametokenizationrulesapplied(seeText ProcessingAppendixforindividualfields).

o o

Comparisonsaredonetotheprecisionoftheleastpreciseargument.Forexample,adatefield containing2010is>=,<=,and=to10102010.Comparingadateof2010to10isnot<>,<,or>10 102010 Someapplicationsmaywanttodoqueriesacrossonlymetadataontheobjectitself,asopposedto thefullmetadata.Thiscanbeusefulforapplicationswhosemainpurposeisdealingwiththe metadata,ratherthandealingwiththeobjectsdefinedbythemetadata.Thiscanbedonebydoing aregularquery,callingResolve()toreturnonlyselfdefinedmetadata,andthenexamining thoseresults. Asanexample,imagineaRegistrythathasobjectswiththefollowingtitlesintheResourceName fields: o o o o o o o o o o Batman:TheDarkKnight KnightofDarkStories DancingInTheDark DarknessAtNoon DarknessWaits TheGhostandTheDarkness ShanghaiKnights ShanghaiNoon Sinbad:TheBattleoftheDarkKnights FirstKnight

Queryingon/FullMetadata/BaseObjectData/ApproximateLength(abbreviatedfieldin thetable)givestheseresults: Expression

field Dark

Results
Batman:TheDarkKnight KnightofDarkStories DancingInTheDark Sinbad:TheBattleoftheDarkKnights

Notes
Anythingwith'Dark'

field "Dark Knight"

Batman:TheDarkKnight

Anythingwithexactlythe sequence'DarkKnight'.Sinbad: TheBattleoftheDarkKnightsis notincludedbecausetitlesare notstemmed.

EIDRAPIOverview

P a g e |27

Version1.0120110407

Expression
field Dark Knight

Results
Batman:TheDarkKnight KnightofDarkStories DancingInTheDark Sinbad:TheBattleoftheDarkKnights FirstKnight

Notes
Anytitlethathas'Dark'or 'Knight'.

field Knights

ShanghaiKnights Sinbad:TheBattleoftheDarkKnights

Anytitlewith'Knights'

(field Dark) AND (field Knight) (field Dark) AND NOT (field The)

Batman:TheDarkKnight KnightofDarkStories KnightofDarkStories

AnytitlewithbothDarkand Knight,inanyorderandany position Sinbad:TheBattleoftheDark Knightsisnotincludedbecause comparisoniscaseinsensitive.

The ISNOT,NOT, and <>operatorscanbeinefficientwhenappliedglobally,butitispossibleto rewritequeriestoworkaroundthis.Forexample,

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

willbemoreresponsivethan

NOT (/FullMetadata/BaseObjectData/ApproximateLength = PT50M00S)

API RootedQuery(DOI, queryExpression, page, pageSize, continuationToken) GeneralQuery(queryExpression, page, pageSize, continuationToken) Returnstypeeidr:queryResults,whichcontains: PageSizemaxsizeofreturnedchunks(sameasinputparameterpageSize) MySizesizeofthischunk(equaltopageSizeexceptforthelastpage TotalPagestotalnumberofpagesthatcanbereturned PageNumnumberofthereturnedpage TotalResultstotalnumberofavailableresults

EIDRAPIOverview

P a g e |28

Version1.0120110407

ContinuationTokenreturnedbyimplementationsthatinternallycachequeryresults. Itshouldbepassedinasthetokenargumentonsubsequentcallsasanaccelerator. Alistof eidr:simpleDataInfoTypeforallobjectsthatmatchqueryExpression, chunkedupbasedonthelastfourparameters.Amalformedorempty queryExpressionreturnsaBadQueryerror

Errors:standarderrors,BadQuery,andResultTooLong Thepagingparametersareusedasfollows: ResultsarereturnedwithpageSizeobjectsperbatch. Thepagethpageofthatsizeisreturned.Page1isthefirstpage.Page0isarequestforall results. ContinuationTokenshouldbeavaluereturnedbythepreviouscallusingthisquery string,oremptyifthisisthefirstcallintheset.

TheonlydifferencebetweenthetwoqueryfunctionsisthatRootedQuery()onlyreturnsresults thatarethechildrenoftheDOIargument. Theresultsaresortedbylanguagecodeoftheprimarytitle,andthenbytitlewithineachlanguage code. Errors:standarderrors,BadQuery, ResultTooLong 3.2.4. VIRTUALFIELDS Besidesindividualfields,anobjectcontainstwo'virtual'stringfieldsthatcombinemultipleotherfields. Bothofthesearenormalized(punctuationstripped,spacescollapsed)andtokenizedusingthedefault (English)rules.Stopwordfilteringandstemmingarenotapplied. 4 Thisalsoappliestostringsasquerieson thevirtualfields. FullStringcomposedofthesefieldsfromFullObjectMetadataType o o o o o o BaseObjectData/ResourceName BaseObjectData/AlternateResourceName BaseObjectData/DisplayName BaseObjectData/Description BaseObjectData/Credits/Director/DisplayName BaseObjectData/Credits/Actor/DisplayName(usingallthatarepresent)

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

EIDRAPIOverview

P a g e |29

Version1.0120110407

SelfDefinedStringasFullString,butonlythosefieldsthatarenotinherited Inqueries,thevirtualfieldsare /VirtualField/Full /VirtualField/SelfDefined Theorderofthetokenswithineachoftheconstituentfieldsispreserved,buttheorderinwhichthe constituentfieldsareaddedtothevirtualfieldisnotdefined.Thismeansthatanexactmatchquery(using <field> "<string">)returnsunpredictableresultswhentheexactquerymightmatchtoken sequencesthatcrossfields.Itmatchestokensequenceswithinindividualfieldspredictablyasitwouldon thesinglefield. ThevaluesofthevirtualfieldscanberetrievedusingGetVirtualFields().Thiscanbeusefulfor debugging,butisnotintendedtobeusedforpresentationtoanenduser. GetVirtualFields(DOI) Returnsastructureoftypeeidr:VirtualFieldscontainingthetwostrings Errors:standarderrorsonly 3.2.5. PROVENANCE Anobject'sprovenanceinformationcanberetrievedbycallingResolve(DOI, "Provenance", followAlias. Whenanobjectiscreated,itsLastModificationDateissetequaltoitsCreationDate. TimesintheprovenancearestoredasUTCwiththeexplicittimezonemarkerZ.

4. PARTIES,USERS,ANDPERMISSIONS
APartyrepresentsanentitysuchasaregistrantoraproducingagent.AUserisanindividual(oranabstract thingthatcanbetreatedasanindividual.)Note:forhistoricalreasons,theinitialimplementation sometimescallsaPartya'Group.' AllUsersareassociatedwithaParty.Thecurrentversionoftheregistrysupportsonlythissinglelevelof hierarchy;futureversionsmayaddsubentities,aswell,forrepresentingdifferentorganizationwithina singleEntity. Allrequeststotheregistrycontainauthenticationinformationforapartyandauser. TheUserrequestingthecreationofanewobjectmustbeassociatedwiththeRegistrant(aParty)givenin theregistrationdata. OnlyPartieshavepermissionsinthesystem;aUserhasallthepermissionsassociatedwithitsparentParty. Note:OnlytheRegistrationAuthorityhastheabilitytocreateormodifyparties. EIDRAPIOverview P a g e |30 Version1.0120110407

4.1 PARTIES ThereisapredefinedPartyrepresentingtheRegistrationAuthority. Anentitycanbeoneormoreofthefollowing: ProducingAgent:Thesebringforththeobjectbeingregistered:astudiointhecaseofan abstractwork;oranencodinghousefortheworkinafinaldigitalform;orevenanantipiracy vendorforregisteringanewillegalcopyofawork.Theimportantthingtorememberaboutthis fieldisthatitreferstotheentitythatmostrecentlytouchedtheitem. Registrants,whoregisteritems.Aregistrantmaybeaprincipalagent,suchasastudiooran encodinghouse,oritmaybeanexternalentitydoingbulkregistrationofbackcatalogueitems. CurrentAssetHolder:Thispartymaybeincludedoptionallybytheregistranttoindicatethe entitytheregistrantthinksismostlikelytohavesomeauthorityoverthisobject.Forexample,a metadataproviderdoingbulkregistrationmaymakethisfieldthesameastheProducingAgent forobjectsreasonablysuretobeunderthecontrolofthatentity,andleaveitblankotherwise. BackupContact:Optionallyregisteredentitiesthatmaybeabletosortoutthingsthatare otherwisebeyondthekenoftheRegistrant. EncodingVersionAgent:optionalentityusedwhenregisteringencodings.

Additionally,anentitycanberegisteredas Writer:canreadandmodifyobjects,butnotcreatethem. Reader:ifonanobject'sACL,canreadobjectsandmetadatathatwouldotherwisebehidden. ThismattersforInDevobjectsonly.

Asanexample,anencodinghousethatregistersnewencodingswillbetheRegistrantfortheobject.Inthe strictestsense,theycouldbetheProducingAgentaswell,butthatisnotmandated;forexample,therights holdercouldrequirethattheProducingAgentfortheencodingbethesameasthatfortheparentobject. TheencodinghousewillalsoprobablybetheEncodingAgentforeachitem,unlesssomeaspecthasbeen subcontractedoutelsewhere(e.g.,toaspecialistsubtitleshop.) APartycanbeeitherActiveorInactive.AninactivePartymaynotmakeanymodificationstothedatabase; thatis,itmaynotbeaRegistrantoraWriter,andallUsersassociatedwithitaresimilarlyrestricted. 4.1.1. CREATE CreateParty(partyData) ReturnsaDOIoftypeeidr:partyDOITypeforthenewlycreatedparty.Theparameter partyDataisoftypeeidr:partyCreationType. ThesuffixofthereturnedDOIisthePartyAccountNamefieldfrompartyData.Itmustnot matchanyotherPartyAccountNameinthesystem. Errors:StandarderrorsorDuplicateParty.

EIDRAPIOverview

P a g e |31

Version1.0120110407

Note:IntheinitialversionoftheRegistry,onlyminimalcheckingisdoneforduplicatesofParties. ApplicationsusingCreateParty()shouldbeaccordinglycautious. CreateUser(userData) ReturnsaDOIoftypeeidr:userDOITypeforthenewlycreateduser. userDataisoftypeeidr:userCreationType,withthefollowingconstraints: userData.Usernameisoftypeeidr:usernameType andmustnotmatchanyother usernameinthesystem. userData.ParentPartyisoftypeeidr:partyDOIType userData.Passwordmustbe632characterslong

ThesuffixofthereturnedDOIistheUsernamefieldfromuserData. Errors:Standarderrors,DuplicateUser, or BadParty. Note:TheinitialversionoftheRegistryonlychecksforanexactduplicateofusername. 4.1.2. MODIFY ModifyParty(partyData) Returnssuccessoranerror. partyDataisoftypeeidr:partyResolutionType.ResolveParty(partyID, "full") returnsanappropriatebaseformodifications. Notethatthisdoesnotincludethepasswordfield.partyData.IDcannotbemodified. Errors:StandarderrorsorBadParty. ChangePartyPassword(partyID, newPartyPassword) ChangestheParty'spassword.Theoldpasswordisnotsentseparately;itisalreadywiththe credentialsentwiththecall. Errors:StandarderrorsorBadParty. ModifyUser(userInfo) Returnssuccessoranerror. userInfo isoftype eidr:userResolutionType. ResolveUser(userID, "full") returnsanappropriatebaseformodifications. Notethatthisdoesnotincludethepasswordfield.userInfo.IDcannotbemodified. Errors:Standarderrorsor BadUser. ChangeUserPassword(userID, newUserPassword) ChangestheUser'spassword.Theoldpasswordisnotsentseparately;itisalreadywiththe credentialsentwiththecall. EIDRAPIOverview P a g e |32 Version1.0120110407

Errors:StandarderrorsorBadUser. ReparentUser(userID, newPartyID) ReturnsSuccess,StandardErrors,BadParty,orBadUser. Ifsuccessful,removestheuserfromitspreviousgroupandassignsittothenewone.

4.1.3. ADMINISTRATIVETASKS Note:OnlytheRegistrationAuthoritycanperformthefollowingtasks. DeactivateParty(partyID) ReturnsSuccess,StandardErrorsorBadParty. Ifsuccessful,usersassociatedwiththepartyarenolongerallowedtodoanythingthatrequires presenceonanACL.partyIDisvirtuallyremovedfromACLs(theRegistrychecksthe active/inactivestateofentriesintheACL),notactuallyremoved;thisallowseasydeactivationand reactivationofpartiesforadministrativereasons. ActivateParty(partyID) ReturnsSuccess,StandardErrorsorBadParty.Ifsuccessful,thePartyismadeactive. DeactivateUser(userID) ReturnsSuccess,StandardErrorsorBadUser. Ifsuccessful,theuserisnolongerallowedtodoanything;authenticationoftheuser'scredentials willfail. ActivateUser(userID) ReturnsSuccess,StandardErrorsorBadUser. Ifsuccessful,theuser'scredentialsarevalidandauthenticationofthemsucceeds. ValidateCredentials(partyID, userID, password) partyID isoftypeeidr:partyDOITYpe userID isoftypeeidr:userDOIType password isoftypeeidr:simplePasswordType. Returns: 'allvalid'iftheuserIDandpasswordarecorrectanduserIDisassociatedwithpartyID. 'wrongparty'iftheuserandpasswordmatchbutuserIDisnotassociatedwithpartyID 'invalid'istheuserandpassworddontmatch.

Errors:Standarderrors. 4.1.4. RETRIEVINGINFORMATION ResolveParty(partyID, type) EIDRAPIOverview P a g e |33 Version1.0120110407

Returnsmetadatafortheparty;theformatoftheresultisdependentonthetypeparameter. Type
DOIKernel Full

Format
DOIkernelmetadataforaParty eidr:partyResolutionType;seetheschema. The PartyAccountNamefieldwillmatchthesuffixoftheDOI

Errors:Standarderrors,orBadParty ResolveUser(userID, type) Returnsmetadatafortheuser;theformatoftheresultisdependentonthetypeparameter. Type

DOIKernel

Format
DOIkernelmetadataforaCreation,withstructuraltypeofrestricted.Theobject's nameis"No information available". eidr:userResolutionType;seetheschema. TheUsernamefieldwillmatchthesuffixoftheDOI.

Full

Errors:Standarderrors,orBadUser GetUsers(partyID) Returnslistofeidr:userDOITypeforallUsersassociatedwithpartyID,whichmustbeof typeeidr:partyDOIType. Errors:Standarderrors. FindPartiesByName(string, roleFilter, activeFilter, page, pageSize, continuationToken) Seebelowforuseofpagingparametersandstring. roleFilterisanoptionallistofstringsoftypeeidr:administratorTypeType. activeFilteris'active','inactive',or'all'. Returnstypeeidr:partyQueryResults,whichcontains: PageSizemaxsizeofreturnedchunks(sameasinputparameterpageSize) MySizesizeofthischunk(equaltopageSizeexceptforthelastpage TotalPagestotalnumberofpagesthatcanbereturned PageNumnumberofthereturnedpage TotalResultstotalnumberofavailableresults ContinuationTokenreturnedbyimplementationsthatinternallycachequeryresults. Itshouldbepassedinasthetokenargumentonsubsequentcallsasanaccelerator. P a g e |34 Version1.0120110407

EIDRAPIOverview

Alistof eidr:partyDOIType forallparties o o o whoseDisplayNamefieldorAlternatePartyNamefieldcontainsstring, thatmatchactiveFilter, and whoseAllowedRolescontainsoneormoreoftheelementsofroleFilter.If roleFilterisnotpresent,anyrolewillmatch.

Forexample,"Fox"wouldreturntherecordsforFoxTelevisionand20thCenturyFox. Forthesearch,String,DisplayNameandSortNamearenormalized(spacescollapsed, punctuationremoved)butnottokenized,filteredforstopwords,orstemmed. Errors:standarderrorsandResultTooLong Thepagingparametersareusedasfollows: Internally,theRegistrykeepsalistofPartiessortedbySortName(orDisplayNameofSortNameisnot present.)SectionsofthissortedlistarereturnedusingtheFindPartiesFromCatalog()call. FindPartiesFromCatalog(string, roleFilter, activeFilter, page, pageSize, continuationToken) Seebelowforuseofpagingparametersandstring. roleFilterisanoptionallistofstringsoftypeeidr:administratorTypeType. activeFilteris'active','inactive',or'all'. Returnstypeeidr:partyQueryResults,whichcontains: PageSizemaxsizeofreturnedchunks(sameasinputparameterpageSize) MySizesizeofthischunk(equaltopageSizeexceptforthelastpage TotalPagestotalnumberofpagesthatcanbereturned PageNumnumberofthereturnedpage TotalResultstotalnumberofavailableresults ContinuationTokenreturnedbyimplementationsthatinternallycachequeryresults. Itshouldbepassedinasthetokenargumentonsubsequentcallsasanaccelerator. ResultsarereturnedwithpageSizeobjectsperbatch Thepagethpageofthatsizeisreturned.Page1isthefirstpage.Page0isarequestforall results. ContinuationTokenshouldbeavaluereturnedbythepreviouscallusingthisquery string,oremptyifthisisthefirstcallintheset.

EIDRAPIOverview

P a g e |35

Version1.0120110407

Alistof eidr:partyDOIType,inlexicalorderbySortName(orDisplayNameif SortNamedoesnotexist),forallpartiesfoundmatchingthesecriteria:Alistof eidr:partyDOIType forallparties o o o o whoseDisplayNamefieldcontainsstring thatmatchactiveFilter whoseAllowedRolescontainsoneormoreoftheelementsofroleFilter.If roleFilterisnotpresent,anyrolewillmatch stringisusedasfollows: TheemptystringmatchesallParties Lettersequence:returnsallpartieswhoseSortName(orDisplayNameif thereisnotSortName)startswiththelettersequence.Forexample"BBC" wouldreturntherecordsforBBC,BBCWorldwide,BBCCymru,BBC Scotland,andBBCAmerica. Lettersequence1lettersequence2:returnsallpartieswhoseSortName(or DisplayNameifthereisnotSortName)startswithsomethingbetween lettersequence1andlettersequence2,inclusive.Iflettersequence2isnot lexicallygreaterthanlettersequence1,allitemsfromlettersequence1 thoughtheendofthesortedlistofPartiesarereturned.Forinstance,"AB" returnsallPartieswhosenamesstartwithAorB. Notethatiflettersequence1andlettersequence2areidentical,thebehavioristhesameas forthesinglelettersequence.

Forthesearch,string,DisplayNameandSortNamearenormalized(spacescollapsed, punctuationremoved)butnottokenized,filteredforstopwords,orstemmed. Errors:standarderrorsandResultTooLong Thepagingparametersareusedasfollows: ResultsarereturnedwithpageSizeobjectsperbatch. Thepagethpageofthatsizeisreturned.Page1isthefirstpage.Page0isarequestforall results. ContinuationTokenshouldbeavaluereturnedbythepreviouscallusingthisquerystring, oremptyifthisisthefirstcallintheset. 4.2 PERMISSIONS Aregularrecordcanbecreated,modified,aliased,ordeleted.AnInDevelopmentrecordcanalsobe promoted.Itisalsopossibletoreadcertaintypesofadministrativeinformationaboutarecord. AParty(anditsUsers)canonlycreateanewrecordifithas'Registrant'intheAllowedRolesfield.

EIDRAPIOverview

P a g e |36

Version1.0120110407

AParty(anditsUsers)mustbeabletoreadanobjectinordertocreateormodifyanyinheritance, dependence,orlightweightrelationshipsinvolvingit.Forexample,anIsAdjunctTorelationshipcannotbe madetoanInDevobjectbyaPartythatisnotontheInDevobject'sReadACL. OtheractionsaregatedbyACLsontheindividualrecords.EachregularrecordhasanACLfor: Modify:cancontainentitiesthatareoftypeRegistrantorWriter.Requiredtomodifyanobject. Delete:cancontainentitiesthatareoftypeRegistrantorWriter.Requiredtoaliasordeletean object. ReadACL:cancontainentitiesthatareoftypeRegistrant,Writer,orReader.Requiredtoreadany ACL. WriteACL:cancontainentitiesthatareoftypeRegistrant.RequiredtomodifyanyACL. ReadProvenance:cancontainentitiesthatareoftypeRegistrant,Writer,orReader.Requiredto readtheprovenancemetadata.OnlytheRegistrationAuthoritycanmodifyarecord'sProvenance information.

InDevelopmentrecordshavetwomoreACLs: Promote:entitiesonthislistmustbeoftypeRegistrant.Onlyentitiesonthislistcanpromotean InDevobjecttoValid. View:entitiesonthislistcanbeofanytype.OnlyentitiesonthislistcanviewanInDevobjector havethemreturnedfromaquery.

ThefollowingtablesummarizespossiblepermissionsbasedontheRole.ForagivenObject,theassociated permissionsforaparticularParty(withaRole)maybemorerestrictivethanwhatsspecifiedinthetable. Role/Permission View Read ACL Registrant Writer Reader PrincipalAgent Yes Yes Yes Yes Yes Yes Yes Read Provenance Yes Yes Yes Yes Yes Yes Yes Modify Delete Write ACL Yes Yes Yes Yes Promote

CurrentAssetHolder Yes BackupContact EncodingAgent Yes Yes

IfaRoleisremovedfromaparty,anyACLthatdependsonthepresenceofthatrolewilldisallowtheaction, evenifthePartyisintheACL.Forexample,iftheWriterroleisremovedfromaParty,thatPartyandits associatedUserswillnotbeabletomodifyrecordsforwhichitwasalreadyontheACLsforModify,Delete, EIDRAPIOverview P a g e |37 Version1.0120110407

WriteACL,andPromote,andwillnotsubsequentlybeabletobeaddedtotheACLsforModify,Delete, WriteACL,orPromoteonanyotherobjects. ReadACL (assetID, aclType) ReturnsalistofthePartiesonthespecifiedACLforassetID,whichmustbeoftype eidr:assetDOIType. Errors:Standarderrors. ClearACL(assetID, aclType) RemovesallPartiesfromthespecifiedACLforassetID,whichmustbeoftype eidr:assetDOIType. Errors:Standarderrors. AddToACL(assetID, aclType, partyID) AddspartyIDtothespecifiedACLforassetID,whichmustbeoftype eidr:assetDOIType. PartyID isoftype eidr:partyDOIType. Errors:Standarderrors,andBadPartyifpartyIDisnotvalid. RemoveFromACL(assetID, aclType, partyID) RemovespartyIDfromthespecifiedACLforassetID,whichmustbeoftype eidr:assetDOIType. PartyID isoftype eidr:partyDOIType. Errors:Standarderrors,andBadPartyifpartyIDwasnotontheACL.

5. UTILITIES
5.1 DOIPROXY EIDRresolutionscanberequestedfromthestandardDOIproxy.Resolutionrequestsareoftheform:
http://dx.doi.org/<Handle prefix>/<Handle suffix>

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

Inthefollowingtable,'ResolutionType'isthestringafterthecoloninthe?locatt=type:construction. (none)meansthatthetypespecifierisnotprovided. Proxyresolutionsfollowaliaschains,andbehaveliketheResolve()callwithfollowAliassetto true.SeeResolve()forinformationonspecialcasesfordeletedobjects,overnestedaliases,etc. EIDR item Prefix Resolution Type Returns P a g e |38 Version1.0120110407

EIDRAPIOverview

EIDR item
Party User

Prefix
10.5237 10.5238

Resolution Type
(none) (none)

Returns
doi:kernelMetadatawithadoi:referentPartyelement doi:kernelMetadatawithreferenttypeofRestricted doi:referentPartyelementwithanameof"EIDRUser"

Object Object Object Object Object

10.5240 10.5240 10.5240 10.5240 10.5240

(none) Full SelfDefined Simple DOIKernel

Returnsmetadataformattedaseidr:fullObjectInfoType. Returnsmetadataformattedaseidr:fullObjectInfoType. Returnsmetadataformattedas eidr:allSelfDefinedObjectInfoType. Returnsmetadataformattedaseidr:simpleDataInfoType Returnsmetadataformattedasdoi:kernelMetadata.

6. PREDEFINEDOBJECTSANDCONSTANTS
6.1 TOMBSTONES Deletedobjectsarealiasedtoa'tombstone.'Becausethetombstoneobjectisoftype'Restricted',only threeofitsfieldshaveguaranteedvalues.Otherfieldsshouldnotbeused. Field
ID StructuralType ResourceName

Value
10.5240/00000000000000000000X Restricted "EIDRTombstoneObject"

Thetombstoneobjectisnotindexed,soitwillneverbereturnedfromqueries. 6.2 ERRORHANDLING Thestructuresusedforreturningerrorsareinapi.xsd Errorstringsandnumericerrorcodesareinapicommon.xsd 6.3 PREDEFINEDPARTIES Theparty10.5237/superpartyispredefinedandhasallallowedroles.Ithasapredefineduser 10.5238/superuser. 10.1000/ra5istheDOIfortheEIDRRegistrationAuthority;itisusedintheDOIKernelresolutionformat. 6.4 HANDLEPREFIXES TheHandleprefixesusedbytheregistryare: EIDRAPIOverview P a g e |39 Version1.0120110407

10.5237parties 10.5238users 10.5240assets/objects

7. APPENDICES
7.1 SEASONSANDEPISODES Theinteractionsbetweenname,number,andtheIsOrderedflaginseasonsandseriesis: Seasons: SequenceNumberisrequiredforseasons. ResourceNameisrequiredforaseasonifparent.IsOrderedisfalse.

Episodes: SequenceNumberisrequiredforepisodesifparent.IsOrderedistrue. ResourceNameisrequiredforepisodesifparent.IsOrderedisfalse. ItislegalforbothSequenceNumberandResourceNametobepresent.

7.2 COMPLEXINHERITANCE Mostinheritablefieldsusesimpleinheritancethevalueistakendirectlyfromtheparent,whichinturn mayhavetakenitfromitsparent,andsoonuptheinheritancechainuntilanobjectisfoundthatdefines thefield.Inthesecases,afield'svalueisoneofeithertheselfdefinedmetadataortheinheritedmetadata. ResourceNameandPrimaryandsecondarylanguagesbehavedifferently,becauselanguagesandtitlescan bereplacedinaparticularobject(providinganewvalue)oraccreted(addinganewvaluetoapreexisting set).Inthesecases,thevaluefoundintheobject'sfullmetadataisnotnecessarilythesameaseitherthe selfdefinedortheinheritedmetadata,butcanbeacombinationofthings. 7.2.1. RESOURCENAME ResourceNameiscardinality1inbaseObjectInfoTypeitmustexistinafullyresolvedobjectand 01inselfDefinedBaseObjectInfoTypeandinheritedBaseObjectInfoType,whereitcan beeitherpresentontheobjectorinherited.Aresourcenamespecifiesthelanguageofthename,andthe classofthenameRelease,Working,Acronym,andsoon. TheReplacedAlternateResourceNamesflagbehavesasfollows:

Iftrue,thealternatetitlesintheobjectreplaceallothers.Itcanbetrue,withnoAlternateNames provided,whichresultsinanemptyalternatetitlelist.Ifitisfalse,thenamesprovidedareaddedto thelistofinheritedalternatenames. P a g e |40 Version1.0120110407

EIDRAPIOverview

Itisitselfaninheritablefield.Althoughthealternatenamesonarootobjectbehavethesameno matterwhichwaytheflagisset,sincereplacinganemptylistandaddingtoanemptylistare equivalent,thevalueinarootobjectshouldbeonethatsupportsdownstreampracticesfor alternatenames,forexampleforeditsandencodings.

AlternateResourceNameisalistofalternatenamesfortheobject,oftypetitleType.0ormoreof theseareprovidedwhenanobjectiscreated.Inrecordsreturnedfromtheregistry: InselfDefinedBaseObjectInfo,theelementsarethesetofitemsprovidedwhentheobject wascreatedormodified. IninheritedBaseObjectInfo,theelementsareanythatareinherited.Notethatif ReplacedAlternateNamesistrue,thislistisempty;ifitisfalse,itcontainsonlytheitems providedbyancestors InbaseObjectInfoType,itisthecollatedlistofalternatetitles(addingorreplacingasstated above.)

7.2.2. LANGUAGES PrimaryLanguage andSecondaryLanguageinthebasetypeareprovidedonlywhencreatinga rootobject. ArootobjectdefinesaPrimaryLanguageelement,andasetofoptionalSecondaryLanguage elements.Thesecontainonlylanguageinformation;titlesarespecifiedseparatelyusingthe ResourceNameandAlternateResourceNameelements. Thesetwofieldsarenotdirectlymodifiableinnonrootobjects.Instead,extralanguagesarespecifiedwith anIsLanguageVariantdependencerelationship,whichcomesintwoforms: Add:onlysecondarylanguagescanbespecified,andtheyareaddedtoanyinheritedsecondary languages.Theprimarylanguageisunchanged. Replace:Thissupportsthreevariants: o Primarylanguageonly:Theprimarylanguageisreplaced,andallsecondarylanguagesare removed. Primaryandoneormoresecondarylanguages:Theprimarylanguageisreplaced,allexisting secondarylanguagesareremoved,andthesecondarylanguagesintherequestareadded. Secondarylanguagesonly:Allsecondarylanguagesareremoved,andreplacedwiththe secondarylanguagesintherequest.Thesetisallowedtobeempty,inwhichcaseall secondarylanguagesareremoved.

Whenresolvinganobject,thebehaviorisasfollows: InselfDefinedBaseObjectInfo,thePrimaryLanguageandSecondaryLanguage elementsareneverpresent,unlesstheobjectisarootobject. P a g e |41 Version1.0120110407

EIDRAPIOverview

IninheritedBaseObjectInfo,thelanguageselementsareanythatareinherited.These inheritedvaluesmaybedirectlyinheritedfromtherootobject,orgeneratedbyfollowing add/replacerulesintheancestors.ThislistdoesnotincludethelanguagesinanyLanguageVariant relationshipontheobjectitself. InbaseObjectInfoType,thePrimaryLanguageandSecondaryLanguageelements containcollatedlanguages,startingfromtherootandfollowingtheadd/replaceinstructionsinany IsLanguageVariantrelationshipsinthechain,includinganyontheobjectitself.Thisissometimes calledtherolledupsetoflanguages,orfullyinheritedlanguages,andrepresentsthelanguages actuallypresentontheobject.

7.3 MODIFYINGOBJECTS Modifyingobjectshastwocomponents: Changingmetadataforthetypewithwhichtheobjectwascreatedorcouldhavebeencreated. Changingmetadataforrelationshipswhichhavebeenaddedorcouldhavebeenaddedtothe object.

Inalloftheseexamples,'legal'iscontingentonthenewdatapassingthevalidationrules.Thistableisnot exhaustive. Initial Subsequent additions creationType

CreateBasic CreateSeries CreateClip none none LanguageRelationship

Legal modification bases

Legal replace/remove relationship

none none LanguageRelationship

CreateBasic CreateBasic,CreateSeries CreateBasic,CreateClip, CreateLanguageVariant

7.4 TEXTPROCESSING 7.2.3. FIELDRULES Therearethreekindsofmatches: TokenMatchthecheckismadefortheexistenceofthetokensinanyorderinthecandidate string.Thisusesthe<field> <string> <string>syntax. ExactMatchthecheckisdonefortheexistenceofanorderedsequenceoftokensinthecandidate string.Thisusesthe<field> "<string>"syntax. CompleteMatchchecksfortheexactexistenceoftheexactquerystringornot.Thisisgenerally usedforfieldscontainingcontrolledvocabularyorIDs,butcanalsobeusedonsometextfields.For P a g e |42 Version1.0120110407

EIDRAPIOverview

anontokenizedfield,thequerystringandthefieldmustbeidentical.Atokenizedfieldmustbe identicaltothetokenizedquerystring.ThisusestheISandISNOToperators. Controlledvocabularyfieldshavepunctuationreplacedbyaspace,andarethentokenized. Field

ResourceName

Match type
Token Exact

Normalize
Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes

Filter Stop Words

No No No No No No No No No No No No No No No No No No No No No No Yes No Yes No

Stem
No No No No No No No No No No No No No No No No No No No No No No Yes No Yes No

AlternateResourceName

Token Exact

DisplayName

Token Exact

VirtualField(Fullandselfdefined) SeedescriptionofVirtualFields. md:PersonNametype/DisplayName

Token Exact Token Exact

md:PersonNametype/SortName

Token Exact

md:PersonNametype/FirstGivenName

Token Exact

md:PersonNametype/SecondGivenName

Token Exact

md:PersonNametype/FamilyName

Token Exact

md:PersonNametype/Suffix

Token Exact

md:PersonNametype/Moniker

Token Exact

Description

Token Exact

WrapperDetails

Token Exact

EIDRAPIOverview

P a g e |43

Version1.0120110407

Field
HouseSequence RegistrantExtra RegistrantPrivate AlternateID Anyfieldoftype componentReferenceType: EncodingInfo/xxxInfoBlock/Compone ntReference and EncodingInfo/WrapperInfoBlock/Com ponentInfo/componentReference FindPartiesByName FindPartiesFromCatalog

Match type
Complete Complete Complete Complete Total

Normalize
No No No No No

Filter Stop Words

No No No No No

Stem
No No No No No

Seefunction definition Seefunction definition

Yes Yes

No No

No No

7.2.4. LANGUAGESPECIFICFILTERING TherearelanguagespecificlistsforEnglish,French,Spanish,Italian,andGermanfor: Punctuationthatturnsintospaces Punctuationthatcollapsestwowordstogether Stopwordsthatgetfilteredout

Languagespecificrulesaregiveninthetablebelow.Ifafieldhasalanguageattribute,thenthelanguage specificrulesareapplied;otherwise,Englishrulesareapplied.Thequerystringisprocessedbasedonthe languagefieldinthequeriedfield;ifthereisnolanguageattribute,Englishrulesareapplied. Notethatthedashinlanguagefields(e.g.deCH)isnotremoved. Language

English

Spacing Punctuation
.,;:^&!+=()[]{}<>~ #$/*@/ '(singlequote) "(doublequote) (hyphen)

Collapsing Punctuation
(apostrophe)

Stop Words
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,

EIDRAPIOverview

P a g e |44

Version1.0120110407

Language

Spacing Punctuation
#$/*@/ '(singlequote) "(doublequote) (hyphen) (apostrophe)

Collapsing Punctuation

Stop Words
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

.,;:^&!+=()[]{}<>~ #$/*@/ '(singlequote) "(doublequote) (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, un,unos,una,unas,el,los,la,las,este,esta,esto, estos,estas,ese,esa,eso,esos,esas,es,son,est, estn,hay,y,o,pero,de,en,para,como,con, por,sobre,el,ella,ellos,ellas,se,su,sus,suyo, suya,suyos,suyas

Spanish

.,;:^&!+=()[]{}<>~ #$/*@/ '(singlequote) "(doublequote) (hyphen) (apostrophe,butit'snot usedinSpanish)

German

.,;:^&!+=()[]{}<>~ #$/*@/ '(singlequote) "(doublequote) (hyphen)

(apostrophe) [Note:thismeans thatanapostrophe attheendofaword isdropped,andone inthemiddleofa wordfor abbreviations collapsesthetwo partstogether.]

ein,einer,eine,eines,einem,einen,der,die,das, denist,seinund,oderdurch,als,von,mit,fr, am,in,auser,sie,es,sieihnihm,ihr,ihnensein, siene,ihre

EIDRAPIOverview

P a g e |45

Version1.0120110407

7.5 ESCAPINGXMLCHARACTERS SpecialXMLcharactersinaRegistryresponseareescapedasappropriate,regardlessofthetechnique (escapingorCDATA)usedintheoriginalrequest.Thespecialcharactersandtheirescapedrepresentation are Character " ' < > & Escape &quot; &apos; &lt; &gt; &amp;

7.6 MAPPINGEIDRFIELDSTODOIFIELDS Note: BaseObjectDataisoftypeeidr:baseObjectInfoType. Provenanceisoftypeeidr:provenanceInfoType PrincipalAgentisoftypeeidr:principalAgentType PartyResolutionisoftypeeidr:partyResolutionType DOI Kernel Subfield
primaryLanguage value type

DOI kernelMetadata Field

referentDoiName primaryReferentType registrationAgencyDoiName issueDate issueNumber referentCreation.name

EIDR Field (Assets only)

/BaseObjectData/ID Creation 10.1000/ra5 /Provenance/CreationDate /Provenance/IssueNumber /BaseObject/ResourceName@lang /BaseObject/ResourceName Always'title' Infutureversions,derivedfrom /BaseObject/ResourceName@titleClass

EIDRAPIOverview

P a g e |46

Version1.0120110407

DOI kernelMetadata Field

referentCreation.identifier

DOI Kernel Subfield

EIDR Field (Assets only)

Currentlyusedonlyforaliasedobjects.(See Resolve().) UsedforAlternateIDsinafutureversionofthisspec.

referentCreation.structuralType referentCreation.mode

/BaseObject/StructuralType /BaseObject/Mode AudioVisualresultsintwoDOImodes.

referentCreation.character

Basedon/BaseObject/Mode Audio>Language Video>Image AudioVideo>Both Exception:objectofReferentTypeInteractiveMaterial >Other

referentCreation.type

/BaseObject/ReferentType Series>Series Season>Series Allothers>MovingImage(withapologiesto InteractiveMaterialandAudioonlyitems.

referentCreation.PrincipalAgent

name.value name.type identifier role

/PartyResolution/PartyName/DisplayName 'Name' /PrincipalAgent basedon/PrincipalAgent@role broadcaster,distributor>Publisher allothers>CorporateCreator

linkedCreation

Reservedforfutureusebasedonanobject's relationships

EIDRAPIOverview

P a g e |47

Version1.0120110407