Media Objects¶

A resource that implements the concept of Media Object defined in the AlpineBits® 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 ???.
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": { ... }
}

Meta¶

See the definition of the meta object in ???.

Attributes¶

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

abstract: a ??? object containing a brief description of the media object. Nullable. See the definition in ???.
author: a string that identifies the author of a media object, like an image, a video, or a song. Nullable.

When assigned a value, the author SHOULD follow the example below representing the author’s name and e-mail contact:
```
"author": "\"Mary Jane\" <mary.jane@example.com>"
```
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 link:https://www.iana.org/assignments/media-types/media-types.xhtmlIANA. 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 ??? object containing a description of the media object. Nullable. Conditional Assignment. See the definition in ???.
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 link:https://spdx.org/licenses/SPDX License List (e.g. CC-BY-4.0, FreeImage). Nullable.
name: a ??? object containing the complete name of the media object. Non-nullable. Conditional Assignment. See the definition in ???.
shortName: a ??? object containing a short name of the media object. Nullable. See the definition in ???.
url: a ??? string representing the media object’s source. Non-nullable. See the definition in ???.
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	???	Nullable
author	string	Nullable
contentType	string	Non-nullable, Regular Expression
description	???	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	???	Nullable, Conditional Assignment
shortName	???	Nullable
url	???	Non-nullable
width	number	Nullable, Conditional Assignment, Unit of Measure, Greater than Zero

Relationships¶

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

categories: a ??? category resources that are instantiated by the media object. See Section ???. Nullable. Non-empty.

No category is pre-defined by the standard.
licenseHolder: a ??? agent resource (see agent) who holds the rights over the media object. Nullable.

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

Field	Type	Constraints
categories	??? object to ???	Nullable, Non-empty
licenseHolder	??? object to ???	Nullable

Links¶

See the definition of the links object in ???.

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,
    "author": 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,
    "licenseHolder": null
  },
  "links": {
    "self": "https://example.com/2022-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."
    },
    "author": "Leonardo da Vinci",
    "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/2022-04/mediaObjects/1/categories"
      }
    },
    "licenseHolder": {
      "data": {
        "type": "agents",
        "id": "0"
      },
      "links": {
        "related": "https://example.com/2022-04/mediaObjects/1/copyrgihtOwner/"
      }
    }
  },
  "links": {
    "self": "https://example.com/2022-04/mediaObjects/1"
  }
}

asciidoc/examples/mediaobject.full.json