Asset

An asset is any image, video, audio, 3D model or other file that you want the platform to provide services for. You register assets, the platform provides services for those assets.

For historical reasons the API name of this resource class is vocab:Image, and images are still the most common scenario.

The services the platform provides include:

IIIF Image API service for image assets (register an image, the platform provides an image service)
Thumbnail creation for image assets
Transcoding audio and video assets to web friendly derivatives
Providing IIIF Authorisation Flow 2.0 Access control for any kind of asset
Storing related and derived files and metadata for an asset (OCR data, transcriptions, subtitles - anything you need to connect to your assets)

An example image asset:

{
  "@context": "https://dlcs.github.io/vocab/context/future.json",
  "@id": "https://api.dlcs.example/customers/2/spaces/5/images/b2921371x_0001.jp2",
  "@type": "vocab:Image",
  "id": "b2921371x_0001.jp2",
  "space": 5,
  "imageService": "https://dlcs.example/iiif-img/2/5/b2921371x_0001.jp2",
  "thumbnailImageService": "https://dlcs.example/thumbs/2/5/b2921371x_0001.jp2",
  "created": "2023-07-20T09:56:39.0649160Z",
  "origin": "https://s3-eu-west-1.amazonaws.com/example-bucket/digitised/b2921371x/v1/data/objects/b2921371x_0001.jp2",
  "batch": "https://api.dlcs.example/customers/2/queue/batches/871143",
  "maxUnauthorised": -1,
  "maxWidth": 0,
  "openFullMax": 0,
  "duration": 0,
  "width": 8008,
  "height": 5754,
  "finished": "2023-07-20T09:56:50.5261830Z",
  "ingesting": false,
  "error": "",
  "tags": [],
  "string1": "b2921371x",
  "string2": "b2921371x",
  "string3": "b2921371x",
  "number1": 0,
  "number2": 0,
  "number3": 0,
  "roles": [],
  "adjuncts": "https://api.dlcs.example/customers/2/spaces/5/images/b2921371x_0001.jp2/adjuncts",
  "metadata": "https://api.dlcs.example/customers/2/spaces/5/images/b2921371x_0001.jp2/metadata",
  "storage": "https://api.dlcs.example/customers/2/spaces/5/images/b2921371x_0001.jp2/storage",
  "manifests": [],
  "mediaType": "image/jp2",
  "family": "I",
  "deliveryChannels": [
    {
      "@type": "vocab:DeliveryChannel",
      "channel": "iiif-img",
      "policy": "use-original"
    },
    {
      "@type": "vocab:DeliveryChannel",
      "channel": "thumbs",
      "policy": "https://api.dlcs.example/customers/2/deliveryChannelPolicies/thumbs/default"
    },
    {
      "@type": "vocab:DeliveryChannel",
      "channel": "file",
      "policy": "none"
    }
  ]
}

/customers/{customer}/spaces/{spaceId}/images/{id}

Method	Label	Expects	Returns	Status
GET	Retrieve an Asset	-	vocab:Image	200 OK, 404 Not Found
PUT	Create or replace an asset	vocab:Image	vocab:Image	200 OK, 201 Created, 400 Bad request
PATCH	Update supplied field of asset	vocab:Image	vocab:Image	200 OK, 400 Bad request, 404 Not found
DELETE	Delete an image	-	owl:Nothing	204 No Content, 404 Not Found

💻 Asset HTTP operations HTTP operations directly on an Asset

id

The model id of an asset. This is the part of an asset identifier within the space.

An asset API resource URL is of the form /customers/{customer}/spaces/{spaceId}/images/{modelId}, and the public facing URL of a delivered asset will be (or begin with, depending on whether the channel adds further path elements to the end) /{channel}/{customer}/{space}/{id}, where {customer} may (for public facing URLs) be the customer.name string value or the integer customer identifier.

You can’t update id for an existing asset (via PATCH), and if you create or update an asset via PUT, it is not required (an id in the body is ignored — the last path element of the PUT URL determines the asset’s identity; if you supply @id, the platform will validate that it matches the PUT URL). You MUST supply id when registering assets in batches via the Queue. See Registering Assets for more details.

Generally you should select your asset id values carefully, so that they are meaningful to you. You could use the asset file name (as in the above example), or an identifier associated with the file in a digital preservation system, or given to the asset during a digitisation workflow. Whatever you choose, it will form part of the public facing URL of the image service, or AV derivatives, or access file version.

domain	range	readonly	writeonly
vocab:Image	xsd:string	True	False

mediaType

