Architecture & Developer Integration Guide (FKA EIDR Programmers Guide)

The Entertainment Identifier Registry (EIDR) provides unique, universal, persistent identifiers for commercial audiovisual content and corporate entities. This guide synthesizes the EIDR technical documentation into a modernized, developer-focused architecture reference, covering the EIDR Data Model, ID Formats, API Integration, and SDK Workflows.

1. System Architecture

The EIDR ecosystem is built on the Handle system (similar to how HTTP utilizes TCP/IP) and is fully compliant with the ISO 26324 Digital Object Identifier (DOI) standard.

The architecture consists of the following core components:

• Core Registry & Repository: Manages registrations, generates EIDR IDs, handles access control, and stores object metadata.

• De-Duplication Engine: Evaluates new and modified records against the registry to guarantee uniqueness before ID assignment.

• EIDR REST API & SDKs: An HTTPS-only interface providing access to registry functions (query, resolution, registration, modification). Java and .NET SDKs abstract this API for developer convenience.

• EIDR API Proxy: A supplementary read-only service that provides advanced JSON/TSV formatting, bulk resolution, and JSON queries without impacting the primary XML-native registry.

• DOI Proxy (https://doi.org ): Resolves canonical EIDR IDs and standard URN forms globally.

2. The EIDR Data Model

The EIDR Content ID Registry utilizes a strict object-oriented hierarchical registration tree.

Record Types

Records are defined by their Structural Type and Referent Type:

1. Collection: Grouping records like Series, Seasons, and Compilations.

2. Abstraction: The fundamental root work, such as a Movie, Web original, or a TV Episode.

3. Edit (Performance): A specific creative cut or version of an Abstraction (e.g., Director's Cut, censored version, airline edit).

4. Manifestation (Digital/Physical): A technical representation or encoding of an Edit (e.g., H.264 file, Blu-ray, or specific language dubs/subs).

Data Inheritance

All EIDR records share a core set of Base Object Data (ID, Structural Type, Referent Type, Resource Name).

• Root Records (e.g., Series or Movies) must self-define all required Base Object Data.

• Child Records (e.g., Seasons, Episodes, Edits) inherit most Base Object Data from their parent, supplying only self-defined metadata unique to that child (e.g., a specific duration for an Edit or sequence number for an Episode).

• Extra Object Metadata encapsulates data specific to derived types (such as EditInfo or SeasonInfo) and non-inheriting relationships (like isPromotionFor or isCompositeOf).

3. EIDR Identifier Formats

An EIDR ID is a specific implementation of a DOI, structured as [Prefix]/[Suffix].

• Prefixes: Designate the EIDR namespace.

  • 10.5240 - Content IDs

  • 10.5239 - Video Services

  • 10.5237 - Parties (Organizations)

  • 10.5238 - Users

• Suffix: For Content IDs, this is 20 hexadecimal digits grouped by hyphens, followed by an ISO 7064 Mod 37,36 check character. Example: 10.5240/XXXX-XXXX-XXXX-XXXX-XXXX-C.

Developer Representations

While the canonical format is strictly enforced by the EIDR API, several lossless formats are supported for application layers:

• Compact Binary: Ideal for database storage. Encodes the 16-bit sub-prefix (e.g., 5240) and 80-bit suffix into a 96-bit binary string.

• Base64URL: Useful for URL parameters. The Compact Binary representation is converted to Base64URL, yielding a 16-byte, URL-safe string without padding (e.g., FHj4WuEAsGhbj7HI).

• URN Format: Standardized in RFC 7972. Formatted as urn:eidr:10.5240:XXXX-XXXX-XXXX-XXXX-XXXX-C.

• Filename Format (EIDR-F): Safe for filesystems where / and . are prohibited. Replaces the prefix with EIDR-F- (e.g., EIDR-F-XXXX-XXXX-XXXX-XXXX-XXXX-C).

4. REST API & SDK Integration

The Java and .NET SDKs are the strongly recommended paths for EIDR integration, abstracting the underlying HTTP XML API.

Authentication

Both the primary REST API and the API Proxy use a custom HTTP Authorization scheme named Eidr. Header Format:

• PasswordShadow is calculated as Base64(SHA-256(Password)) (ensure the Base64 string is padded with = to a multiple of 4 characters).

Core SDK Classes

Operations are handled via dedicated classes in org.eidr.sdk.api:

• Read Operations (Synchronous): Resolution, Query, GraphTraversal, Match.

• Write Operations (Batchable): Registration, Modify, AddRelationship, Delete, Promote, Alias.

API Workflows: Immediate vs. Asynchronous

All EIDR write requests are fundamentally processed as batches. EIDR requires all metadata modifications to pass through the De-Duplication Engine.

1. Immediate (Synchronous) Workflow:

   • Usage: Single-item batches where high confidence exists that manual de-duplication review is not required.

   • Behavior: Returns a definitive result in the initial HTTP response. If a potential duplicate is detected, it returns an error with a list of duplicate candidate IDs and match scores.

2. Non-Immediate (Asynchronous) Workflow:

   • Usage: Standard for most registration pipelines and required for multi-item batches.

   • Behavior: The API accepts the request and returns Tokens (Request Status Token and Operation Tokens).

   • De-Duplication: The registry routes ambiguous matches to EIDR Operations for manual review (which may take up to one business day).

   • Polling: Applications must query the StatusLookup API using the assigned Token until it reaches a terminal state (e.g., success, duplicate, rejected, validation error).

Code Handling for Tokens: Tokens can be system-generated (19-digit strings) or User-Defined Tokens (internal application primary keys). When developing integrations, using User-Defined Tokens is highly recommended to easily correlate EIDR asynchronous callbacks with your internal database states.

5. API Proxy Services (Advanced Reads)

For non-XML reads, the EIDR API Proxy (https://proxy.eidr.org) provides powerful features for modern web developers.

Proxy Capabilities

• Formats Supported: JSON, TSV (Tab-Separated Values), and x-bibliography (academic citations).

• Bulk Resolution: Submitting a JSON array of EIDR IDs to POST /resolve efficiently resolves multiple records simultaneously.

• JSON Queries: Bypasses complex XML XPath queries. The proxy translates custom JSON querying syntax (supporting and, or, not, exists, exact, contains) directly into EIDR XPath.

Example: JSON Bulk Resolution

Example: JSON Query To find all records featuring "Winona Ryder" and "Johnny Depp":

Legacy Documentation

EIDR 2.6 Programmers Guide

Open