Cloud Software Group, Inc. EBX®
Documentation > Developer Guide > REST data services > JSON Formats
Navigation mode Documentation > Developer Guide > REST data services > JSON Formats

# Common

## Introduction

The common specifications are used in both compact and Extended formats.

## Global structure

### JSON Response body

#### Form data category

The response body contains a JSON `Object` per handled resources. That is, the JSON root `Object` for a single handled resource is a JSON `Object` as well as for multiple handled resources. The several properties are directly placed into the JSON `Object`.

- If the insert/update of a single record request or update field in table/dataset request was successful, the `code` JSON property may be absent and if not, it corresponds to the HTTP response code associated to the handled resource. The validation report is always present. Some properties are optional and added when requested using request parameters. See Form data operations for more information.

      {
        "validation": [
          {
            "level": "error",
            "message": "Field 'Value' is mandatory.",
            "blocksCommit": "never",
            "pathInRecord": "/value"
          },
          {
            "level": "error",
            "message": "Values between 'AD100' and 'AD200' (included) are prohibited.",
            "blocksCommit": "onUserSubmit-checkModifiedValues",
            "pathInRecord": "/code"
          },
          {
            "level": "warning",
            "message": "Value 'AD150' is prohibited.",
            "blocksCommit": "never",
            "pathInRecord": "/code"
          }
        ]
      }

- If the insert multiple record request was successful, the `code` JSON property may be absent and if not, it corresponds to the HTTP response code associated to the handled resource. The validation report is always present. Some properties are optional and added when requested using request parameters.

      {
        "rows": [
          {
            "label": "My Lable1",
            "details": "http://.../root/table/1",
            "foreignKey": "1",
            "validation": [
              {
                "level": "error",
                "message": "Field 'Value' is mandatory.",
                "blocksCommit": "never",
                "pathInRecord": "/value"
              },
              {
                "level": "error",
                "message": "Values between 'AD100' and 'AD200' (included) are prohibited.",
                "blocksCommit": "onUserSubmit-checkModifiedValues",
                "pathInRecord": "/code"
              },
              {
                "level": "warning",
                "message": "Value 'AD150' is prohibited.",
                "blocksCommit": "never",
                "pathInRecord": "/code"
              }
            ]
          },
          {
            "label": "My Lable2",
            "details": "http://.../root/table/2",
            "foreignKey": "2",
            "validation": [
              {
                "level": "error",
                "message": "Field 'Value' is mandatory.",
                "blocksCommit": "never",
                "pathInRecord": "/value"
              },
              {
                "level": "error",
                "message": "Values between 'AD100' and 'AD200' (included) are prohibited.",
                "blocksCommit": "onUserSubmit-checkModifiedValues",
                "pathInRecord": "/code"
              },
              {
                "level": "warning",
                "message": "Value 'AD150' is prohibited.",
                "blocksCommit": "never",
                "pathInRecord": "/code"
              }
            ]
          }
        ]
      }

- If the insert/update of a single record request or update field in table/dataset failed, the response body corresponds to a JSON `Exception handling` response.

      {
        "code": 422,
        "errors": [
          {
            "level": "error",
            "userCode": "Validation",
            "message": "Field 'Category' is mandatory.",
            "blocksCommit": "never",
            "pathInRecord": "/category"
          },
          {
            "level": "error",
            "userCode": "Validation",
            "message": "Values between 'AD100' and 'AD200' (included) are prohibited.",
            "blocksCommit": "onUserSubmit-checkModifiedValues",
            "pathInRecord": "/code"
          }
        ]
      }

- If the insert multiple record request failed, the response body corresponds to a JSON `Exception handling` response.

      {
        "code": 422,
        "errors": [
          {
            "level": "error",
            "rowIndex": 0,
            "userCode": "Validation",
            "message": "Values between 'AD100' and 'AD200' (included) are prohibited.",
            "blocksCommit": "onUserSubmit-checkModifiedValues",
            "pathInRecord": "/code"
          },
          {
            "level": "error",
            "rowIndex": 0,
            "userCode": "Validation",
            "message": "Field 'Value Less Than' is mandatory.",
            "blocksCommit": "never",
            "pathInRecord": "/less_than_value"
          },
          {
            "level": "error",
            "rowIndex": 1,
            "userCode": "Validation",
            "message": "Values between 'AD100' and 'AD200' (included) are prohibited.",
            "blocksCommit": "onUserSubmit-checkModifiedValues",
            "pathInRecord": "/code"
          },
          {
            "level": "error",
            "rowIndex": 1,
            "userCode": "Validation",
            "message": "Field 'Value Less Than' is mandatory.",
            "blocksCommit": "never",
            "pathInRecord": "/less_than_value"
          }
        ]
      }

##### See also

- Form validation report
- Exception handling

## Form validation report

This report can be retrieve by using the Form data operations. It provides every validation constraint on the requested resource.

Those constraints have the following properties:

JSON property | JSON format | Description | Required
--- | --- | --- | ---
`message` | `String` | Description of the constraint. | Yes
`blocksCommit` | `String` | Control policy of the constraint. The possible values are: `onInsertUpdateOrDelete`, `onUserSubmit-checkModifiedValues`, `never`. See Blocking and non-blocking constraints for more information. | Yes
`level` | `String` | Severity level of the constraint. The possible values are: `info`, `warning`, `error` or `fatal`. | Yes
`pathInDataset` | `String` | Relative field path starting from the schema node. | No(**)
`pathInRecord` | `String` | Relative field path starting from the table node. | No (*)

(*) Only available for record and record field operations.

(**) Only available for dataset operations.

##### See also

- Form data category

## Content

### Pagination

Use pagination to return a limited and parameterizable number of data. Pagination can be applied to the following data types: records, association values, selection node values, selectors, dataspaces and datasets. A context named `pagination` is always returned. This context allows you to browse data in a similar manner to the UI.

The pagination is always enabled.

##### See also

- Select operation
- Select datasets
- Beta feature: Select dataspaces or snapshots

The following provides detailed information related to this context:

JSON property | JSON format | Description | Required
--- | --- | --- | ---
`firstPage` | `String` or `null` (*) | URL to access the first page. | Yes
`previousPage` | `String` or `null` (*) | URL to access the previous page. | Yes
`nextPage` | `String` or `null` (*) | URL to access the next page. | Yes
`lastPage` | `String` or `null` (*) | URL to access the last page. | Yes

##### Note

(*) Only defines whether data is available in this context and not in the response.

### Content of simple type

XML Schema | JSON format | Examples | Meta type | OpenAPI
--- | --- | --- | --- | ---
`xs:string` `xs:Name` `osd:text` | `String` (Unicode characters, cf. RFC4627) | "A text" "The escape of \"special character\" is preceded by a backslash." null | `string` `name` `text` | type: `string` format: `n/a`
`osd:html` | `String` (Unicode characters, cf. RFC4627) | "<p>An HTML tag can thus be written without trouble</p>" | `html` | type: `string` format: `html`
`osd:email` | `String` (Unicode characters, cf. RFC4627) | "employee@mycompany.com" | `email` | type: `string` format: `email`
`osd:locale` | `String` (Language tag, cf. RFC1766) | "en-US" | `locale` | type: `string` format: `locale`
`xs:string` (Foreign key) | `String` contains the value of the formatted foreign key. | `"0"` `"true|99"` | `foreignKey` | type: `string` format: `n/a`
`xs:boolean` | `Boolean` | true false null | `boolean` | type: `boolean` format: `n/a`
`xs:decimal` | `Number` or `null` | -10.5 20.001 15 -1e-13 | `decimal` | type: `number` format: `double`
`xs:date` | `String` with format: "yyyy-MM-dd" | "2015-04-13" | `date` | type: `string` format: `date`
`xs:time` | `String` with format: "HH:mm:ss" "HH:mm:ss.SSS" | "11:55:00" "11:55:00.000" | `time` | type: `string` format: `date-time`
`xs:dateTime` | `String` with format: "yyyy-MM-ddTHH:mm:ss" "yyyy-MM-ddTHH:mm:ss.SSS" | "2015-04-13T11:55:00" "2015-04-13T11:55:00.000" | `dateTime` | type: `string` format: `date-time`
`xs:anyURI` | `String` (Uniform Resource Identifier, cf. RFC3986) | "https://fr.wikipedia.org/wiki/René_Descartes" | `anyURI` | type: `string` format: `uri`
`xs:int` `xs:integer` | `Number` or `null` | 1596 | `int` | type: `integer` format: `int32`
`osd:resource` | `String` contains the resource formatted value. | "ebx-tutorial:ext-images:frontpages/Bach.jpg" | `resource` | type: `string` format: `n/a`
`osd:color` | `String` with format: "#[A-Fa-f0-9]{6}" contains the formatted value for the color. | "#F6E0E0" | `color` | type: `string` format: `n/a`
`osd:datasetName` | `String` with format: "[a-zA-Z_][-a-zA-Z0-9_.]*" and 64 characters max. contains the formatted value of the dataset name. | "ebx-tutorial" | `dataset` | type: `string` format: `n/a`
`osd:dataspaceKey` | `String` with format: `[BV][a-zA-Z0-9_:.\-\|]+` and 33 characters max. contains the formatted key value of the dataspace. | "Bebx-tutorial" | `dataspace` | type: `string` format: `n/a`

### Insert operation report

When invoking the insert operation with a record table, it can optionally return a report. The report includes a JSON `Object` that contains the following properties:

- `count` contains an `int` of JSON `Number` type, that defines the number of processed records since the listed rows can not be exhaustive in several cases.

- `isPartialList` contains a `boolean` of JSON `Boolean` type, that is true if the listed rows are only a partial list of the whole processed records, false otherwise.