The media type (also known as MIME type, or sometimes content type) of the asset. This identifies what kind of file the asset is. This is mandatory on newly registered assets — and because a PUT is a create-or-replace operation, it must be supplied on every PUT, not just the first (see Reprocessing). The platform does not inspect assets to determine this value (file format identification), or rely on file extensions to deduce types (your asset origins may not have file extensions). The platform uses the first type part of the mediaType (e.g., image, audio, text) to make processing decisions, in combination with the asset’s deliveryChannels. It also provides the value when serving on the file deliveryChannel.

domain	range	readonly	writeonly
vocab:Image	xsd:string	False	False

Examples might be:

image/tiff
audio/mpeg
application/vnd.ms-excel
text/plain

family

A single-character code classifying the asset: I (image), T (timebased — audio or video), or F (file). It is present on every asset the API returns.

The platform derives the family when an asset is registered, from its deliveryChannels (falling back to its mediaType). It cannot be edited afterwards: an update that changes family is rejected with 400 Bad Request.

domain	range	readonly	writeonly
vocab:Image	xsd:string	True	False

space

The integer identifier of the customer Space. This is readonly on an asset except when sent in a batch to the queue (see registering assets), where a single batch of assets may be intended for different spaces. That is, you can set it on an asset that has yet to be given an @id within the system. After this point the value of space will always match the space part of the asset identifier. You do not need to supply it on API operations other than creation of assets to the queue, but if you do, it must match the expected space from the asset ID.

domain	range	readonly	writeonly
vocab:Image	xsd:integer	True*	False

imageService

The URL of the IIIF Image API service for this asset, on the public delivery host rather than the API host. This property is present on every asset the API returns, whatever its delivery channels; the service it points to is only backed by the platform when the asset has the iiif-img delivery channel.

domain	range	readonly	writeonly
vocab:Image	xsd:string	True	False

thumbnailImageService

The URL of the IIIF Image API service for this asset’s thumbnails, on the public delivery host. Unlike imageService, this property is only present when the asset has the thumbs delivery channel.

domain	range	readonly	writeonly
vocab:Image	xsd:string	True	False

origin

Origin endpoint from where the original image can be acquired (or was acquired). This is always a URI but is not necessarily an HTTP(S) URI - it could be SFTP, S3 or some other protocol, as long as the platform understands how to retrieve an asset from the URI and, where applicable, has an origin strategy configured to negotiate any access control protecting the asset.

For some assets the origin is only used once, at registration time. While the asset record retains the information, you don’t need to maintain the asset at the origin URL indefinitely. For other assets the platform may retrieve the asset from the origin multiple times, and expects to be able to fetch it quickly when needed. This is not the default behaviour - see origin strategy for details of optimised origins.

If an update of an asset modifies the value of origin, the asset will be re-processed (for example, a source image is replaced with a higher quality version). For some types of asset this action might modify other fields, such as the height and width if the asset is an image. See Reprocessing for which property changes trigger re-processing, and how PUT and PATCH updates differ.

domain	range	readonly	writeonly
vocab:Image	xsd:string (a URI)	False	False

created

Date the asset was created (first known to the platform, rather than anything about the file at the origin).

domain	range	readonly	writeonly
vocab:Image	xsd:dateTime	True	False

batch

The batch this image was ingested in (most recently). This is a link to the batch object created when this asset was last ingested via a queue.

An asset created directly with a direct PUT will not have a batch link.

Batches may also be archived, and an asset may lose the reference to its ingest batch after a long period (greater than one year).

domain	range	readonly	writeonly
vocab:Image	🔗 vocab:Batch	True	False

The batch link on an asset points directly to the batch resource:

/customers/{customer}/queue/batches/{batchId}

Method	Label	Expects	Returns	Status
GET	Retrieve the asset’s batch	-	vocab:Batch	200 OK

💻 Get asset batch Follow the batch link from an asset to retrieve its batch

ingesting

If true, the asset is still being processed by the platform and is not ready for public asset delivery via delivery channels. There is no limit to how many assets may be placed on a queue through batch submissions, so an asset can be in the ingesting state for a long period of time. The platform scales up to process large queue backlogs when they arise.

domain	range	readonly	writeonly
vocab:Image	xsd:boolean	True	False

finished

Date the asset left the ingesting state. This value will be cleared if the asset is submitted for reprocessing (an asset can’t have a finished value and have ingesting=true at the same time).

domain	range	readonly	writeonly
vocab:Image	xsd:dateTime	True	False

error

A string message from any error(s) encountered the last time this asset was processed. If re-processed the value will be cleared.

domain	range	readonly	writeonly
vocab:Image	xsd:string	True	False

duration

The length in milliseconds of a time-based asset. This will be set by the platform when the asset is processed.

domain	range	readonly	writeonly
vocab:Image	xsd:integer	True	False

width

