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-resource-schema.adoc#anchor-attributes.
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 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 for the media object. Nullable. See definition in basic-resource-schema.adoc#anchor-attributes.
categories: an array of datatypes.adoc#anchor-type strings identifying the types instantiated by the media object. Nullable. No type is pre-defined by the standard.
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 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 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 definition in basic-resource-schema.adoc#anchor-attributes.
url: a datatypes.adoc#anchor-url string representing the media object’s source. Non-nullable.
The url string may be used for the exchange of HTML data, which case the 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
categories	Array of datatypes.adoc#anchor-type	Nullable, Non-empty
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

3. Relationships

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

copyrightOwner: an object representing a reference towards an agent resource who owns the rights over the media object. Nullable.

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

Field	Type	Constraints
copyrightOwner	A Reference object to an Agent	Nullable

Field

Type

Constraints

copyrightOwner

A Reference object to an Agent

Nullable

4. Links

See 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 /1.0/mediaObjects: returns a collection of media objects.
https://example.com /1.0/mediaObjects/:id: returns the media object identified by the :id parameter.
https://example.com /1.0/events/:id/multimediaDescriptions: returns a collection of media objects.
https://example.com /1.0/venues/:id/multimediaDescriptions: returns a collection of media objects.
https://example.com /1.0/eventSeries/:id/multimediaDescriptions: returns a collection of media objects.
https://example.com /1.0/mountainAreas/:id/multimediaDescriptions: returns a collection of media objects.
https://example.com /1.0/trails/:id/multimediaDescriptions: returns a collection of media objects.
https://example.com /1.0/snowparks/:id/multimediaDescriptions: returns a collection of media objects.
https://example.com /1.0/lifts/:id/multimediaDescriptions: returns a collection of media objects.
https://example.com /1.0/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,
    "categories": null,
    "contentType": "audio/mpeg3",
    "description": null,
    "duration": null,
    "height": null,
    "license": null,
    "name": null,
    "shortName": null,
    "url": "http://example.com/audio.mp3",
    "width": null
  },
  "relationships": {
    "copyrightOwner": null
  },
  "links": {
    "self": "http://example.com/1.0/mediaObjects/1"
  }
}

asciidoc/examples/mediaobject.min.json

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

{
  "type": "mediaObjects",
  "id": "1",
  "meta": {
    "dataProvider": "http://example.com",
    "lastUpdate": "2020-04-01T08:00:00+02:00"
  },
  "attributes": {
    "abstract": {
      "eng": "My first image sent as an example for the API."
    },
    "categories": [
      "example/panoramic-photo"
    ],
    "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": "http://example.com/image.png",
    "width": 400
  },
  "relationships": {
    "copyrightOwner": {
      "data": {
        "type": "agents",
        "id": "0"
      },
      "links": {
        "related": "http://example.com/1.0/mediaObjects/1/copyrgihtOwner/"
      }
    }
  },
  "links": {
    "self": "http://example.com/1.0/mediaObjects/1"
  }
}

asciidoc/examples/mediaobject.full.json