OpenProject Schemas API

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](https://www.openproject.org/docs/api/endpoints/schemas/#schema-dependencies) 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](https://www.openproject.org/docs/api/endpoints/queries/)) 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 | | formula | If present, contains a formula that is used to calculate the value of the property | 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 | | placeholder | If present, contains the text to display as a placeholder, so if no value is set | String | null | 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](https://ruby-doc.org/core-2.2.6/Regexp.html). ### 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: ```json { "_type": "SchemaDependency", "on": "someProperty", "dependencies": { "1": { "loremIpsum": { "type": "User", "name": "Lorem ipsum", "required": true, "hasDefault": false, "writable": true, "location": "_links", "placeholder": "Lorem ipsum placeholder", "description": { "format": "markdown", "raw": "A description for field Lorem ipsum. This may contain [links](https://example.com).", "html": "A description for field Lorem ipsum. This may contain links." }; "_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.