Data Types

This page defines data types that are commonly used by many External API requests. The page is divided in several sections that start with general information about how the types are supposed to work.

Basic

This section defines basic data types used in the External API specification.

Type	Description
`string`	An UTF-8 encoded string
`boolean`	`true` or `false`
`integer`	An integer number, i.e. [-][0-9]+[0-9]*

Extended

This section describes extended data types used in the External API specification.

array

The External API makes use of JSON arrays often. We indicate the element type in the brackets, e.g. array[string].

The empty array [] is allowed.

Examples

["String1", "String2"]

[]

object

The External API makes use of JSON objects.

The empty object {} might be allowed.

Examples

{
  "myObject1": {
    "key": "value";
  },
  "myObject2": {
    "array": [1, 2, 3]
  },
  "valid": false
}

{}

file

This data type indicates that a file is needed as parameter.

flavor

Opencast uses flavors to locate tracks, attachments and catalogs associated to events. Flavors have a type and a subtype and are written in the form type + "/" + subtype.

flavor ::= type + "/" + subtype whereas both type and subtype consist of ([a-z][A-Z][1-9])+([a-z][A-Z][1-9][+-])*

Example

dublincore/episode

property

Opencast often uses sets of key-value pairs to associate properties to objects. The External API uses JSON objects to represent those properties. Both the name of the JSON object field and its value are of type string.

Example

{
  "key": "value",
  "live": "true"
}

Date and Time

Type	Encoding	Description
`date`	ISO 8601	Date
`datetime`	ISO 8601	Date and Time

Examples

date:

2018-03-11

datetime:

2018-03-11T13:23:51Z

Recurrence Rule

To define a set of recurring events within a given time period, Opencast uses recurrence rules.

For more details about reccurrence rules, please refer to the Internet Calendaring and Scheduling Core Object Specification (iCalendar).

Example

"rrule":"FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=16;BYMINUTE=0"

Please note that BYHOUR is specified in UTC.

Metadata Catalogs

The External API is designed to take full advantage of the powerful metadata facilities of Opencast.

Opencast distinguishes between bibliographic metadata and technical metadata:

Bibliographic metadata is supposed to describe the associated objects and to be used to present those objects to endusers (e.g. in a video portal).
Technical metadata is used by Opencast to manage objects (e.g. permissions, processing, scheduling)

For events and series, Opencast manages bibliographic metadata in metadata catalogs. There are two kind of metadata catalogs:

The default metadata catalogs for events (dublincore/episode) and series (dublincore/series)
An arbitrary number of configurable extended metadata catalogs can be configured for both events and series

While the extended metadata can be fully configured, the default metadata catalogs are supposed to hold a minimum set of defined metadata fields.

As the metadata catalogs are configurable, the External API provides means of gathering the metadata catalog configuration.

This is done by "/api/events/{event_id}/metadata" and "/api/series/{series_id}/metdata". Those requests return self-describing metadata catalogs that do not just contain the values of all metadata fields but also a list of available metadata fields and their configuration.

Note that the Opencast configuration defines which metadata catalogs are available for events and series.

The following sections define data types that are used to manage metadata catalogs.

fields

Each metadata catalogs has a list of metadata fields that is described as array of JSON objects with the following fields:

Field	Optional	Type	Description
`id`	no	`string`	Technical identifier of the metadata field
`value`	no	`string`	Current value of the metadata field
`label`	no	`string`	Displayable name of the metadata field (i18n)
`type`	no	`string`	Type of the metadata field
`readOnly`	no	`boolean`	Whether this metadata field is read-only
`required`	no	`boolean`	Whether this metadata field is mandatory
`collection`	yes	`string`	Pre-defined list of values as JSON object
`translatable`	yes	`boolean`	Whether the field `value` supports i18n

Example

[
  {
    "readOnly": false,
    "id": "title",
    "label": "EVENTS.EVENTS.DETAILS.METADATA.TITLE",
    "type": "text",
    "value": "Test Event Title",
    "required": true
  },
  {
    "translatable": true,
    "readOnly": false,
    "id": "language",
    "label": "EVENTS.EVENTS.DETAILS.METADATA.LANGUAGE",
    "type": "text",
    "value": "",
    "required": false
  },
  {
    "translatable": true,
    "readOnly": false,
    "id": "license",
    "label": "EVENTS.EVENTS.DETAILS.METADATA.LICENSE",
    "type": "text",
    "value": "",
    "required": false
  },
  [...]
]

