Media Objects

A resource that implements the concept of Media Object defined in the AlpineBits^® DestinationData Ontology.

A JSON object representing such a resource MUST contain the following fields: * type: the constant "mediaObjects" that identifies the resource as being of the type media object.

id: a string that uniquely and persistently identifies the media object within a SERVER. See the definition in Basic Fields.
attributes: an object containing the attributes of the media object.
relationships: an object containing the relationships of the media object to other resources.
links: an object containing the links related to the media object.

A media object resource is structured as follows:

{
  "type": "mediaObjects",
  "id": "1",
  "meta": { ... },
  "attributes": { ... },
  "relationships": { ... },
  "links": { ... }
}

1. Meta

See the definition of the meta object in basic-resource-schema.adoc#anchor-metadata.

2. Attributes

The attributes object of the media object resource MUST contain the following fields:

abstract: a datatypes.adoc#anchor-text object containing a brief description of the media object. Nullable. See the definition in basic-resource-schema.adoc#anchor-attributes.
contentType: a string that represents the media type (formerly known as MIME type) of the media object. Non-nullable. Regular Expression.
For example, possible values of contentType include yet are not limited to: "video/mp4", for videos, "image/png", for images, and "audio/mpeg3", for audio.
The allowed media types are defined by IANA. The following regular expression constraints the valid pattern for the contentType string.

"^(application|audio|font|example|image|message|model|multipart|text|video)/[a-zA-Z0-9-.+]+$"

description: a datatypes.adoc#anchor-text object containing a description of the media object. Nullable. Conditional Assignment. See the definition in basic-resource-schema.adoc#anchor-attributes.
duration: a number representing the duration of an audio or a video in seconds. Nullable. Positive value.
If the media object is neither an audio or a video object, i.e., contentType contains a substring following the pattern "^(application|font|example|image|message|model|multipart|text)", duration MUST be set to null.
For example, a short video shared in social platforms may have its duration set to 45 seconds, while a documentary of an event may have its duration set to 5774 seconds (i.e., 1 hour, 36 minutes and 14 seconds).
height: a number representing the height of an image or a video in pixels. Nullable. Positive value.
If the media object is neither an image or a video, i.e. contentType contains a substring following the pattern "^(application|audio|font|example|message|model|multipart|text)", height MUST be set to null.
For example, the height of a Full-HD video is expected to be 1080 pixels, while the height of a 4K video is expected to be 2160 pixels.
license: a string that represents the license applied to the media object. The value of this field SHOULD be a valid license identifier as defined in SPDX License List (e.g. CC-BY-4.0, FreeImage). Nullable.
name: a datatypes.adoc#anchor-text object containing the complete name of the media object. Non-nullable. Conditional Assignment. See the definition in basic-resource-schema.adoc#anchor-attributes.
shortName: a datatypes.adoc#anchor-text object containing a short name of the media object. Nullable. See the definition in basic-resource-schema.adoc#anchor-attributes.
url: a datatypes.adoc#anchor-url string representing the media object’s source. Non-nullable. See the definition in basic-resource-schema.adoc#anchor-attributes.
The url string may be used for the exchange of HTML data with the condition that whenever this HTML data contains some textual description of another resource (i.e., abstract, description, name, or shortName), the resource MUST have the equivalent text field assigned with non-HTML (sanitized) data.
In case the url field is used with this purpose, contentType MUST be set to "text/html" and the URI must be properly encoded. For example:
- HTML data:

<div>This is the solution for sending HTML we were looking for!<div/>

Encoded string:

"url": "data:text/html;charset:utf8,%3Cdiv%3EThis%20is%20the%20solution%20for%20sending%20HTML%20we%20were%20looking%20for%21%3Cdiv%2F%3E"

width: a number representing the width of an image or a video in pixels. Nullable. Positive value.
If the media object is neither an image or a video, i.e., if contentType contains a substring following the pattern "^(application|audio|font|example|message|model|multipart|text)", width MUST be set to null.
For example, the width of a Full-HD video is expected to be 1920 pixels, while the width of a 4K video is expected to be 3840 pixels.

A summary of the attributes object is presented in the table below:

Field	Type	Constraints
abstract	datatypes.adoc#anchor-text	Nullable
contentType	string	Non-nullable, Regular Expression
description	datatypes.adoc#anchor-text	Nullable, Conditional Assignment
duration	number	Nullable, Conditional Assignment, Unit of Measure, Greater than Zero
height	number	Nullable, Conditional Assignment, Unit of Measure, Greater than Zero
license	string	Nullable
name	datatypes.adoc#anchor-text	Nullable, Conditional Assignment
shortName	datatypes.adoc#anchor-text	Nullable
url	datatypes.adoc#anchor-url	Non-nullable
width	number	Nullable, Conditional Assignment, Unit of Measure, Greater than Zero

