The JSON extended format is used to retrieve master data, technical information and metadata. It is designed in an expanded way that allows to include several features such as validation, sorting and so on. To activate the extended format, the unsuffixed REST category, like data or form-data, must be used in the URL.
The request body is represented by a JSON Object whose content varies according to the operation and the category.
The request body contains at least a content property which hold master data values.
Dataset node
Specifies the target values of terminal nodes under the specified node. This request is used for the dataset node update operation.
{
"content": {
"nodeName1": {
"content": true
},
"nodeName2": {
"content": 2
},
"nodeName3": {
"content": "Hello"
}
}
}
Record
Specifies the target record content by setting the value of each field. For missing fields, the behavior depends on the request parameter byDelta. This structure is used for table record insert, record update or selector's select operation when local enumeration dependency field values are declared.
Some technical data can be added beside the content property such as lastUpdateDate.
{
...
"lastUpdateDate": "2015-12-25T00:00:00.001",
...
"content": {
"gender": {
"content": "Mr."
},
"lastName": {
"content": "Chopin"
},
"lastName-en": {
"content": "Chopin",
"inheritedFieldMode": "inherit"
},
"firstName": {
"content": "Fryderyk"
},
"firstName-en": {
"content": "Frédéric",
"inheritedFieldMode": "overwrite"
},
"birthDate": {
"content": "1810-03-01"
},
"deathDate": {
"content": "1849-10-17"
},
"jobs": {
"content": [
{
"content": "CM"
},
{
"content": "PI"
}
]
},
"infos": {
"content": [
{
"content": "https://en.wikipedia.org/wiki/Chopin"
}
]
}
}
}
Record fields
Specifies the target values of fields under the record terminal node by setting the value of each field. For missing fields, the behavior depends on the request parameter byDelta. This structure is only used for table record updates.
{
"content": [
{
"content": "CM"
},
{
"content": "PI"
}
]
}
Record table
Defines the content of one or more records by indicating the value of each field. For missing fields, the behavior depends on the byDelta parameter of the request. This structure is used upon insert or update records in the table.
{
"rows": [
{
"content": {
"gender": {
"content": "M"
},
"lastName": {
"content": "Saint-Saëns"
},
"firstName": {
"content": "Camille"
},
"birthDate": {
"content": "1835-10-09"
},
...
}
},
{
"content": {
"gender": {
"content": "M"
},
"lastName": {
"content": "Debussy"
},
"firstName": {
"content": "Claude"
},
"birthDate": {
"content": "1862-10-22"
},
...
}
}
]
}
Record table to deleted
Defines one or more records. This structure is used upon deleting several records from the same table.
{
"rows": [
{
"details": "http://.../root/table/1"
},
{
"details": "http://.../root/table/2"
},
{
"primaryKey": "./oid=3"
},
{
"foreignKey": "4"
},
...
]
}
Field
Specifies the target field content. This request is used for field update.
The request has the same structure as defined in node value by only keeping the content entry. Additional entries are simply ignored.
Open or close user interface
Specifies whether the user interface is open or close and the unavailability message.
{
"content": {
"toolStatus": {
"content": true // or false
},
"toolStatusCloseMessage": {
"content": "Access is temporarily forbidden for maintenance."
}
}
}
Only writable fields can be mentioned in the request, this excludes the following cases:
Association node,
Selection node,
Value function,
JavaBean field that does not have a setter,
Unwritable permission on node for authenticated user.
The response body is represented by a JSON Object whose content depends on the operation and the category.
The selection operation contains two different parts.
The first one named meta contains the exhaustive structure of the response.
The second, regrouping content, rows, pagination... etc, contains the values corresponding to the request.
Dataset tree
Contains the hierarchy of table and non-terminal group nodes.
{
"meta": {
"fields": [
{
"name": "rootName",
"label": "Localized label",
"description": "Localized description",
"type": "group",
"pathInDataset": "/rootName",
"fields": [
{
"name": "settings",
"label": "Settings",
"type": "group",
"pathInDataset": "/rootName/settings",
"fields": [
{
"name": "settingA",
"label": "A settings label",
"type": "group",
"pathInDataset": "/rootName/settings/settingA"
},
{
"name": "settingB",
"label": "B settings label",
"type": "group",
"pathInDataset": "/rootName/settings/settingB"
}
]
},
{
"name": "table1",
"label": "Table1 localized label",
"type": "table",
"minOccurs": 0,
"maxOccurs": "unbounded",
"pathInDataset": "/rootName/table1"
},
{
"name": "table2",
"label": "Table2 localized label",
"type": "table",
"minOccurs": 0,
"maxOccurs": "unbounded",
"pathInDataset": "/rootName/table2"
}
]
}
]
},
"validation": [
{
"level": "error",
"message": "Value must be greater than or equal to 0.",
"details": "http://.../rootName/settings/settingA/settingA1?includeValidation=true"
},
{
"level": "error",
"message": "Field 'Settings A2' is mandatory.",
"details": "http://.../rootName/settings/settingA/settingA2?includeValidation=true"
}
],
"content": {
"rootName": {
"details": "http://.../rootName",
"openApiDetails": "http://.../api/.../rootName",
"content": {
"settings": {
"details": "http://.../rootName/settings",
"openApiDetails": "http://.../api/.../rootName/settings",
"content": {
"weekTimeSheet": {
"details": "http://.../rootName/settings/settingA",
"openApiDetails": "http://.../api/.../rootName/settings/settingA"
},
"vacationRequest": {
"details": "http://.../rootName/settings/settingB",
"openApiDetails": "http://.../api/.../rootName/settings/settingB"
}
}
},
"table1": {
"details": "http://.../rootName/table1",
"openApiDetails": "http://.../api/.../rootName/table1"
},
"table2": {
"details": "http://.../rootName/table2",
"openApiDetails": "http://.../api/.../rootName/table2"
}
}
}
}
}
The meta and validation properties are optional.
Dataset node
Contains the list of terminal nodes under the specified node.
{
"meta": {
"fields": [
{
"name": "nodeName1",
"label": "Localized label of the field node 1",
"description": "Localized description",
"type": "boolean",
"minOccurs": 1,
"maxOccurs": 1,
"pathInDataset": "/rootName/.../nodeName1"
},
{
"name": "nodeName2",
"label": "Localized label of the field node 2",
"type": "int",
"minOccurs": 1,
"maxOccurs": 1,
"pathInDataset": "/rootName/.../nodeName2"
}
]
},
"content": {
"nodeName1": {
"content": true
},
"nodeName2": {
"content": -5,
"validation": [
{
"level": "error",
"message": "Value must be greater than or equal to 0."
}
]
}
}
}
Table
JSON Object containing the following properties:
(Optional) The table meta data,
(Optional) The sort criteria applied,
(Optional) The table validation report,
The rows property corresponding to a JSON Array of the selected records. Each record is represented by an JSON Object. If no record is selected then the JSON Array is empty.
(Optional) the pagination property, containing pagination data.
{
"rows": [
{
"label": "Claude Levi-Strauss",
"details": "http://.../root/individu/1",
"content": {
"id": {
"content": 1
},
...
}
},
{
"label": "Sigmoud Freud",
"details": "http://.../root/individu/5",
"content": {
"id": {
"content": 2
},
...
}
},
...
{
"label": "Alfred Dreyfus",
"details": "http://.../root/individu/10",
"content": {
"id": {
"content": 30
},
...
}
}
],
"sortCriteria": [
{
"path": "/name",
"order": "lasc"
},
...
],
"pagination": {
"firstPage": null,
"previousPage": null,
"nextPage": "http://.../root/individu?pageRecordFilter=./id=9&pageSize=9&pageAction=next",
"lastPage": "http://.../root/individu?pageSize=9&pageAction=last"
}
}
Record
JSON Object containing:
The label,
(Optional) The record URL,
(Optional) The technical data ,
(Optional) The table metadata ,
(Optional) The record validation report,
(Optional) The inheritance mode of the record, which can be: root, inherit, overwrite or occult.
The record content.
{
"label": "Name1",
"details": "http://.../rootName/table1/pk1",
"creationDate": "2015-02-02T19:00:53.142",
"creationUser": "admin",
"lastUpdateDate": "2015-09-01T17:22:24.684",
"lastUpdateUser": "admin",
"inheritanceMode": "root",
"meta": {
"name": "table1",
"label": "Table1 localized label",
"type": "table",
"minOccurs": 0,
"maxOccurs": "unbounded",
"primaryKeys": [
"/pk"
],
"inheritance": "true",
"fields": [
{
"name": "pk",
"label": "Identifier",
"type": "string",
"minOccurs": 1,
"maxOccurs": 1,
"pathInRecord": "pk",
"filterable": true,
"sortable": true
},
{
"name": "name",
"label": "Name",
"type": "string",
"minOccurs": 1,
"maxOccurs": 1,
"pathInRecord": "name",
"filterable": true,
"sortable": true
},
{
"name": "name-fr",
"label": "Nom",
"type": "string",
"minOccurs": 1,
"maxOccurs": 1,
"inheritedField": {
"sourceNode": "./name"
},
"pathInRecord": "name-fr",
"filterable": true,
"sortable": true
},
{
"name": "parent",
"label": "Parent",
"description": "Localized description.",
"type": "foreignKey",
"minOccurs": 1,
"maxOccurs": 1,
"foreignKey": {
"tablePath": "/rootName/table1",
"details": "http://.../rootName/table1"
},
"enumeration": "foreignKey",
"pathInRecord": "parent",
"filterable": true,
"sortable": true
}
]
},
"content": {
"pk": {
"content": "pk1"
},
"name": {
"content": "Name1"
},
"name-fr": {
"content": "Name1",
"inheritedFieldMode": "inherit"
},
"parent": {
"content": null,
"selector":"http://.../rootName/table1?selector=true",
"validation": [
{
"level": "error",
"message": "Field 'Parent' is mandatory."
}
]
}
},
"validation": {
...
}
}
Fields
For association or selection nodes, contains the target table with the associated records if, and only if, the includeDetails parameter is set to true.
For other kinds of nodes, contains the current node value.
Retrieve the user interface state
Contains the user interface status and the unavailability message.
{
"content": {
"toolStatus": {
"content": true,
"label": "Open",
"selector": "http://.../domain/toolStatus/toolStatus?selector=true"
},
"toolStatusCloseMessage": {
"content": "Access is temporarily forbidden for maintenance."
}
}
}
Nodes, records and fields, property and values may be hidden depending on their resolved permissions (see permissions) .
This section can be activated on demand with the includeMeta parameter. It describes the structure and the JSON typing of the content section.
This section is deactivated by default for selection operations.
Table metadata is represented by a JSON Object with the following properties:
JSON property | JSON format | Description | Required |
|---|---|---|---|
|
| Specifies the name of the authorized table defined in the model. | Yes |
|
| Specifies the table's label. If undefined, the name of the schema node is returned. | Yes |
|
| Specifies the table's description. | No |
|
| Specifies the node's type, the value is always equal to: | Yes |
|
| Specifies the number of minimum authorized record(s). | Yes |
|
| Specifies the number of maximum authorized record(s) or | Yes |
|
| Specifies if the table content is historized. Its value is See also | No |
|
| Specifies the primary key composition which is represented as an array of the paths. | Yes |
|
| Specifies whether the dataset inheritance is activated for the table. Its value is See also | No |
|
| Specifies the direct children of the record node which are represented as an array of fields. Each field may also recursively contain sub-fields. | Yes |
Each authorized field is represented by a JSON Object with the following properties:
JSON property | JSON format | Description | Required |
|---|---|---|---|
|
| Specifies the name of the authorized field defined in the model. | Yes |
|
| Specifies the node's label. If undefined, the name of the schema node is returned. | Yes |
|
| Specifies the field's description. | No |
|
| Specifies the field's type, which can be a: simple type, | Yes |
|
| Specifies the number of minimum authorized occurrence(s). | Yes |
|
| Specifies the number of maximum authorized occurrence(s) or | Yes |
|
| Specifies whether the field access permission is defined as read-only from the data model access properties. That is, if its data can be read or written. Its value is See also | Yes |
|
| Specifies whether the field is auto-incremented. This property is only available for integer field type. Its value is See also | No |
|
| Specifies whether the check of the constraints on The constraint check is activated when the field has the property | Yes |
|
| Holds information related to the inherited field's value source.
{
"inheritedField": {
"sourceRecord": "/path/to/record", // (optional)
"sourceNode": "./path/to/Node"
}
}
See also | No |
|
| Holds information related to the target table. See also | No (*) |
|
| Holds information related to the association table. See also | No (*) |
|
| Specifies if the field is an enumeration value. Possible values are:
See also According to its value, indicates if the field can be used for retrieving possible values by using the | No |
|
| Specifies the metadata enumeration dependencies list. Only available for enumeration types among: | No |
|
| Specifies if the field is a computed value. See also | No |
|
| Holds information related to the linked field. | No |
|
| Specifies the relative field's path starting from the schema node. | No (**) |
|
| Specifies the relative field's path starting from the table node. | No (*) |
|
| Specifies whether the field can be used to filter records using the | No (*) |
|
| Specifies the hidden filter policy. The possible values are: | No (*) |
|
| Specifies whether the field can be used in sort criteria using the | No (*) |
|
| Specifies the field's non-programmatic constraints. See also | No |
|
| Holds the structure and typing of each field group. | No |
(*) Only available for table, record and record field operations.
(**) Only available for dataset tree operations.
The foreign key field metadata is represented by a JSON Object.
{
"dataspace": "BAuthors",
"dataset": "Authors",
"tablePath": "/root/Authors",
"details": "http://.../BAuthors/Authors/root/Authors"
}
It holds the following properties:
JSON property | JSON format | Description | Required |
|---|---|---|---|
|
| Specifies the target dataspace or snapshot identifier. If not specifies then it corresponds to the same dataspace as the table's one. | No |
|
| Specifies the target dataset's identifier. If not specifies then it corresponds to the same dataset as the table's one. | No |
|
| Specifies the target table's path. | Yes |
|
| Specifies the target table's REST resource URL. See also | No |
|
| Specifies the history target table's REST resource URL. See also | No |
The association field metadata is represented by a JSON Object. This object holds properties which depend on the association type:
tableRefInverse
{
"type": "tableRefInverse",
"dataspace": "BTitles",
"dataset": "Titles",
"tablePath": "/root/Titles",
"details": "http://.../BTitles/Titles/root/Titles",
"fieldToSource": "/root/Titles/au_id",
"filter": "./unit_price > 10"
}
linkTable
{
"type": "linkTable",
"tablePath": "/root/Inventory",
"details": "http://.../BInventory/Inventory/root/Inventory",
"linkTablePath": "/root/Inventory",
"fieldToSource": "/root/Inventory/store",
"fieldToTarget": "/root/Inventory/item",
"filter": "./price > 10"
}
xpathLink
{
"type": "xpathLink",
"tablePath": "/root/Inventory",
"details": "http://.../BAuthors/Authors/root/Inventory",
"predicate": "/root/Inventory[./price < 100]",
"filter": "./price > 10"
}
It holds the following properties:
JSON property | JSON format | Description | Required |
|---|---|---|---|
|
| Specifies the association type. The possible values are: See also | Yes |
|
| Specifies the target dataspace or snapshot identifier. If not specifies, then it corresponds to the same dataspace as the table's one. | No |
|
| Specifies the target dataset's identifier. If not specifies, then it corresponds to the same dataset as the table's one. | No |
|
| Specifies the path of the target table. | Yes |
|
| Specifies the target table's REST resource URL. See also | No |
|
| Specifies the field which refers to the source table of the association. Defined if the association type is | No |
|
| Specifies the path of the field to the target table. Defined if the association type is | No |
|
| Specifies the path of the link table. Defined if the association type is | No |
|
| Specifies the criteria of the association, relative to the current node. Defined if the association type is | No |
|
| Specifies the XPath predicate expression to filter the associated objects. | No |
The linked field metadata is represented by a JSON Object.
{
"relationshipField": "/au_id",
"tablePath": "/root/Authors",
"linkedFieldPath": "/birth_date",
"details": "http://.../BAuthors/Authors/root/Authors"
}
It holds the following properties:
JSON property | JSON format | Description | Required |
|---|---|---|---|
|
| Specifies the field's path holding the relationship used by this linked field. | Yes |
|
| Specifies the table's path referred by this linked field. | Yes |
|
| Specifies the path referred by this linked field. See also | Yes |
|
| Specifies the target table's REST resource URL. See also | No |
The metadata enumeration dependency object is represented by a JSON Object.
{
"localModify": false,
"dataspace": "BAuthors",
"dataset": "Authors",
"targetPath": "/root/Authors",
"details": "http://.../BAuthors/Authors/root/Authors"
}
It holds the following properties:
JSON property | JSON format | Description | Required |
|---|---|---|---|
|
| Specifies whether the enumeration dependency field is impacted by modifications performed on a field in the same record. | Yes |
|
| Specifies the target dataspace or snapshot identifier of the enumeration dependency. If not specified then it corresponds to the same dataspace as the record's one. | No |
|
| Specifies the target dataset's identifier of the enumeration dependency. If not specifies then it corresponds to the same dataset as the record's one. | No |
|
| Specifies the target path of the enumeration dependency. | Yes |
|
| Specifies the target REST resource table URL of the enumeration dependency. See also | No |
The sort criteria, applied to the request, can be returned on demand, by using the includeSortCriteria parameter (deactivated by default). If it is activated, a sortCriteria property is directly added to the response root node.
A sortCriteria property is represented as a JSON Array that contains ordered sort criterion. Each sort criterion corresponds to a JSON Object with the following properties:
JSON property | JSON format | Description | Required |
|---|---|---|---|
|
| Field's path. | Yes |
|
| Possible values are: | Yes |
The sortByRelevancy property is represented by a JSON Array, itself holding a JSON Object with the following properties:
JSON property | JSON format | Description | Required |
|---|---|---|---|
|
| Defines whether the sort is done in ascending or descending order. Possible values are: See sortByRelevancy for more information. | Yes |
The validation can be activated on demand with the includeValidation parameter (deactivated by default). If it is activated, validation properties are directly added on target nodes with one or several messages. For messages without target node's path, a validation property is added on the root node.
A validation property is represented by a JSON Array, holding a JSON Object per message, corresponding to a validation item, with the following properties:
JSON property | JSON format | Description | Required |
|---|---|---|---|
|
| Severity level of the validation item. The possible values are: | Yes |
|
| Description of the validation item. | Yes |
|
corresponding to an absolute URL. | URL of the resource associated with the validation item. Only available on table and dataset scopes, if the associated resource exist and if it is included. See also | No |
This section is automatically activated when the node has a read-write permission. It provides the non-programmatic constraints declared on the data model.
The constraints property is represented by a JSON Array. Every constraint is taking the form of a JSON Object. They have the following properties:
JSON property | JSON format | Description | Required |
|---|---|---|---|
|
| Specifies the type of the constraint See also | Yes |
|
| Specifies the severity level of the constraint. The possible values are: | Yes |
|
| Specifies the value of the non-programmatic constraint. This value can be a simple type, like a | No |
|
| Specifies the minimum value for | No |
|
| Specifies the maximum value for | No |
|
| Specifies the validation message returned when the value of the field does not comply with the constraint. | Yes |
|
| Specifies the control policy management for blocking or non-blocking constraint. See Blocking and non-blocking constraints for more information. | No |
This section lists the non-programmatic constraints types.
Type | Description |
|---|---|
| Defines the field is mandatory |
| Defines the exact number of characters required for this field. |
| Points out a field which provides the exact number of characters required for this one. |
| Defines the minimum number of characters allowed for this field. |
| Points out a field which provides the minimum number of characters allowed for this one. |
| Defines the maximum number of characters allowed for this field. |
| Points out a field which provides the maximum number of characters allowed for this field. |
| Defines an inclusive range of not allowed values for this field. |
| Defines a list of not allowed values for this field. |
| Defines the maximum number of decimal allowed for this field. |
| Defines the regular expression pattern that must be match by the field's value. |
| Defines the maximum number of digits allowed for this integer or decimal field. |
| Defines the minimum value allowed (including the minimum value) for this field. |
| Defines the minimum value allowed (excluding the minimum value) for this field. |
| Defines a field that provide the minimum value allowed (including the minimum value) for this field. |
| Defines a field that provide the minimum value allowed (excluding the minimum value) for this field. |
| Defines the maximum value allowed (including maximum value) for this field. |
| Defines the maximum value allowed (excluding the maximum value) for this field. |
| Defines a field that provide the maximum value allowed (including the maximum value) for this field. |
| Defines a field that provide the maximum value allowed (excluding the maximum value) for this field. |
This section can be deactivated on demand with the includeContent parameter (activated by default). It provides the content of the record values, dataset, or field of one of the content fields for an authorized user. It also has additional information, including labels, technical information, URLs...
The content is represented by a JSON Object with a property set for each sub-node.
JSON property | JSON format | Description | Required |
|---|---|---|---|
| Contains the node value. Available for all nodes except for |
| |
|
corresponding to an absolute REST resource URL. | Returns the node details when invoked. The response type depends on the meta type.
Example:
|
|
|
corresponding to an absolute REST resource URL. | Returns the node history details when invoked. See also |
|
|
| Contains the foreign key or enumeration label in the current locale. The default label is returned if the current locale is not supported. |
|
|
| Contains the node's inheritance state, considering only dataset inheritance. |
|
|
| Contains the node's field inheritance state, considering dataset and field inheritance. When both inheritances are used, field inheritance has priority over the dataset one. |
|
|
corresponding to an absolute URL. | Contains the appropriate URL for selector operation. Example:
|
|
|
| Contains the validation report that concerns the current node context. See also |
|
A simple field value is stored in a JSON Object and its content is the value of the content property.
XML Schema | JSON format | Examples | Meta type |
|---|---|---|---|
Group
|
Contains a property per sub-node. | Example for a simple-occurrence group.
{
"road": {
"content": "11 rue scribe"
},
"zipcode": {
"content": "75009"
},
"country": {
"content": "France"
}
}
|
|
List
|
Contains an array of all field occurrences represented by a JSON Each object is represented as a node value. | Example for a multi-occurrence field of
[
{
"content": 0
},
{
"content": 1
},
{
"content": 2
},
{
"content": 3
}
]
Example for a multi-occurrence group.
[
{
"content": {
"road": {
"content": "11 rue scribe"
},
"zipcode": {
"content": "75009"
},
"country": {
"content": "France"
}
}
},
{
"content": {
"road": {
"content": "711 Atlantic Ave"
},
"zipcode": {
"content": "MA 02111"
},
"country": {
"content": "United States"
}
}
}
]
| or
|
By invoking the URL represented by the selector property on a field that provides an enumeration, it returns a JSON Object containing the following properties:
rows corresponding to an Array of JSON Object where each one contains two entries: the returned content that can be persisted and the corresponding label. The list of established possible items depends on the current context.
(Optional) pagination containing pagination data (activated by default).
{
"rows": [
{
"content": "F",
"label": "feminine"
},
{
"content": "M",
"label": "masculine"
}
],
"pagination": {
"nextPage": null
}
}
Each returned record is completed with the properties corresponding to its technical data, containing:
JSON property | JSON format | Description | Required |
|---|---|---|---|
|
| Creation date | Yes |
|
| Creation user's identifier. | Yes |
|
| Last update date. | Yes |
|
| Last update user's identifier. | Yes |
{
...
"creationDate": "2015-12-24T19:00:53.158",
"creationUser": "admin",
"lastUpdateDate": "2015-12-25T00:00:00.001",
"lastUpdateUser": "admin",
...
}