API: Schemas

The schema provides detailed information about the properties of a resource.

The schema is represented by a dictionary where keys are names of resource properties and values are objects describing the corresponding property.

These objects are called field schema and form the core of the schema representation. Each of them can contain its own _links and _embedded section.

Linked Properties

Link Description Type Nullable Supported operations
self This schema Schema READ

Local Properties

Property Description Type
_dependencies A list of dependencies between one property’s value and another property SchemaDependency

The _dependencies property contains the list of dependencies that exist between the value selected for one of the properties of the described resource and the resource’s structure. Depending on the value, additional properties might exist or properties might have other values allowed to be assigned. See SchemaDependency for more information.

Field schema

Linked Properties

Property Description Conditions
allowedValues List of resources that are assignable by the current user. Will not exist if allowedValuesSchemas is present.
allowedValuesSchemas Link to schemas further describing the property. Will not exist if allowedValues is present.

The allowedValues can either contain a list of canonical links or just a single link to a collection resource. This is an optimization to allow efficient handling of both small resource lists (that can be enumerated inline) and large resource lists (requiring one or more separate requests).

The allowedValuesSchemas will on rare occasions (e.g. for a Query) replace allowedValues. This is done when there is no fixed set of allowed values. Instead, the allowed values will have to follow a schema, or one of a list of schemas, in its own right.

Only one of the links (allowedValues, allowedValuesSchemas) will exist for any given property.

Local Properties

Property Description Type Default
type The data type of the property MetaType
name Human readable name of the property as it could be displayed in a UI String
required If true this property is not nullable Boolean true
hasDefault If true this property will have a default value if none is provided Boolean false
writable If false it is not allowed to change the property value Boolean true
minLength The value of the property must at least contain the specified amount of characters Integer 0
maxLength The value of the property must at most contain the specified amount of characters Integer ∞
regularExpression The value of the property must match the given regular expression (if not null) String null
location If present, contains a reference to the location of the property in the JSON String null
description If present, contains a formattable, human readable description Formattable null
deprecated If present, the client should consider the existence of the property deprecated Boolean false

All of the above properties that do not have a default value must be present in the schema. For properties that have a default value, the client can assume the default value, if the property is missing.

Note that regular expressions used in the API follow the rules of Ruby Regular Expressions.

Location property

The location property gives a hint as to where to find the resource property:

  • when not set, it is in the resource top level attributes;
  • when set to _links, it is under the path _links.propertyName;
  • when set to _meta, it is under the path _meta.propertyName.

For example, for a work package schema, the field schema of the user property has a location property set to _links. This means that the user property will be found under the path _links.user of the json payload of the work package resource.

Schema Dependencies

A SchemaDependency describes the dependencies between a value chosen for a resource’s property and the resource’s structure. By that, additional properties or changes in a property are described.

A SchemaDependency will never describe a property to disappear, only to appear. As such it always provides additional information. For a property that is depending on another property’s value, this can result in not being listed in the resource’s schema itself at all. This will be the case if the existence of the property as a whole will be dependent. If only one of the aspects (e.g. writable) of the property changes with the selected value, the property itself will already be listed in the schema, but it will lack the dependent aspect.

Given that SchemaDependencies will only add information, and the content type of JSON, a client should be able to join the two objects, the schema and the dependency, into one object easily.

SchemaDependencies are always embedded inside a Schema’s _dependencies attribute. As such, they are not independently existing resources. Consequently, they do not have a self reference.

Linked Properties

A SchemaDependency does not have any links.

Local Properties

Property Description Type
on The name of the property on which the dependency exists string
dependencies The additions to a schema grouped by the value of the depending property object

The following excerpt exemplifies the objects that can be found as a value of the dependencies property:

{
  "_type": "SchemaDependency",
  "on": "someProperty",
  "dependencies": {
    "1": {
      "loremIpsum": {
        "type": "User",
        "name": "Lorem ipsum",
        "required": true,
        "hasDefault": false,
        "writable": true,
        "location": "_links",
        "description": {
            "format": "markdown",
            "raw": "A description for field Lorem ipsum. This may contain [links](https://example.com).",
            "html": "<p>A description for field Lorem ipsum. This may contain <a href=\"https://example.com\">links</a>.</p>"
        };
        "_links": {
          "allowedValues": {
            "href": "/api/v3/some/path/to/users"
          }
        }
      }
    },
    "2": {
      "loremIpsum": {
        "type": "User",
        "name": "Lorem ipsum",
        "required": true,
        "hasDefault": false,
        "writable": true,
        "location": "_links",
        "_links": {
          "allowedValues": {
            "href": "/api/v3/a/totally/different/path/to/other/users"
          }
        }
      }
    },
    "3": {
      "loremIpsum": {
        "type": "User",
        "name": "Lorem ipsum",
        "required": true,
        "hasDefault": false,
        "writable": false,
        "location": "_links",
      }
    },
    "4": {}
  }
}