Field

Type

Constraints

abstract

datatypes.adoc#anchor-text

Nullable

contentType

string

Non-nullable, Regular Expression

description

datatypes.adoc#anchor-text

Nullable, Conditional Assignment

duration

number

Nullable, Conditional Assignment, Unit of Measure, Greater than Zero

height

number

Nullable, Conditional Assignment, Unit of Measure, Greater than Zero

license

string

Nullable

name

datatypes.adoc#anchor-text

Nullable, Conditional Assignment

shortName

datatypes.adoc#anchor-text

Nullable

url

datatypes.adoc#anchor-url

Non-nullable

width

number

Nullable, Conditional Assignment, Unit of Measure, Greater than Zero

3. Relationships

The relationships object of a media object resource MUST contain the following fields:

categories: a basic-resource-schema.adoc#anchor-referencetomany category resources that are instantiated by the media object. See Section Categories. Nullable. Non-empty.

No category is pre-defined by the standard.
copyrightOwner: a basic-resource-schema.adoc#anchor-referencetoone agent resource (see agent) who owns the rights over the media object. Nullable.

A summary of the relationships object is presented in the table below:

Field	Type	Constraints
categories	basic-resource-schema.adoc#anchor-referencetomany object to Categories	Nullable, Non-empty
copyrightOwner	basic-resource-schema.adoc#anchor-referencetoone object to Agents	Nullable

Field

Type

Constraints

4. Links

See the definition of the links object in basic-resource-schema.adoc#anchor-links.

5. Endpoints

The following endpoints in this API specification return media object resources:

https://example.com /2021-04/mediaObjects: returns a collection of media objects.
https://example.com /2021-04/mediaObjects/:id: returns the media object identified by the :id parameter.
https://example.com /2021-04/events/:id/multimediaDescriptions: returns a collection of media objects.
https://example.com /2021-04/venues/:id/multimediaDescriptions: returns a collection of media objects.
https://example.com /2021-04/eventSeries/:id/multimediaDescriptions: returns a collection of media objects.
https://example.com /2021-04/mountainAreas/:id/multimediaDescriptions: returns a collection of media objects.
https://example.com /2021-04/skiSlopes/:id/multimediaDescriptions: returns a collection of media objects.
https://example.com /2021-04/snowparks/:id/multimediaDescriptions: returns a collection of media objects.
https://example.com /2021-04/lifts/:id/multimediaDescriptions: returns a collection of media objects.
https://example.com /2021-04/agents/:id/multimediaDescriptions: returns a collection of media objects.

6. Examples

The following example presents an object containing the minimal information required of a media object resource:

{
  "type": "mediaObjects",
  "id": "1",
  "meta": {
    "dataProvider": null,
    "lastUpdate": null
  },
  "attributes": {
    "abstract": null,
    "contentType": "audio/mpeg3",
    "description": null,
    "duration": null,
    "height": null,
    "license": null,
    "name": null,
    "shortName": null,
    "url": "https://example.com/audio.mp3",
    "width": null
  },
  "relationships": {
    "categories": null,
    "copyrightOwner": null
  },
  "links": {
    "self": "https://example.com/2021-04/mediaObjects/1"
  }
}

asciidoc/examples/mediaobject.min.json

The following example presents an object representing a media object resource:

{
  "type": "mediaObjects",
  "id": "1",
  "meta": {
    "dataProvider": "https://example.com",
    "lastUpdate": "2020-04-01T08:00:00+02:00"
  },
  "attributes": {
    "abstract": {
      "eng": "My first image sent as an example for the API."
    },
    "contentType": "image/png",
    "description": {
      "eng": "My first image sent as an example for the API."
    },
    "duration": null,
    "height": 300,
    "license": "FreeImage",
    "name": {
      "ita": "La mia immagine",
      "deu": "Mein bild",
      "eng": "My image"
    },
    "shortName": {
      "eng": "My image"
    },
    "url": "https://example.com/image.png",
    "width": 400
  },
  "relationships": {
    "categories": {
      "data": [
        {
          "type": "categories",
          "id": "example/panoramic-photo"
        }
      ],
      "links": {
        "related": "https://example.com/2021-04/mediaObjects/1/categories"
      }
    },
    "copyrightOwner": {
      "data": {
        "type": "agents",
        "id": "0"
      },
      "links": {
        "related": "https://example.com/2021-04/mediaObjects/1/copyrgihtOwner/"
      }
    }
  },
  "links": {
    "self": "https://example.com/2021-04/mediaObjects/1"
  }
}

asciidoc/examples/mediaobject.full.json