Schemas
The schema provides more detailed information about the properties of a resource.
The schema is represented by a dictionary containing names of resource properties as keys
and objects describing the corresponding property as values.
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 propertie’s value and another property | SchemaDependency |
The _dependencies
property contains the list of dependencies that exist between the value selected for one of the properites of the described resource and the resoure’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 furhter 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 |
---|---|---|---|
name | Human readable name of the property as it could be displayed in a UI | String | |
type | The data type of the properties values | MetaType | |
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 |
required | If true this property is not nullable | Boolean | true |
writable | If false it is not allowed to change the properties value | Boolean | true |
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.
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 propertie’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 a 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
Link | Description | Type | Nullable | Supported operations |
---|
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 examplifies 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,
"_links": {
"allowedValues": {
"href": "/api/v3/some/path/to/users"
}
}
}
},
"2": {
"loremIpsum": {
"type": "User",
"name": "Lorem ipsum",
"required": true,
"hasDefault": false,
"writable": true,
"_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
}
},
"4": {}
}
}
Given the example above, the client has to add the property loremIpsum
to the schema if the depending property is 1
, 2
or 3
. If it is 4
the property does not exist. The property will not be writable if the value is 3
. The values allowed to be set differ between having 1
or 2
selected for the depending property.
Because of the limitation of JSON objects, all keys will be strings, even when the depending value is actually someting different (e.g. Integer, Date). This is also true for resources in which case the url of the resource is used as the key.
Example Schema
This is an example of how a schema might look like. Note that this endpoint does not exist in the actual implementation.
- Response
200
Toggle details Headers
Content-Type: application/hal+json
Body
{ "_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", "_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:20Z", "updatedAt": "2014-05-21T09:12:00Z" }, { "_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:20Z", "updatedAt": "2014-05-21T09:12:00Z" } ] } } }
Help and feedback
If you did not find what you were looking for
If you need help from the community or want to support others
If you are eligible for professional support and have more questions
REQUEST SUPPORT
If you find an easily fixable error or need for improvement in the documentation for the stable release
If you would like to suggest bigger updates or improvements to this documentation
If you want to contribute to translate this documentation to another language
If there's something you don't like or understand about this feature
If you want to propose a new feature that OpenProject does not offer yet
To further help OpenProject to shape and test new features
To view OpenProject premium features and pricing
If you want to try all premium features in the OpenProject Cloud Edition 14 days for free
If you want to try all premium features in your on premise Community installation 14 days for free