values

To modifiy values of metadata catalogs, a JSON array with JSON objects contained the following fields is used:

Field	Required	Description
`id`	yes	The technical identifier of the metadata field
`value`	yes	The value of the metadata field

Notes:

Fields which are not included in catalog_values will not be updated
Attempting to write readonly fields will result in error
Attempting to write empty values to a required field will result in error

[
  {
    "id": "title",
    "value": "Captivating title - edited"
  },
  {
    "id": "creator",
    "value": ["John Clark", "Thiago Melo Costa"]
  },
  {
    "id": "description",
    "value": "A great description - edited"
  }
]

catalog

Besides the metadata configuration, the full metadata catalog configuration includes some additional fields describing the catalog itself:

Field	Type	Description
label	`string`	Displayable name of the metadata catalog
flavor	`string`	The flavor of the metadata catalog
fields	`fields`	An array of JSON objects describing the metadata field configurations of the metadata catalogs

Example

  {
    "flavor": "dublincore/episode",
    "title": "EVENTS.EVENTS.DETAILS.CATALOG.EPISODE",
    "fields": [
      {
        "readOnly": false,
        "id": "title",
        "label": "EVENTS.EVENTS.DETAILS.METADATA.TITLE",
        "type": "text",
        "value": "Test 1",
        "required": true
      },
      [...]
    ]
  }
]

catalogs

The metadata configuration including all metadata catalogs of a given objects is returned as JSON array whereas its elements are of type catalog.

Example

[
  {
    "flavor": "dublincore/episode",
    "title": "EVENTS.EVENTS.DETAILS.CATALOG.EPISODE",
    "fields": [
      {
        "readOnly": false,
        "id": "title",
        "label": "EVENTS.EVENTS.DETAILS.METADATA.TITLE",
        "type": "text",
        "value": "Test 1",
        "required": true
      },
      {
        "readOnly": false,
        "id": "subjects",
        "label": "EVENTS.EVENTS.DETAILS.METADATA.SUBJECT",
        "type": "text",
        "value": [],
        "required": false
      },
      {
        "readOnly": false,
        "id": "description",
        "label": "EVENTS.EVENTS.DETAILS.METADATA.DESCRIPTION",
        "type": "text_long",
        "value": "",
        "required": false
      },
      [...]
    ]
  }
]

Access Control Lists

Opencast uses access control lists (ACL) to manage permissions of objects. Each access control list is associated to exactly one object and consists of a list of access control entries (ACE). The access control entries are a list of triples <role, action, allow> which read like "Users with role role are allowed to perform action action on the associate object if allow is true".

Opencast defines the following ACL actions:

Action	Description
`read`	Read access
`write`	Write access

Depending on the configuration of Opencast, there can be additional ACL actions.

ace

The access control entries are represented as JSON objects with the following fields:

ACE field	Required	Type	Description
`role`	yes	`string`	The role this ACE affects
`action`	yes	`string`	The actions this ACE affects
`allow`	yes	`boolean`	Whether role is allowed to perform the action

Example

  {
    "allow": true,
    "action": "write",
    "role": "ROLE_ADMIN"
  }

acl

The access control lists are represented as JSON arrays with element type ace.

Example

[
  {
    "allow": true,
    "action": "write",
    "role": "ROLE_ADMIN"
  },
  {
    "allow": true,
    "action": "read",
    "role": "ROLE_USER"
  }
]

Workflow

workflow_retry_strategy

The retry strategy of a workflow operation definition in case of an error. The following values are possible:

Value	Description
`none`	no retry
`retry`	restart the operation
`hold`	keep the operation in hold state

workflow_state

The state the workflow instance is currently in. The following values are possible:

Value	Description
`instantiated`	The workflow instance was instantiated, but is not yet running
`running`	The workflow instance is running
`stopped`	The workflow instance was stopped
`paused`	The workflow instance was paused
`succeeded`	The workflow instance has succeeded
`failed`	The workflow instance has failed
`failing`	The workflow instance has failed and is currently running the error handling workflow

workflow_operation_state

The state the workflow operation instance is currently in. The following values are possible:

