joystream/testnets/acropolis/specification/runtime/content-directory.md

Content Directory

Table Of Contents

• Name
• Dependencies
• Design
• Future TODOs
• State
• Events
• Dispatchable Methods
  • add_metadata
  • update_metadata

Name

ContentDirectory

Dependencies

• The Storage System.

Design

Motivation

Once data is stored on the network, it must be made discoverable. Part of this is to assign meaning to any stored data. For these purposes, the Content Directory is introduced.

The Content Directory is a list of ContentMetadata entries on the runtime. Each ContentMetadata entry can:

• Contain a JSON payload conforming to a schema identified by a SchemaId.
• Contain a list of ContentId as children of the entry.

As ContentMetadata is itself identified by a ContentId, it is inextricably linked to a DataObject with the same identifier, and intended to describe this object.

Therefore the runtime enforces that for any ContentMetadata:

1. A DataObject with the same ContentId exists.
2. An active StorageRelationship for the ContentId exists.

Additionally, ContentMetadata may exist in a published or unpublished state. Of course, nothing is entirely private on the runtime, but only published ContentMetadata is intended for inclusion in content listing, searches or other user interfaces for the Content Directory. Unpublished entries can e.g. be used as drafts during the creation process.

Hierarchy

ContentMetadata may contain child content IDs, which are used to indicate a hierarchy of content of sorts. Each child must itself have a meaning; therefore, for each child content ID, an appropriate ContentMetadata entry must also exist, with the above constraints enforced.

This means that when creating a hierarchy of ContentMetadata, it must be done in a leaf-to-root order.

The purpose of creating such a hierarchy depends on the SchemaId used in the root entry. Possible uses are:

• For structuring podcast/video episodes in a series.
• For providing multiple language tracks, subtitle tracks, commentary, etc. for video content.
• etc.

Hierarchy and Publishing

Note in particular that in hierarchically structured content, the published state may be interpreted differently depending on whether the metadata describes a root, branch or leaf element, and on the metadata schema.

Largely, it is the published state of root entries that determines whether content is discoverable at all. For branch or leaf elements, the flag may be ignored - but such a decision is outside the scope of this document, and belongs in a description of schemata to be used.

For example, in episodic content like a podcast, the root level element may describe the podcast series, and contain:

1. Image DataObjects, for describing the podcast. These may be considered to be published if the root element itself is published.
2. Episode DataObjects, each of which may stay in a draft state until it is finalized. Here, the published flag should be interpreted.

Using schema identifiers in ContentMetadata permits easy decision making in rendering or indexing apps as to how the hierarchy should be interpreted.

Content Creation

The content creation protocol is as follows:

1. Create one (or several related) DataObjects as described in the Data Directory section of the Storage Module.
2. Create appropriate ContentMetadata entries in a leaf-to-root order in the ContentDirectory.
3. Publish the root ContentMetadata (see the Hierarchy section) to make content discoverable.

State

• MetadataByContentId: a map of ContentId to matching ContentMetadata Objects.

• PublishedRootContent: a vector of published ContentIds that describe root content in a ContentMetadata hierarchy - in other words, the discoverable ContentIds.

Note: This list should be moved off-chain once an indexing node provides content discovery services; it exists solely for not having to scan the entire MetadataByContentId map in the pioneer app.

Events

• MetadataAdded: ContentMetadata has been added to MetadataByContentId. The event payload is the ContentId of the matching metadata.

• MetadataUpdated: ContentMetadata has been updated. The event payload is the ContentId of the matching metadata.

• RootContentUpdated: a ContentMetadata that represents root content in a metadata hierarchy has been updated. The payload is the ContentId, and a flag indicating whether or not this content is published.

Note: This event exists to trigger updates in either pioneer's rendering of the content directory, or an indexing node's internal database. It's a special case of MetadataUpdated that can be listened to explicitly.

Dispatchable Methods

add_metadata

Payload

• The publisher origin.
• content_id: the ContentId for which the ContentMetadata applies.
• data: a ContentMetadata struct.
• is_root: a boolean flag indicating whether the metadata represents the root of a metadata hierarchy.

Description

Create a new ContentMetadata object for the given ContentId. All but optional fields must be supplied. It is possible to set the published field here immediately, but for hierarchical metadata that is discouraged.

Errors

• The origin is not an active member.
• There already exists ContentMetadata for this ContentId.
• For the given ContentId, the Storage Module does not have any currently active StorageRelationship entries, i.e. the content does not exist on the network. Note: it would be possible to limit this error only to situations in which published flag is to be set.

Side effect(s)

• The ContentMetadata struct is added under the given ContentId to the MetadataByContentId map.
• If the ContentMetadata's published flag is set, and is_root is set, the ContentId is also added to PublishedRootContent.

Event(s)

• MetadataAdded
• If the ContentMetadata's published flag is set, and is_root is set, also RootContentUpdated is emitted.

update_metadata

Payload

• The publisher origin.
• content_id: the ContentId for which the ContentMetadata applies.
• data: a ContentMetadataUpdate struct.
• is_root: a boolean flag indicating whether the metadata represents the root of a metadata hierarchy.

Description

Modify an existing ContentMetadata for the given ContentId. With the ContentMetadataUpdate struct, only fields to be updated must be supplied.

Errors

• The origin is not an active member.
• The origin is not the original creator of the ContentMetadata.
• There exists no ContentMetadata for this ContentId.
• For the given ContentId, the Storage Module does not have any currently active StorageRelationship entries, i.e. the content does not exist on the network. Note: it would be possible to limit this error only to situations in which published flag is to be set afterwards (aka explicitly set now, already set).

Side effect(s)

• The ContentMetadata struct is modified under the given ContentId to the MetadataByContentId map.
• If the ContentMetadataUpdate's published flag is set, and is_root is set, the ContentId may also added to PublishedRootContent.

Event(s)

• MetadataUpdated
• If the ContentMetadataUpdate's published flag is set, and is_root is set, also RootContentUpdated is emitted.