Skip to main content

Schemas

As ftrack supports customizing entity types and attributes, the API makes use of schemas to describe which entity types and attributes are available for a particular server. To see the list of available schemas on your ftrack workspace, click on "API reference" under the help menu from your user menu in the top right corner.

A schema definition roughly follows the JSON-schema specification and provides an easy way to build a dynamic client that can adapt to differing setups.

To retrieve a list of schemas for a particular server, connect to that server and issue a Query schemas operation. Each entry in the returned list will be a schema definition whose id corresponds to the unique entity type. Here is an example of an Asset schema definition:

{
  "id": "Asset",
  "type": "object",
  "properties": {
    "id": {
      "alias_for": "assetid",
      "type": "string",
      "default": "{uid}"
    },
    "name": {
      "type": "string"
    },
    "context_id": {
      "type": "string",
      "format": "foreign_key",
      "description": "Foreign key(s): Context.id"
    },
    "type_id": {
      "alias_for": "typeid",
      "type": "string",
      "format": "foreign_key",
      "description": "Foreign key(s): AssetType.id"
    },
    "parent": {
      "$ref": "Context"
    },
    "type": {
      "$ref": "AssetType"
    },
    "versions": {
      "type": "array",
      "items": {
        "$ref": "AssetVersion"
      }
    },
    "metadata": {
      "alias_for": "meta",
      "type": "mapped_array",
      "items": {
        "$ref": "Metadata"
      }
    }
  },
  "immutable": ["id"],
  "primary_key": ["id"],
  "required": ["id"],
  "default_projections": ["id"]
}

Properties​

Each schema has a properties section that describes the known attributes for that entity type.

A property is keyed by its unique name against a configuration that may contain entries for:

type​

The type of the attribute. Can be used for validation and hinting. Standard types include string, boolean, number, array. There are also a few special types such as:

  • mapped_array - Indicates that an array attribute should be presented as a mapping. For example, metadata works this way where a collection of entities should be presented as key, value pairs for convenience.
  • variable - Type varies depending on value and must be computed at runtime.

format​

Describes format of value for some types. Can be used for validation and hinting. For example, a string type may have a format of date-time to indicate that the stored string value can be interpreted as a date time.

description​

Describes the attribute with a human readable string. Useful for hinting in interfaces and providing users with more information.

default​

A default value that should be used for the attribute primarily when creating entities. If the value is surrounded by braces {} then this indicates that the value should be a computed value. For example, {uid} would indicate that a UUID should be computed for the default value. Most clients should ensure default values are set for any required attributes prior to sending operations to the server.

$ref​

A reference to another entity type. When this field is encountered it should be expected that the attribute can hold a reference to an instance of another entity of the specified type. Can also be used in conjunction with items for array type to describe many-to-many relationships.

alias_for​

Describes the internal attribute name that the public attribute maps to. This data is primarily used by the server and should not be relevant for most clients.

Additional metadata​

A schema also provides additional metadata about the entity type that can be useful to a client:

primary_key​

A list of properties that make up the unique identity for an instance of the entity type. The values of these properties are useful when performing certain operations like updating an entity.

immutable​

Properties that, once set, should not be altered.

required​

Properties that are required to be set in order to successfully create an instance of the entity type. Can be useful when building a dynamic UI that displays feedback to the user on required values.

default_projections​

List of properties that should be used as projections when none are supplied in a query for the entity type.

system_projections​

List of properties that are required by internals and will always be loaded for that entity type.