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"
      }
    ]
  }

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:

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

(**) Only available for dataset operations.

Content

Pagination

This feature allows to return a limited and parameterizable number of data. Pagination can be applied to data of the following types: records, association values, selection node values, selectors and dataspaces. A context named pagination is always returned. This context allows browsing data similarly to the UI.

The pagination is always enabled.

Detailed information related to this context can be found hereafter:

Content of simple type

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:

• 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.

{
  "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"
    }
  ]
}

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
}

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.

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 metadata are limited to the default search strategy.