- `rows` contains a JSON `Array`, where each element corresponds to the result of a request element.

- `code` contains an `int` of JSON `Number` type, and allows to know whether the record has been inserted or updated. This property is included if, and only if, the `updateOrInsert` parameter is set to `true`.

- `foreignKey` contains a `string` of JSON `String` type, corresponding to the content to be used as a foreign key for this record. This property is included if, and only if, the parameter `includeForeignKey` is set to `true`.

- `label` contains a `string` of JSON `String` type, and allows to retrieve the record label. This property is included if, and only if, the parameter `includeLabel` is set to `yes`.

- `details` containing a `string` of JSON `String` type, corresponding to the resource URL. This property is included if, and only if, the parameter `includeDetails` is set to `true`.

    {
      "count": 2,
      "isPartialList": false,
      "rows": [
        {
          "code": 204,
          "foreignKey": "62",
          "label": "Claude Debussy",
          "details": "http://.../root/individu/62"
        },
        {
          "code": 201,
          "foreignKey": "195",
          "label": "Camille Saint-Saëns",
          "details": "http://.../root/individu/195"
        }
      ]
    }

##### See also

- Insert operation

### Delete operation report

When invoking the delete operation, a report is returned. The report includes a JSON `Object` that contains the following properties:

- `deletedCount` containing an integer of JSON `Number` type, corresponds to the number of deleted records.

- `occultedCount` containing an integer of JSON `Number` type, corresponds to the number of occulted records.

- `inheritedCount` containing an integer of JSON `Number` type, corresponds to the number of inherited records.

    {
      "deletedCount": 1,
      "inheritedCount": 0,
      "occultedCount": 0
    }

##### See also

- Delete operation

### Technical data

Each returned record can contain its system records metadata under `ebx-metadata/system` properties corresponding to the technical data. System metadata are requestable and sortable.

To include records metadata, see `includeMetadata=system` parameter value for select operation.

JSON property | JSON format | Description | Required
--- | --- | --- | ---
`uuid` | `String` | Universally Unique Identifier of the record | Yes
`creator` | `String` | Creation user's identifier. See `UserReference` for more information. | Yes
`creation_time` | `String` | Creation date | Yes
`updater` | `String` | Last update user's identifier. See `UserReference` for more information. | Yes
`update_time` | `String` | Last update date. | Yes

For extended format:

    {
      ...,
      "ebx-metadata":{
        "content":{
          "system":{
            "content":{
              "uuid":{
                "content":"7FE03810-6A67-11ED-A892-00FF20216100"
              },
              "creator":{
                "content":"Uadmin"
              },
              "creation_time":{
                "content":"2022-11-22T14:13:47.793"
              },
              "updater":{
                "content":"Uadmin"
              },
              "update_time":{
                "content":"2022-11-29T17:46:55.686"
              }
            }
          }
        }
      }
    }

For compact format:

    {
      ...,
      "ebx-metadata":{
        "system":{
          "uuid":"7FE03810-6A67-11ED-A892-00FF20216100",
          "creator":"Uadmin",
          "creation_time":"2022-11-22T14:13:47.793",
          "updater":"Uadmin",
          "update_time":"2022-11-29T17:46:55.686"
        }
      }
    }

##### See also

- Optimistic locking

## Update modes

The `byDelta` mode allows to ignore data model elements that are missing from the JSON source document. This mode is enabled (by default) through RESTful operations. The following table summarizes the behavior of insert and update operations when elements are not included in the source document.

See the RESTful data services operations update and insert, as well as `ImportSpec.setByDelta` in the Java API for more information.

State in the JSON source document | Behavior
--- | ---
The property does not exist in the source document | If the `byDelta` mode is activated (default): For the `update` operation, the field value remains unchanged. For the `insert` operation, the behavior is the same as when the `byDelta` mode is disabled. If the `byDelta` mode is disabled through the RESTful operation parameter: The target field is set to one of the following values: If the element defines a default value, the target field is set to that default value. If the element is of a type other than a string or list, the target field value is set to `null`. If the element is an aggregated list, the target field value is set to an empty list value. If the element is a string that differentiates `null` from an empty string, the target field value is set to `null`. If it is a string that does not differentiate the two, an empty string. If the element (simple or complex) is hidden in the data services, the target value remains unchanged. ##### See also Hiding a field in Data Services ##### Note The user performing the import must have the required permissions to create or change the target field value. Otherwise, the operation will be aborted.
The element is present and its value is `null` (for example, `"content": null`) | The target field is always set to `null` except for lists, in which case it is not supported.

## Known limitations

### Field values

The value of fields `xs:date`, `xs:time` and `xs:dateTime` does not contain a time zone associated with the JSON-primitive type.

### Indexing and search strategy

Filterable and sortable values from the metamodel are limited to the default search strategy.

##### See also

- Search

Documentation > Developer Guide > REST data services > JSON Formats