Metadata views

Last updated
Save as PDF
Share
1. Share
2. Tweet
3. Share

A metadata view representation is a JSON document that describes a set of metadata fields (by their IDs and localized display). It can be used to display metadata values along with their labels and create metadata input masks or editors.

Every collection MAY have a metadata view, the URL of which is specified in the metadata.href attribute of the collection info representation. For more information about metadata views outside the scope of the API, see Creating a metadata view.

This is a localized representation, see Localization.

Metadata view representation

{
  "id": "2b142203-ba71-45b2-80d3-2a510998afca",
  "href": "/fotoweb/editors/2b142203-ba71-45b2-80d3-2a510998afca",
  "name": "Standard Small",
  "builtinFields": {
    "title": {...},
    "description: {...},
    "tags": {...},
    "status": {...},
    "rating": {...},
    "notes": {...}
  },
  "detailRegions": [{...}, ...],
  "thumbnailFields": {
    "label": {...},
    "firstLine": {...},
    "secondLine": {...},
    "additionalFields": {...}
  }
}

where:

Attribute	Type	Description
`id`	GUID (String)	Unique ID
`href`	URL (String)	URL
`name`	String	Human-readable display name
`builtinFields`	Object	Describes metadata fields with special semantic roles, such as the title or description of an asset.
`builtinFields.title`	Field description (Object)	Description of the built-in title field
`builtinFields.description`	Field description (Object)	Description of the built-in description field
`builtinFields.tags`	Field description (Object)	Description of the built-in tags field
`builtinFields.status`	Field description (Object)	Description of the built-in status field
`builtinFields.rating`	Field description (Object)	Description of the built-in rating field
`builtinFields.notes`	Field description (Object)	Description of the built-in notes field
`detailRegions`	Array of region descriptions (Array of objects)	Contains descriptions of all metadata fields
`thumbnailFields`	Object	Describes metadata fields that are shown in thumbnails
`thumbnailFields.label`	Field description (Object)	Description of the metadata field that provides the short description of a thumbnail
`thumbnailFields.firstLine`	Field description (Object)	Description of the metadata field that provides the first line of the long description of a thumbnail
`thumbnailFields.secondLine`	Field description (Object)	Description of the metadata field that provides the second line of the long description of a thumbnail
`thumbnailFields.additionalFields`	Array of field descriptions (Array of objects)	Descriptions of the metadata fields whose values are shown in a thumbnail in addition to the short and long description.

Field description

A field description is a JSON object that describes a single metadata field in a metadata view.

{
  "field": {
    "id": 10,
    "label": "Status",
    "max-size": 1,
    "multi-instance": true | false,
    "multiline": true | false,
    "data-type": "text" | "date" | "integer" | "real" | "boolean",
    "validation: {
      "min": ... | null,
      "max": ... | null,
      "regexp": "..." | null,
    }
  },
  "isWritable": true | false,
  "required": true | false,
  "taxonomy-only": true | false
}

where

Attribute	Type	Description
`field.id`	Integer	Numeric metadata field ID
`label`	String	Localized human-readable display name of the metadata field
`data-type`	Enum (String)	Type of allowed values of the field. See the table below.
`max-size`	Integer	Maximum length of a field of type `text`.
`multi-instance`	Boolean	`true` if field has zero or more values (bag field) `false` if field has exactly one value
`multiline`	Boolean	For fields of type `text`, indicates that input masks should allow multi-line text input
`isWritable`	Boolean	`true` if the field may be edited in metadata update and upload requests `false` if the field is read-only
`required`	Boolean	`true` if the field must have a non-empty value (or at least one value if `multi-instance` is `true`) `false` if the field may be empty
`taxonomy-only`	Boolean	`true` if input masks should only allow users to select values from a taxonomy associated with the field `false` if users should be allowed to enter arbitrary values that conform with the remaining specifications

Note

FotoWeb does not validate the values of metadata fields. Furthermore, the FotoWeb API expects and returns all field values as strings or arrays of strings (for bag fields with multi-instance set to true).
The format specifications in a field description are only suggestions for restrictions that should be imposed in input masks. However, not complying with these format specifications may result in field values not being compliant with the XMP standard.

The data-type field can have the following values:

Data Type	JSON Type	Value	Description
`text`	String	Arbitrary string Maximum length given by `max-size` Input mask should allow multi-line input if `multiline` is `true`.	Arbitrary text
`date`	String	ISO 8601 date/time value While other formats are allowed, the XMP standard mandates ISO 8601. It is recommended to include a time zone specifier, especially if the time zone is known and not UTC. Input masks SHOULD provide a date picker or similar UI widget to ease user input. Presentation to the user SHOULD be in a human-readable, localized date and time format and MAY also be relative (e.g., "5 weeks ago")	A date and time value
`integer`	String	A whole (integer) positive or negative number, represented as in JSON a string, e.g., `"123"`	An integer number
`real`	String	A fractional (real) positive number, represented in JSON as a string in fixed or floating point format, e.g., `12.34` or `1.23e+4`.	A real number
`boolean`	String	A truth value, represented in JSON as the string `"true"` or `"false"`.	A boolean value

Region description

A region description is a JSON object that describes a logical grouping of metadata fields in a metadata view.

{
  "name": "Overview",
  "fields": [{...}, ...]
}

where

Attribute	Type	Description
`name`	String	Human-readable display name of the region
`fields`	Array of field descriptions (Array of objects)	Descriptions of fields in the region

Presentation of metadata to a user SHOULD group metadata into regions and SHOULD present regions and fields in the order they are defined in a metadata view representation (detailRegions attribute).

Input masks SHOULD also group input in the same way and the same order.

Localization

Metadata field labels may be localized to different languages based on the metadata configuration and site settings. The same rules apply as in the standard FotoWeb user interface.

The language is selected by sending an Accept-Language header in the request. This header is optional.

The format of this header is the one specified in the HTTP specification. It is possible to specify multiple languages. FotoWeb returns a localized representation in the supported language that best matches the most preferred language in the header.

Example:

Accept-Language: nb, no, en-US, en pt-BR

This header indicates that languages are preferred in the following order:

Norwegian (Bokmål)
Norwegian (any)
English (US)
English (any)
Portuguese (Brazilian)

If no Accept-Language header is specified, the representation will be returned in the default language configured for the FotoWeb site. See Choosing a default site language.

Note: If the FotoWeb site is configured to enforce the default language, the Accept-Language header is ignored.