joystream/metadata-protobuf/doc/index.md

Protocol Documentation

Table of Contents

• proto/Channel.proto

  • ChannelCategoryMetadata
  • ChannelMetadata
    

• proto/Council.proto

  • CouncilCandidacyNoteMetadata
    

• proto/Forum.proto

  • ForumPostMetadata
  • ForumPostReaction

  • ForumThreadMetadata

  • ForumPostReaction.Reaction

• proto/Membership.proto

  • MembershipMetadata
    

• proto/Person.proto

  • PersonMetadata
    

• proto/Playlist.proto

  • PlaylistMetadata
    

• proto/Series.proto

  • SeasonMetadata
  • SeriesMetadata
    

• proto/Storage.proto

  • DistributionBucketFamilyMetadata
  • DistributionBucketOperatorMetadata
  • GeoCoordiantes
  • GeographicalArea
  • NodeLocationMetadata

  • StorageBucketOperatorMetadata

  • GeographicalArea.Continent

• proto/Video.proto

  • License
  • MediaType
  • PublishedBeforeJoystream
  • VideoCategoryMetadata
  • VideoMetadata
    

• proto/WorkingGroups.proto

  • AddUpcomingOpening
  • ApplicationMetadata
  • OpeningMetadata
  • OpeningMetadata.ApplicationFormQuestion
  • RemoveUpcomingOpening
  • SetGroupMetadata
  • UpcomingOpeningMetadata
  • WorkingGroupMetadata

  • WorkingGroupMetadataAction

  • OpeningMetadata.ApplicationFormQuestion.InputType

• Scalar Value Types

Top

proto/Channel.proto

ChannelCategoryMetadata

Field	Type	Label	Description
name	string	optional	Category Name

ChannelMetadata

Field	Type	Label	Description
title	string	optional	Channel Title
description	string	optional	Channel Description
is_public	bool	optional	Wether to display channel to the public
language	string	optional	ISO_639-1 Language Code
cover_photo	uint32	optional	index into external assets array
avatar_photo	uint32	optional	index into external assets array
category	uint64	optional	Channel Category Id

Top

proto/Council.proto

CouncilCandidacyNoteMetadata

Field	Type	Label	Description
header	string	optional	Candidacy header text
bullet_points	string	repeated	Candidate program in form of bullet points
banner_image_uri	string	optional	Image uri of candidate's banner
description	string	optional	Candidacy description (md-formatted)

Top

proto/Forum.proto

ForumPostMetadata

Field	Type	Label	Description
text	string	optional	Post text content (md-formatted)
repliesTo	uint32	optional	Id of the post that given post replies to (if any)

ForumPostReaction

The enum must be wrapped inside "message", otherwide it breaks protobufjs

ForumThreadMetadata

Field	Type	Label	Description
title	string	optional	Thread title
tags	string	repeated	Tags accociated with the thread. Any update overrides all current tags. Only the first {MAX_TAGS_PER_FORUM_THREAD} (const exposed via @joystream/metadata-protobuf/consts) tags are taken into account. In order to unset current tags, '' must be provided as value.

ForumPostReaction.Reaction

Name	Number	Description
CANCEL	0	This means cancelling any previous reaction
LIKE	1

Top

proto/Membership.proto

MembershipMetadata

Field	Type	Label	Description
name	string	optional	Member's real name
avatar	uint32	optional	Member's avatar - index into external assets array
about	string	optional	Member's md-formatted about text

Top

proto/Person.proto

PersonMetadata

Field	Type	Label	Description
first_name	string	optional
middle_name	string	optional
last_name	string	optional
about	string	optional
cover_photo	uint32	optional	index into external assets array
avatar_photo	uint32	optional	index into external assets array

Top

proto/Playlist.proto

PlaylistMetadata

Field	Type	Label	Description
title	string	optional
videos	uint64	repeated	Videos in the playlist

Top

proto/Series.proto

SeasonMetadata

Field	Type	Label	Description
title	string	optional
description	string	optional
cover_photo	uint32	optional	index into external assets array
persons	uint64	repeated	Person(s) referenced by PersonId involved in this Season

