TheDude
/
openproject
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve Schema API documentation

Browse Source 
* Add hasDefault property description
* Order properties as they are returned by the API
* Set default value of `location` and `description`, because of the line
  stating "All of the above properties that do not have a default value
  *must* be present in the schema."
* Clarify the location property
* Clarify the SchemaDependency example
* Add some line breaks to let the text breathe
pull/11881/head
Christophe Bliard 2 years ago committed by Oliver Günther
parent 884fa65c1e
commit 2ae047dc70
1 changed files with 39 additions and 21 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 60
      docs/api/apiv3/tags/schemas.yml

60
docs/api/apiv3/tags/schemas.yml
Unescape View File

@ -1,10 +1,12 @@
---
description: |-
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.
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
@ -41,16 +43,17 @@ description: |-
| 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 | |
| type | The data type of the properties values | MetaType | |
| 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 |
| required | If true this property is not nullable | Boolean | true |
| writable | If false it is not allowed to **change** the properties value | Boolean | true |
| location | If present, contains a reference to the location of the property in the JSON | String | |
| description | If present, contains a formattable, human readable description | Formattable | |
| deprecated | If present, the client should consider the existence of the property depreacated | Boolean | false |
| 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.
@ -59,15 +62,28 @@ description: |-
### Location property
The location property gives a hint as to where to find the property if it is not contained in the set of local attributes.
For example, for linked properties, the location attribute of the schema will contain `_links`. The property will then be found in the resource
under the path `_links.propertyName`.
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 the default attributes to be added on the top level of the resource, the location attribute will not be set.
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 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.
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.
@ -141,11 +157,13 @@ description: |-
}
```
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.
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 in which case the url of the resource is used as the key.
This is also true for resources where the resource url is used as the key.
name: Schemas

Write Preview
Loading…
Cancel
Save