Catalog Integration Overview

This section provides information on catalog integration with the Vionlabs Discovery Platform. The catalog integration is a critical element of the overall integration and is required in all current use cases. This integration normally occurs with the Content Management System (CMS) of the Vionlabs partner.

The fundamental purpose of the catalog integration is to allow the Vionlabs Discovery Platform to understand the content and structure of the partner's media catalog/inventory. The platform uses this information to configure and enable a range of functionality including, but is not limited to:

• understanding of partner IDs for use in result APIs
• linkage of series/season/episodes
• locating media assets for automated processing
• management of availability windows for result APIs
• reconciliation of media assets with the contents of the Vionlabs central data platform
• tracking of changes in the content inventory over time
• automated checking and verification of assets and catalog information

Catalog API Integration

The catalog API integration provides a REST API for managing the catalog. This includes methods for submitting catalog items (upsert operation) and deletion of assets by item id.

Methods are also provided for getting current information on a catalog item. However, it should be noted that as the catalog processing is eventually consistent, there may be some delay prior to changes submitted to the catalog becoming available.

To understand the details of the catalog API, you may download the OpenAPI specification or access detailed online documentation as:

• Swagger Documentation
• ReDoc Documentation

Data Updates for Individual Items

All integration methods allow for data mutation. This can be an addition of fields, removal of fields or mutation of the field data. This does not, however, apply to changing an item's id as this cannot be tracked. It should be noted, however, that mutating fields of some types can cause re-processing of data and/or video files.

In all cases, deletion of an asset does not physically delete the information from the Vionlabs Discovery Platform. The item data is retained but marked as deleted. After deletion has occurred, creation of a new catalog item with the same type and id will result in the item being reinstated in the catalog. As a result, any processed data associated with the original item will immediately be made available to results APIs.

Catalog Model

The Vionlabs catalog model provides a standardized superset of information that can be provided in the catalog integration. Most properties in this model are optional for many use cases, but partners are encouraged to provide as much information as possible as this can greatly reduce the complexity of provisioning additional functionality and use cases in the future.

The model is based around a single JSON object type Catalog Item. A complete and documented JSON schema for this object is available for download here: catalog_model_schema.json

The catalog model is a collection of these Catalog Item objects. To aid in understanding the model, and for convenience, additional information on the model components and their uses is provided below.

Catalog Model Structure

The catalog item objects are composed collectively to form a complete model that requires all episodic item types (series, season and episode) to be specified. Episodic information is provisioned using the EpisodicInfo data structure for seasons and the ExtendedEpisodicInfo data structure for episodes.

Episodic Lifecycle Rules

The following lifecycle rules are applied for episodic content:

• deletion of a parent item (series or season) will automatically cause all children of that item (i.e., seasons and/or episodes) to be deleted
• deletion of the last remaining child (season or episode) of a parent item will cause the parent to be flagged for deletion

Content Identifiers

There is a mandatory field for each item id which should be populated with the partner's internal identifier for the item. No requirements are placed on the structure or nature of this id save that it should be provided in the item as a string. This id for the item will be used in all interactions with the platform to identify items, e.g., result APIs. This removes the requirement for partners to adapt to any identifiers used internally by the platform.

Catalog Item Types

A mandatory enumeration field exists in the model named item_type. This can take the following values:

• episode : indicating that the item represents a piece of episodic content, i.e., a piece of content that is part of a series
• standalone : indicating that the item represents a piece of content which is not episodic e.g. a movie
• series : indicating that the item represents a series
• season : indicating that the item represents a season

This information is mandatory as it is critical for the platform to be able to identify which content assets are episodic and how they are grouped into collections. An example of this is when making content recommendations for series. The recommendation is made on series as a whole, but content A/V processing occurs on individual assets. To achieve this, an aggregation of data from multiple episodes to series is required.

Episodic Information

The episodic_info object is used for season items and is mandatory. For seasons, the episode_number field should not be included.

The extended_episodic_info object is used for episode items and is mandatory. All fields are required.

Asset Information

Asset information is mandatory in most use cases for episode and standalone item types. In particular, the file_uri field must be provided to allow the media content processing workflow within the Vionlabs Platform to locate assets and associate the results of processing with specific catalog identifiers. The interpretation of this field is dependent on the type of media content integration selected for the partner integration:

• Upload Integration (integration with partner uploaded files): this should be the URI of a file in a cloud object storage e.g.: gs://customer/upload/media-file.mp4 (supported schemes are gs:// and s3://)
• On-Prem Integration (on partner premises file processing): this should be the URI in the on-premises file location e.g.: file://local-drive/media/media-file.mp4

The duration of the asset may also be provided. If available, it will be used as part of automated QA workflows.

Window Information

It is possible, but not mandatory, to include window information for items in the catalog. This provides the Vionlabs Discovery Platform with essential information in determining over which time period items should appear in certain types of results. Please consult API documentation for each use case to see which use cases make use of this information.

If window start information is not available, the platform will include items in results as soon as processing is completed.

If window end information is not available, the platform will only exclude items from results if the item has been marked as deleted.

Poster URLs

Poster URLs are optional but extremely useful if provided. If provided, posters are made available to our internal tools that are used for manual QA processes.

Release Year

The original release year of an item may be provided. If available, it will be used to aid in reconciliation of items against Vionlabs' global content data stores as well as in both manual and automated QA processes.

External Ids

It is possible to include identifiers for the item from external data providers, such as metadata providers. If available, this information will be used to aid in reconciliation of items against Vionlabs' global content data stores. Additionally, it may be used as part of both automated and manual QA processes to ensure the quality of results.

Metadata

It is possible to provide metadata information on catalog items such as genres, keywords, cast and crew information, and descriptions. All of this metadata information is optional in the majority of use cases. However, it should be provided if possible, as the Vionlabs Platform can use this information to aid in reconciliation against Vionlabs global content data stores as well as both automatic and manual QA processes.

Operational fields

The model includes a number of fields that may be used to signal actions that should be taken by the system in response to receiving item data. Most notably, a flag is included that can be used to instruct the system to mark an item as deleted from the catalog.