Catalog Integration Overview

This section provides information of 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 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.

Using your Catalog API base URL, the OpenAPI specification is available at /catalog/openapi.json, Swagger UI at /catalog/docs, and ReDoc at /catalog/redoc.

Data Updates for Individual Items

PUT /catalog/v1/item is a full replacement, not a partial update. When updating an item, include every field that should be retained. Omitted optional fields are cleared or reset to their defaults. To change one field, retrieve the current item, apply the change locally, and submit the complete item.

If the submitted item is identical to the stored item, the request succeeds without applying changes or starting a new processing job. Metadata can be updated without media reprocessing when asset_info.file_uri remains unchanged. Changing asset_info.file_uri requires operations.force_asset_reprocess to be set to true.

Deletion is soft: the item data is retained and marked as deleted. Submitting the same type and id again reinstates the item, and previously processed results remain available.

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

Episodic Catalog Ingestion

The Catalog API supports one ingestion contract. Standalone content is submitted as standalone items. Episodic assets are submitted as episode items using extended_episodic_info.

• The platform creates or updates the corresponding series and season records when an episode is submitted.
• Series and season items may also be submitted directly when their metadata needs to be managed explicitly.
• For a directly submitted season, use episodic_info to identify its parent series.

Episodic Lifecycle Rules

• Parent series and season items are created when they are first referenced by an episode.
• Parent information inferred from episodes, such as titles, is updated from the most recently submitted episode.
• Deleting the last episode in a season deletes that season; if no seasons remain, the series is also deleted.
• Deleting a season or series also deletes its child items.

Guide: Correcting a Season Assigned to the Wrong Series

A season cannot be moved to another series by updating its series_id. Season IDs remain bound to their original series, even after deletion, so deleting the season does not make its season_id reusable under another series.

To correct an incorrectly assigned season:

1. Retrieve and retain the complete representation of every episode assigned to the incorrect season.
2. Choose a new, unique season_id for the destination series, for example series2_season1. The season may be submitted explicitly, or it will be created when the first episode is submitted with the new hierarchy.
3. For each episode, submit a complete PUT /catalog/v1/item request using the same episode id and the same asset_info.file_uri. Update extended_episodic_info.series_id, series_title, season_id, season_title, and season_number for the destination hierarchy.
4. Do not set operations.force_asset_reprocess. Keeping the same episode ID and media URI updates the catalog hierarchy without reprocessing the media.
5. After all episodes have been repointed and verified, delete the old season if it is no longer needed. Moving episodes does not automatically delete the old season. If the old series has no remaining seasons, deleting the old season may also delete that series.

Because item updates are full replacements, every episode request must include all fields that should be retained. Do not reuse the old season_id for the destination series.

Content Identifiers

Every item requires a non-empty id representing the partner's identifier. IDs are stored as strings and are used in API interactions and result APIs. An ID must not contain the / character.

IDs must be unique across the catalog's item types and episodic hierarchy. An episode ID must differ from its series and season IDs, a series or season ID cannot already belong to another item type, and a season ID cannot be reused under a different series.

Catalog Item Types

A mandatory enumeration field exists in the model named 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

Episode items must use extended_episodic_info to describe their series and season hierarchy. Episode submissions containing episodic_info are rejected.

The extended_episodic_info object contains the series and season identifiers and titles, together with season and episode numbering. The season_id may be omitted; in that case, the platform generates it from series_id and season_number.

For season items submitted directly, use episodic_info to identify the parent series. Series items do not require episodic information.

The asset_model option on the retrieval endpoint controls only the response representation. It does not enable a second ingestion model.

Asset Information

Asset information is required for media processing of episode and standalone items. The file_uri associates the catalog item with the media file to process.

Virtual items are the exception: when virtual is true, file_uri may be omitted, but external_ids must be provided.

The asset duration may be provided for automated QA workflows. An optional video_playback_uri must use the gs:// or s3:// scheme.

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 in an item 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

Catalog items may include metadata such as genres, keywords, cast and crew, and descriptions. These fields are optional for most use cases, but should be provided when available because they can support content reconciliation and automated or manual quality-assurance workflows.

Operational Fields

The operations.deleted flag marks an item as deleted. The dedicated delete endpoint provides another way to perform the same soft-delete operation.

The operations.force_asset_reprocess flag requests media reprocessing and is required when changing asset_info.file_uri. It can be used only for an existing, non-deleted asset. Reprocessing removes the existing asset results before starting a new processing job and is subject to a configured cooldown period.