The width in pixels of a bitmap-based image. This will be set by the platform when the asset is processed.

domain	range	readonly	writeonly
vocab:Image	xsd:integer	True	False

height

The height in pixels of a bitmap-based image. This will be set by the platform when the asset is processed.

domain	range	readonly	writeonly
vocab:Image	xsd:integer	True	False

deliveryChannels

Delivery channels specify the way(s) in which you want the platform to make your assets available.

It is possible for an asset to have no delivery channels, in which case it is known to the platform but not yet served.

You can assign delivery channels explicitly at registration time, or you can omit the property when registering and allow the platform to assign default delivery channels based on the values of customer.defaultDeliveryChannels and space.defaultDeliveryChannels. An asset resource returned by API will always list delivery channels.

See Delivery Channels for full details.

domain	range	readonly	writeonly
vocab:Image	Array of vocab:DeliveryChannel	False	False

Note that the value of this property is an inline array of vocab:DeliveryChannel, not a link to a collection.

roles

An array of Role URIs. The roles a user needs to have to access the output of a delivery channel for this asset. A user acquires roles by interacting with an Auth Service.

Roles are always URIs of the form {...}/customers/{customer}/roles/{roleId}, i.e., members of the customer.roles collection.

See Access Control for a general discussion. Note that for image assets, setting a positive value for openFullMax allows a user to see images below the configured size without roles.

domain	range	readonly	writeonly
vocab:Image	Array of 🔗 vocab:Role	False	False

Example:

"roles": [
  "https://api.dlcs.example/customers/2/roles/staff",
  "https://api.dlcs.example/customers/2/roles/reading-room"
]

maxWidth

Restricts the maximum permitted pixel response as defined in the Image API.

domain	range	readonly	writeonly
vocab:Image	xsd:integer	False	False

The platform only supports maxWidth, not maxHeight or maxArea.

The IIIF Image API specification says “If maxWidth is specified and maxHeight is not, then clients should infer that maxHeight = maxWidth.” In the IIIF Cloud Services platform, maxWidth therefore defines a square bounding box. So you can’t get a 100 w x 1000 h image if maxWidth is 100.

As well as governing the allowed pixel responses from the level 2 iiif-img delivery channel, this value is also considered by the thumbs delivery channel. The platform will not generate thumbnails larger than the maxWidth limit even if the policy defines them.

If the image has roles and openFullMax is 0, no thumbnails will be produced (this behaviour is not dependent on maxWidth but on the requirement that nothing on the thumbs delivery channel is subject to access control; if you offer thumbs they must be accessible anonymously).

See Size Restrictions for examples of the effects of the maxWidth and openFullMax properties.

The value of maxWidth must either be 0, indicating unset (a system default will still be imposed) or a positive integer equal to or greater than 256, up to a platform-configured upper bound (default 5000). Values between 0 and 256 exclusive are disallowed, as are values above the configured upper bound.

openFullMax

Only applies when an image has roles, and the image request region is /full/. This value is ignored if the image does not have roles (it is not considered an error, as you may vary roles for other reasons). Pixel requests on the iiif-img delivery channel whose region is /full/ and whose size fits a bounding square openFullMax on an edge are permitted whether the user has any of the roles or not (therefore also for anonymous users).

domain	range	readonly	writeonly
vocab:Image	xsd:integer	False	False

On the thumbs delivery channel, thumbs will be generated by the policy as long as their resulting sizes are equal to or less than the bounding square defined by openFullMax.

This setting allows an access-controlled image to have open thumbnails. Typical settings are low - e.g., 200 or 400 - sizes suitable for thumbnails but not for reading text in an image.

A value of 0 or less than 0 is considered unset.

See Size Restrictions for examples of the effects of the maxWidth and openFullMax properties.

The value of openFullMax must either be 0, indicating unset, or a positive integer.

maxUnauthorised

The legacy size gate, superseded by maxWidth and openFullMax. It is the maximum size of request allowed before roles are enforced, relating to the effective whole image size, not the individual tile size. 0 means no open option; -1 (the default) means no authorisation.

domain	range	readonly	writeonly
vocab:Image	xsd:integer	False	False

Every asset response includes maxUnauthorised (it is -1 unless set), so you will see it on assets even though new registrations should not use it.

You cannot mix the old and new properties in one request: supplying maxUnauthorised together with maxWidth or openFullMax is rejected with 400 Bad Request (“‘maxUnauthorised’ cannot be set when ‘maxWidth’ or ‘openFullMax’ is set”). When migrating an asset from maxUnauthorised to the replacement properties, set the new properties and leave maxUnauthorised out of the request body.

domain	range	readonly	writeonly
vocab:Image	Array of xsd:string	False	False