Value	Description
`instantiated`	The workflow operation instance was instantiated, but is not yet running
`running`	The workflow operation instance is running
`paused`	The workflow operation instance was paused
`succeeded`	The workflow operation instance has succeeded
`failed`	The workflow operation instance has failed
`skipped`	The workflow operation instance was skipped
`retry`	The workflow operation instance has failed and a retry is currently running

operation_definition

The workflow operation_definition entries are represented as JSON objects with the following fields:

Field	Type	Description
`operation`	`string`	The operation of this workflow operation definition
`description`	`string`	The description of this workflow operation definition
`configuration`	`property`	The configuration for this workflow operation definition
`if`	`string`	The condition of this workflow operation definition that is required to be true for this operation to be executed
`unless`	`string`	The condition of this workflow operation definition that is required to be false for this operation to be executed
`fail_workflow_on_error`	`boolean`	Whether an error during this workflow operation definition fails the workflow
`error_handler_workflow`	`string`	The identifier of the exception handler workflow of this workflow operation definition
`retry_strategy`	`workflow_retry_strategy`	The retry strategy of this workflow operation definition in case of an error
`max_attempts`	`integer`	The number of attempts made to execute this workflow operation definition

operation_instance

The workflow operation_instance entries are represented as JSON objects with the following fields:

Field	Type	Description
`identifier`	`integer`	The unique identifier of this workflow operation instance (equals the job identifier)
`operation`	`string`	The operation of this workflow operation instance
`description`	`string`	The description of this workflow operation instance
`configuration`	`property`	The configuration for this workflow operation instance
`state`	`workflow_operation_state`	The state of this workflow operation instance
`start`	`datetime`	The start date and time of this workflow operation instance
`completion`	`datetime`	The completion date and time of this workflow operation instance
`time_in_queue`	`integer`	The number of milliseconds this workflow operation instance waited in a service queue
`host`	`string`	The host that executed this workflow operation instance
`if`	`string`	The condition of this workflow operation instance that is required to be true for this operation to be executed
`unless`	`string`	The condition of this workflow operation instance that is required to be false for this operation to be executed
`fail_workflow_on_error`	`boolean`	Whether an error during this workflow operation instance fails the workflow
`error_handler_workflow`	`string`	The identifier of the exception handler workflow of this workflow operation instance
`retry_strategy`	`workflow_retry_strategy`	The retry strategy of this workflow operation instance in case of an error
`max_attempts`	`integer`	The number of attempts made to execute this workflow operation instance
`failed_attempts`	`integer`	The number of failed attempts to execute this workflow operation instance

Statistics

parameters

The Statistics endpoint can list the available statistics providers. Optionally, the endpoint provides information about supported data query parameters using this JSON object.

Field	Type	Description
`name`	`string`	The name of the parameter to be used in requests
`type`	`string`	The type of this parameter to be used in requests
`optional`	`boolean`	Whether the parameter must be specified in queries
`values`	`array`	Values to be used for enumeration types (only for type `enumeration`)

The following types are available:

Type	Description
`string`	UTF-8 encoded string
`date`	ISO 8601 encoded date
`datetime`	ISO 8601 encoded date and time
`integer`	An integer number, i.e. [-][0-9]+[0-9]*
`boolean`	`true` or `false`
`enumeration`	One of the values provided by the field `values`

Playlists

Playlist

A playlist is represented as a JSON object with the following fields:

Field	Type	Description
`id`	`string`	Identifier. Will be created if not set.
`entries`	`List<PlaylistEntry>`	List of entries.
`title`	`string`	Metadata.
`description`	`string`	Metadata.
`creator`	`string`	Metadata.
`updated`	`unix epoch in milliseconds`	Metadata. Updated by Opencast with current time when playlist gets updated.
`accessControlEntries`	`List<AccessControlEntry>`	List of access control entries, basically an ACL.

Playlist Entry

An entry for a playlist as a JSON object. There are different kinds of entries:

Field	Type	Description
`id`	`long`	Identifier. Will be created if not set.
`contentId`	`string`	Identifier for the content of the entry. What the "content" is is defined by `type`.
`type`	`string`	Enumeration, current possible values are EVENT, INACCESSIBLE. Typically EVENT, set to INACCESSIBLE by Opencast if the requesting user lacks permissions on the event.