Given the example above:

  • If the depending property is 1, 2 or 3:
    • The client must set the property loremIpsum, because of "required": true for all three field schemas
    • When the depending property is 1 or 2, the values allowed to be set for loremIpsum property differ
    • When the depending property is 3, the loremIpsum property will not be writable
  • If the depending property is 4, the loremIpsum property does not exist

Because of the limitation of JSON objects, all keys will be strings, even when the depending value is actually something different (e.g. Integer, Date). This is also true for resources where the resource url is used as the key.

Methods

View the schema

This is an example of how a schema might look like. Note that this endpoint does not exist in the actual implementation.

No parameters

200

OK

{
  "_dependencies": [

  ],
  "_links": {
    "self": {
      "href": "/api/v3/example/schema"
    }
  },
  "_type": "Schema",
  "lockVersion": {
    "name": "Resource Version",
    "type": "Integer",
    "writable": false
  },
  "status": {
    "_embedded": {
      "allowedValues": [
        {
          "_links": {
            "self": {
              "href": "/api/v3/statuses/1"
            }
          },
          "_type": "Status",
          "createdAt": "2014-05-21T08:51:20.396Z",
          "defaultDoneRatio": 0,
          "id": 1,
          "isClosed": false,
          "isDefault": true,
          "name": "New",
          "position": 1,
          "updatedAt": "2014-05-21T09:12:00.441Z"
        },
        {
          "_links": {
            "self": {
              "href": "/api/v3/statuses/2"
            }
          },
          "_type": "Status",
          "createdAt": "2014-05-21T08:51:20.396Z",
          "defaultDoneRatio": 100,
          "id": 2,
          "isClosed": true,
          "isDefault": false,
          "name": "Closed",
          "position": 2,
          "updatedAt": "2014-05-21T09:12:00.441Z"
        }
      ]
    },
    "_links": {
      "allowedValues": [
        {
          "href": "/api/v3/statuses/1",
          "title": "New"
        },
        {
          "href": "/api/v3/statuses/2",
          "title": "Closed"
        }
      ]
    },
    "location": "_links",
    "name": "Status",
    "type": "Status"
  },
  "subject": {
    "maxLength": 255,
    "minLength": 1,
    "name": "Subject",
    "type": "String"
  }
}
Example_SchemaModel
{
  "type": "object",
  "example": {
    "_type": "Schema",
    "_dependencies": [

    ],
    "_links": {
      "self": {
        "href": "/api/v3/example/schema"
      }
    },
    "lockVersion": {
      "name": "Resource Version",
      "type": "Integer",
      "writable": false
    },
    "subject": {
      "name": "Subject",
      "type": "String",
      "minLength": 1,
      "maxLength": 255
    },
    "status": {
      "_links": {
        "allowedValues": [
          {
            "href": "/api/v3/statuses/1",
            "title": "New"
          },
          {
            "href": "/api/v3/statuses/2",
            "title": "Closed"
          }
        ]
      },
      "name": "Status",
      "type": "Status",
      "location": "_links",
      "_embedded": {
        "allowedValues": [
          {
            "_links": {
              "self": {
                "href": "/api/v3/statuses/1"
              }
            },
            "_type": "Status",
            "id": 1,
            "name": "New",
            "position": 1,
            "isDefault": true,
            "isClosed": false,
            "defaultDoneRatio": 0,
            "createdAt": "2014-05-21T08:51:20.991Z",
            "updatedAt": "2014-05-21T09:12:00.155Z"
          },
          {
            "_links": {
              "self": {
                "href": "/api/v3/statuses/2"
              }
            },
            "_type": "Status",
            "id": 2,
            "name": "Closed",
            "position": 2,
            "isDefault": false,
            "isClosed": true,
            "defaultDoneRatio": 100,
            "createdAt": "2014-05-21T08:51:20.991Z",
            "updatedAt": "2014-05-21T09:12:00.155Z"
          }
        ]
      }
    }
  }
}