SeriesMetadata

Field	Type	Label	Description
title	string	optional
description	string	optional
cover_photo	uint32	optional	index into external assets array
persons	uint64	repeated	Person(s) referenced by PersonId involved in this Series

Top

proto/Storage.proto

DistributionBucketFamilyMetadata

Field	Type	Label	Description
region	string	optional	ID / name of the region covered by the distribution family (ie. us-east-1). Should be unique.
description	string	optional	Additional, more specific description of the region
areas	GeographicalArea	repeated	Standarized geographical areas covered by the family (providing [{}] will unset the current value)
latency_test_targets	string	repeated	List of targets (hosts/ips) best suited latency measurements for this family

DistributionBucketOperatorMetadata

Field	Type	Label	Description
endpoint	string	optional	Root distribution node endpoint (ie. https://example.com/distribution)
location	NodeLocationMetadata	optional	Information about node's phisical location (providing {} will unset current value)
extra	string	optional	Additional information about the node / node operator

GeoCoordiantes

Field	Type	Label	Description
latitude	float	optional
longitude	float	optional

GeographicalArea

Field	Type	Label	Description
continent	GeographicalArea.Continent	optional
country_code	string	optional	ISO 3166-1 alpha-2 country code
subdivision_code	string	optional	ISO 3166-2 subdivision code

NodeLocationMetadata

Field	Type	Label	Description
country_code	string	optional	ISO 3166-1 alpha-2 country code (2 letters)
city	string	optional	City name
coordinates	GeoCoordiantes	optional	Geographic coordinates (providing {} will unset current value)

StorageBucketOperatorMetadata

Field	Type	Label	Description
endpoint	string	optional	Root storage node endpoint (ie. https://example.com/storage)
location	NodeLocationMetadata	optional	Information about node's phisical location (providing {} will unset current value)
extra	string	optional	Additional information about the node / node operator

GeographicalArea.Continent

Name	Number	Description
AF	1
NA	2
OC	3
AN	4
AS	5
EU	6
SA	7

Top

proto/Video.proto

License

License types defined by Joystream

Field	Type	Label	Description
code	uint32	optional	License code defined by Joystream. reference
attribution	string	optional	Text for licenses that require an attribution
custom_text	string	optional	Text for custom license type

MediaType

Codec, Container, MIME media-type information

Field	Type	Label	Description
codec_name	string	optional	Codec corresponding to name field from FFmpeg
container	string	optional	Video container format, eg. 'MP4', 'WebM', 'Ogg' ref
mime_media_type	string	optional	MIME Media Type, eg. 'video/mp4' ref

PublishedBeforeJoystream

Publication status before joystream

Field	Type	Label	Description
is_published	bool	optional	Was video published before joystream platform
date	string	optional	Date of publication: 'YYYY-MM-DD' ISO-8601

VideoCategoryMetadata

Field	Type	Label	Description
name	string	optional	Category name

VideoMetadata

Field	Type	Label	Description
title	string	optional	Video Title
description	string	optional	Video Description
video	uint32	optional	index into external assets array
thumbnail_photo	uint32	optional	index into external assets array
duration	uint32	optional	Lengths of video in seconds
media_pixel_height	uint32	optional	Resolution of the video (Height)
media_pixel_width	uint32	optional	Resolution of the video (Width)
media_type	MediaType	optional	Encoding and Container format used
language	string	optional	ISO_639-1 Language Code
license	License	optional	License type for the media
published_before_joystream	PublishedBeforeJoystream	optional	Date of publication
has_marketing	bool	optional	Does video have marketing or advertising in the stream
is_public	bool	optional	Should video be publicy visible yet
is_explicit	bool	optional	Does Video have explicit language or scenes
persons	uint64	repeated	Person(s) referenced by PersonId involved in this video
category	uint64	optional	Video Category Id

Top

proto/WorkingGroups.proto

AddUpcomingOpening

Field	Type	Label	Description
metadata	UpcomingOpeningMetadata	optional	Upcoming opening metadata

ApplicationMetadata

Field	Type	Label	Description
answers	string	repeated	List of answers to opening application form questions

OpeningMetadata

Field	Type	Label	Description
short_description	string	optional	Short description of the opening
description	string	optional	Full description of the opening
hiring_limit	uint32	optional	Expected number of hired applicants
expected_ending_timestamp	uint32	optional	Expected time when the opening will close (Unix timestamp)
application_details	string	optional	Md-formatted text explaining the application process
application_form_questions	OpeningMetadata.ApplicationFormQuestion	repeated	List of questions that should be answered during application

OpeningMetadata.ApplicationFormQuestion

Field	Type	Label	Description
question	string	optional	The question itself (ie. "What is your name?"")
type	OpeningMetadata.ApplicationFormQuestion.InputType	optional	Suggested type of the UI answer input

RemoveUpcomingOpening

Field	Type	Label	Description
id	string	optional	Upcoming opening query-node id

SetGroupMetadata

Field	Type	Label	Description
new_metadata	WorkingGroupMetadata	optional	New working group metadata to set (can be a partial update)

UpcomingOpeningMetadata

Field	Type	Label	Description
expected_start	uint32	optional	Expected opening start (timestamp)
reward_per_block	uint64	optional	Expected reward per block
min_application_stake	uint64	optional	Expected min. application stake
metadata	OpeningMetadata	optional	Opening metadata

WorkingGroupMetadata

Field	Type	Label	Description
description	string	optional	Group description text (md-formatted)
about	string	optional	Group about text (md-formatted)
status	string	optional	Current group status (expected to be 1-3 words)
status_message	string	optional	Short status message associated with the status

WorkingGroupMetadataAction

Field	Type	Label	Description
set_group_metadata	SetGroupMetadata	optional
add_upcoming_opening	AddUpcomingOpening	optional
remove_upcoming_opening	RemoveUpcomingOpening	optional

OpeningMetadata.ApplicationFormQuestion.InputType

Name	Number	Description
TEXTAREA	0
TEXT	1

Scalar Value Types

| .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby | | ----------- | ----- | --- | ---- | ------ | -- | -- | --- | ---- | | double | | double | double | float | float64 | double | float | Float | | float | | float | float | float | float32 | float | float | Float | | int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) | | int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | int64 | long | integer/string | Bignum | | uint32 | Uses variable-length encoding. | uint32 | int | int/long | uint32 | uint | integer | Bignum or Fixnum (as required) | | uint64 | Uses variable-length encoding. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum or Fixnum (as required) | | sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) | | sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | int64 | long | integer/string | Bignum | | fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | uint32 | uint | integer | Bignum or Fixnum (as required) | | fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum | | sfixed32 | Always four bytes. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) | | sfixed64 | Always eight bytes. | int64 | long | int/long | int64 | long | integer/string | Bignum | | bool | | bool | boolean | boolean | bool | bool | boolean | TrueClass/FalseClass | | string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | string | string | string | String (UTF-8) | | bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | []byte | ByteString | string | String (ASCII-8BIT) |

Referencing Assets

Applications that process messages that contain a uint32 field that references an asset such as a cover photo or video, should interpret this value as a zero based index into an array/vector that is received external (out of band) to the protobuf message.

Example in context of query-node processing the runtime event VideoCreated

// Runtime event associated with creating a Video
VideoCreated(video_id: VideoId, video: Video, assets: Vec<NewAsset>, params: VideoCreationParameters)

struct VideoCreationParameters {
  in_category: VideoCategoryId,
  // binary serialized VideoMetadata protobuf message
  meta: Vec<u8>,
}

// suppose assets is a vector of two elements. This is the "out of band" array being referenced by the VideoMetadata message
assets = [
    NewAsset::Uri("https://mydomain.net/thumbnail.png"),
    NewAsset::Upload({
       content_id,
       ipfs_hash,
       size,
       ...
    }),
];

meta = VideoMetadata {
    ...
    // refers to second element: assets[1] which is being uploaded to the storage system
    video: 1,
    // refers to the first element assets[0] which is being referneced by a url string.
    thumbnail_photo: 0,
    ...
};