Skip to main content
Documentation & User Guides | Fotoware

Metadata views

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

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:

  1. Norwegian (Bokmål)
  2. Norwegian (any)
  3. English (US)
  4. English (any)
  5. 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.

  • Was this article helpful?