Primitive Data Types

This page describes data types whose definitions may not be commonly recognized. Unless otherwise stated, these are expressed as strings in the JSON content traversing the Lightroom APIs.

Lowercase UUID

A universally-unique identifier where the hex digits are represented using lower case letters and the hyphens are omitted. Used to identify virtually all objects in the Lightroom cloud.

User-visible string

A user-visible string is interpreted to mean any string that is valid in JSON, with the following exceptions:

• UTF8 encoding is expected.
• Unicode control characters (including CR, LF, tab) are disallowed.
• Clients are expected to display these as user-visible strings without further interpretation. Clients are responsible for escaping strings to prevent unwanted interpretations.
• This is specifically not formatted HTML. Any HTML markup that might be entered into the string should not cause the corresponding HTML formatting to occur. Clients are responsible for escaping characters such as <, >, and & to prevent browser side effects.
• User-visible strings must be non-empty.
• Some of these restrictions might be overridden in specific cases.

ISO 8601 date stamps

An ISO 8601 date stamp, unless otherwise specified, is a timestamp in the W3C-specific subset of the ISO 8601 format.

• Timestamps intended for sorting should be specified in UTC and include the trailing "Z" indicator of such. Clients should use the closest available approximation of UTC. The Lightroom server will always use a highly-accurate UTC time.
• Timestamps intended for user display and grouping (especially date-based grouping) should use local timestamps and include an appropriate designator of the actual time zone.

Cleansing Invalid Datetime Values

The datetime values provided by clients in some model payloads have validation rules. A datetime might come from metadata generated by a camera or a third party application which may be using nonstandard formatting that does not pass the validation rules. It is recommended that clients check payload values for validity before sending the data to the cloud. Specifically for datetime values, if the value does not pass validation it is recommended that clients attempt some simple fixes to the datetime to retain as much information as possible and to get to a valid value.

Validating dates locally before sending to the cloud is preferred. If the cloud rejects a date as invalid, it is recommended to remove the date or come up with a suitable replacement for required dates as detailed below, in order to avoid bugs involving confusion and disagreement between the cloud and client on the correct values, which sometimes triggers looping behavior where the client attempts to send the same data to the cloud repeatedly, in some cases thousands of times.

• If the seconds value is 60, indicating a possible leap second, convert it to 59

  • e.g. 2017-03-09T15:47:60.000Z becomes 2017-03-09T15:47:59.000Z

• Try removing the time and submitting the date only.

  • Most datetime values in the data model require time, so a client would need to replace the time with 00:00:00 (e.g. 2017-03-09T00:00:00)
  • Many times do not require timezone, but some times require a valid timezone and some specifically require GMT timezone with a Z timezone specification (e.g. 2017-03-09T00:00:00Z). For all times requiring a time zone, the recommendation is to specify GMT (Z) timezone.
  • Most datetimes in the xmp section of the asset payload allow date only (e.g. 2017-03-09)

• If the date is invalid, then a client will need to omit the field or come up with a suitable replacement for required fields.

  • The required field captureDate in the asset payload allows the special value 0000-00-00T00:00:00 for assets with unknown capture date.
  • The only other strictly required fields for assets is importSource.importTimestamp, and current time can be substituted for that value.

Reasonable file/folder path name

A reasonable file or folder path is a UTF-8 string designed to comply with the typical file naming rules on MacOS and Windows without unexpected side effects.