Metadata

Overview

Metadata is arbitrary information that is useful to an object, but that is not necessary for the object to function in the Droplit system. Usually, metadata adds information to an object that enables client applications to function. This allows clients to customize their use of the Droplit system without changing its core functionality. The existence of metadata eliminates the need for an external database into which proprietary information would be stored.

Details

Metadata is usually associated with container objects. Any object which can support metadata contains a “meta” property. The metadata is considered to be defined if the property is not null. Metadata should be formatted as a valid JSON object. Established metadata can be removed by setting the “meta” property to null. While there is no limit to the amount of metadata that may be stored (yet), the total size of the record may not exceed 16MB.

Properties set through metadata are called keys. Key names follow the same naming rules as IDs and aliases:

  • Between 1 and 24 characters
  • Only contains characters:
    • “a-z”
    • “A-Z”
    • “0-9”
    • “_” (underscore)
  • No spaces

System-Defined Keys

Metadata keys prefixed with “$” are reserved for special uses. For example, “$label” assigns a display name to an object, and is used by both the developer portal and command line interface tools. It can also be used in client applications.

API users can specify other strings to use as a metadata prefix, if desired. Defining a new prefix may be useful when the default metadata prefix, “$label”, already has special meaning in a client application, such as one built with AngularJS.

Customizing a Metadata Prefix

The header “x-system-meta-prefix” defines the metadata prefix. This header is not global; that is, using it once will not guarantee that all future metadata is inserted with the desired prefix. Every time new metadata is specified, the prefix must be present in the header in order to be included.

The prefix is prepended to a metadata key exactly how it is specified in the header, so care should be taken to ensure that the prefix is always consistent. For example, if “x-system-meta-profile” is set to "droplit-" for a key called "$label", the created key will be “droplit-label”.