Skip to main content

Metadata

Fields​

(🟦) Metadata fields marked with this symbol are Opencast-managed: they are read-only for users/external applications. All other fields can be freely changed, as long as validity checks pass.

When duplicating an event, all fields are copied 1:1 unless specified otherwise.

General​

  • id: ID 🟦: unique among all events.
    • Can be chosen when creating an event, but cannot be changed afterwards.
    • If no ID is specified while creating an event, Opencast generates a generated unguessable ID.
    • When duplicating an event, the new event gets a new unguessable ID.
  • title: NonBlankString: a short title that is the main label associated with this event for users. Plain text.
  • description: string?: user-specified, human-readable description, potentially quite long.
    • TODO: Decide whether this is plain text, markdown or anything else. External apps displaying this need to know that. Some basic formatting options might be nice?
  • creators: NonBlankString[]: The people mainly responsible for creating this video and/or presenting the talk which this video is a recording of. Should contain human-readable names and not usernames. Plain text. This is the main "who?"-information shown in the UIs; other fields in extraMetadata (e.g. dct:contributor) might be shown too, but less prominently.
  • language: LangCode?: describes the (main) language of this event and its metadata. For example, the audio language and (if applicable) language of video content is more important than the language of available subtitles. Generally, assets can have their own language specified.
  • series: SeriesID?: optional ID of the series this event belongs to. Must be a valid series ID of an existing series at all time.
  • owner: Username: TODO figure out details
  • createdBy: Username 🟦: username of the user that created this event.
    • Like created, this refers to the moment when the event is first added to the database, not necessarily when it is ingested.
    • This refers to the user with which the API request is authorized, e.g. potentially an API user and not referring to an actual human person.
    • Technical field, not intended to be shown to normal users.
    • Set by Opencast and cannot be changed.
    • When duplicating an event, the new event has this field set to the duplicating user.

Time-data​

  • startTime: DateTime?: Actual real life datetime when the video recording started or will start, with timezone. If this is not applicable, for example because it's a short movie, this should be undefined. UIs should use this as primary date to show for a video and if unset, fallback to created.
  • endTime: DateTime?: Like startTime, but when the video recording stopped. Due to cutting, recording pauses and etc, the duration is not necessarily end - start.
  • duration: Milliseconds 🟦: duration of the event. As specified in "assets", this needs to always match the duration of all non-internal tracks.
  • modified: Timestamp 🟦: Timestamp of when anything about this event was last changed.
    • More precisely: at any point in time since modified, all fields, assets, ACL and any other part of the event data model need to have the exact same value as they have at the present moment. Whenever anything about an event described in this data model changes, modified has to be set to now().
      • Noteworthy case: when a series is deleted and the event's series field is set to null, the event's modified needs to change.
      • Opencast should try its best to not update modified when it's not necessary (e.g. when the title is set to the current value), but it is not a bug if modified is set to now() unnecessarily.
    • When duplicating an event, the new event has modified = now(), i.e. it is not copied.
  • created: Timestamp 🟦: Timestamp of when the event was created in Opencast. It is set once when the event is first stored in Opencast's DB, and never changed again.
    • This also implies that scheduled event's created date is when the scheduling took place, not the time it is scheduled for (that would be startDate).
    • When duplicating an event, the new event has created = now(), i.e. it is not copied.

Flags​

  • isLive: bool 🟦: TODO this is currently stored per track, figure out if that's useful

Extra metadata​

  • extraMetadata: Map<Label, Json>: additional metadata that Opencast never interprets, but just stores and passes along.
    • The keys of this map consists of a namespace and a field name, separated by :, i.e. ns:name. Both parts must consist of only a-z, A-Z, 0-9, - and _.
    • The values of this map are arbitrary JSON values, i.e. Booleans, numbers, strings, arrays, maps or null. Items of arrays & maps can recursively be any JSON value as well.
    • Unlike the "extended metadata" before, using extraMetadata does work out of the box and does not incur any relevant performance overhead. Therefore, applications are encouraged to add useful data here, e.g. studip:course-id, oc-studio:version or ethz:room-number.

Community documentation​

There should be a community document for specifying rules, as well as collecting used fields and best practices around extraMetadata. That way, common requirements are identified quickly and the community can converge towards a standard.

Official namespaces:

  • oc: reserved.
  • ocx: OC eXperimental for fields that might get promoted to core metadata field in the future.
    • ocx:downloadable: bool: a flag indicating whether users are allowed to download this video (i.e. tracks attached to this event). This can inform external apps whether to show a download button or to enable anti-download protection. The exact effects of this flag are deliberately unspecified, this merely states an intent.
    • ocx:listed: bool: specifies whether this event should be considered "list", meaning that users can find it via search. If it is false, users have to know the ID of the event (e.g. via a series or playlist) in order to access it.
    • ocx:explicitContent: bool: specifies whether this event contains content that is considered "explicit", like swear words or whatnot. This is required for some integrations like iTunes.
  • dct: refers to the Dublin Core Terms specification, e.g. dct:rightsHolder refers to the rightsHolder property of DC terms. It should be avoided to set fields that are already mapped from core fields, like dct:title, which is mapped to the OC core metadatum title.

Community namespaces:

  • ...

Generally, anyone should be able to add to the "Community namespaces" section via pull request against this document: its purpose is to document what is used, not for the OC committers to control what external apps do. In other words: a PR against that section is not asking for permission.

Dublin Core mapping​

As you can see above, the event metadata is not literally a Dublin Core catalog anymore. Dublin Core should be considered an exchange format, not a storage format! Of course, standards make sense and therefore, many Opencast metadata fields correspond exactly to a Dublin Core field. Opencast can offer an API that emits a DCC for an event. That DCC XML is created on the fly in the API handler.

The mapping is as follows:

  • identifier: id
  • title: title
  • description: description
  • creator: creators
  • language: language
  • isPartOf: series (i.e. the ID)
  • modified: modified
  • extend: duration as ISO 8601 duration
  • date or temporal???: TODO combination of startDate and endDate
  • created or dateSubmitted or issued???: TODO created
  • Additionally, all fields in extraMetadata with dct namespace are mapped directly to the corresponding property, e.g. dct:license is mapped to license.

TODO: Should we also define a mapping for OAIMPH? Does that make sense?

Open questions
  • ...