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

Extended

Introduction

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.

Global structure

JSON Request body

The request body is represented by a JSON Object whose content varies according to the operation and the category.

Data category

The request body contains at least a content property which hold master data values.

Only writable fields can be mentioned in the request, this excludes the following cases:

JSON Response body

The response body is represented by a JSON Object whose content depends on the operation and the category.

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

Note

Nodes, records and fields, property and values may be hidden depending on their resolved permissions (see permissions) .

Metamodel

This section can be activated on demand with the includeMetamodel parameter. It describes the structure and the JSON typing of the content section.

This section is deactivated by default for selection operations.

Structure for table

Table metamodel is represented by a JSON Object with the following properties:

JSON property

JSON format

Description

Required

name

String

Specifies the name of the authorized table defined in the model.

Yes

label

String

Specifies the table's label. If undefined, the name of the schema node is returned.

Yes

description

String

Specifies the table's description.

No

type

String

Specifies the node's type, the value is always equal to: table.

Yes

minOccurs

Number

Specifies the number of minimum authorized record(s).

Yes

maxOccurs

Number or String

Specifies the number of maximum authorized record(s) or unbounded.

Yes

history

Boolean

Specifies if the table content is historized. Its value is true if history is activated, false otherwise.

See also

No

primaryKeyFields

Array

Specifies the primary key composition which is represented as an array of the paths.

Yes

inheritance

Boolean

Specifies whether the dataset inheritance is activated for the table. Its value is true if inheritance is activated, false otherwise.

No

fields

Array

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

Structure for field

Each authorized field is represented by a JSON Object with the following properties:

JSON property

JSON format

Description

Required

name

String

Specifies the name of the authorized field defined in the model.

Yes

label

String

Specifies the node's label. If undefined, the name of the schema node is returned.

Yes

description

String

Specifies the field's description.

No

type

String

Specifies the field's type, which can be a: simple type, group, table, foreignKey, association, etc.

Yes

minOccurs

Number

Specifies the number of minimum authorized occurrence(s).

Yes

maxOccurs

Number or String

Specifies the number of maximum authorized occurrence(s) or unbounded.

Yes

readOnly

Boolean

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 true if the field is read only, false otherwise.

Yes

autoIncrement

Boolean

Specifies whether the field is auto-incremented. This property is only available for integer field type. Its value is true if the field is auto-incremented, false otherwise.

No

checkNullInput

Boolean

Specifies whether the check of the constraints on null fields, at user input, is activated or not. Its value is true when activated, false otherwise.

The constraint check is activated when the field has the property osd:checkNullInput set to true.

Yes

inheritedField

Object

Holds information related to the inherited field's value source.

{
  "inheritedField": {
    "sourceRecord": "/path/to/record", // (optional)
    "sourceNode": "./path/to/Node"
  }
}

No

foreignKey

Object

Holds information related to the target table.

No (*)

association

Object

Holds information related to the association table.

No (*)

enumeration

String

Specifies if the field is an enumeration value. Possible values are:

  • dynamic

  • foreignKey

  • nomenclature

  • programmatic

  • resource

  • static

According to its value, indicates if the field can be used for retrieving possible values by using the selector request parameter.

No

enumerationDependencies

Array of JSON Object

Specifies the metadata enumeration dependencies list. Only available for enumeration types among: foreignKey, dynamic or programmatic.

No

valueFunction

Boolean

Specifies if the field is a computed value.

See also

No

linkedField

Object

Holds information related to the linked field.

No

pathInDataset

String

Specifies the relative field's path starting from the schema node.

No (**)

pathInRecord

String

Specifies the relative field's path starting from the table node.

No (*)

filterable

Boolean

Specifies whether the field can be used to filter records using the filter request parameter.

No (*)

hiddenFilterPolicy

String

Specifies the hidden filter policy.

The possible values are: textSearchOnly, true or false.

No (*)

sortable

Boolean

Specifies whether the field can be used in sort criteria using the sort request parameter.

No (*)

constraints

Array of JSON Object

Specifies the field's non-programmatic constraints.

See also

No

fields

Array of JSON Object

Holds the structure and typing of each field group.

No

isBusinessObjectRelation

Boolean

Specifies whether the field structure is in the current table or given through a business object.

No

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

(**) Only available for dataset tree operations.

Structure for foreign key field

The foreign key field metamodel 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

dataspace

String

Specifies the target dataspace or snapshot identifier. If not specifies then it corresponds to the same dataspace as the table's one.

No

dataset

String

Specifies the target dataset's identifier. If not specifies then it corresponds to the same dataset as the table's one.

No

tablePath

String

Specifies the target table's path.

Yes

details

String

Specifies the target table's REST resource URL.

No

historyDetails

String

Specifies the history target table's REST resource URL.

No

Structure for the association field

The association field metamodel is represented by a JSON Object. This object holds properties which depend on the association type:

It holds the following properties:

JSON property

JSON format

Description

Required

type

String

Specifies the association type. The possible values are: tableRefInverse, linkTable, xpathLink

See also

Yes

dataspace

String

Specifies the target dataspace or snapshot identifier. If not specifies, then it corresponds to the same dataspace as the table's one.

No

dataset

String

Specifies the target dataset's identifier. If not specifies, then it corresponds to the same dataset as the table's one.

No

tablePath

String

Specifies the path of the target table.

Yes

details

String

Specifies the target table's REST resource URL.

No

fieldToSource

String

Specifies the field which refers to the source table of the association.

Defined if the association type is tableRefInverse or linkTable.

No

fieldToTarget

String

Specifies the path of the field to the target table.

Defined if the association type is linkTable.

No

linkTablePath

String

Specifies the path of the link table.

Defined if the association type is linkTable.

No

predicate

String

Specifies the criteria of the association, relative to the current node.

Defined if the association type is xpathLink.

No

filter

String

Specifies the XPath predicate expression to filter the associated objects.

No

Structure for the linked field

The linked field metamodel 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

relationshipField

String

Specifies the field's path holding the relationship used by this linked field.

Yes

tablePath

String

Specifies the table's path referred by this linked field.

Yes

linkedFieldPath

String

Specifies the path referred by this linked field.

Yes

details

URI

Specifies the target table's REST resource URL.

No

Structure for the enumeration dependencies

The metamodel 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

localModify

Boolean

Specifies whether the enumeration dependency field is impacted by modifications performed on a field in the same record.

Yes

dataspace

String

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

dataset

String

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

targetPath

String

Specifies the target path of the enumeration dependency.

Yes

details

String

Specifies the target REST resource table URL of the enumeration dependency.

No

Sort criteria

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

path

String

Field's path.

Yes

order

String

Possible values are: asc, lasc, desc or ldesc.

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

order

String

Defines whether the sort is done in ascending or descending order. Possible values are: lasc or ldesc.

See sortByRelevancy for more information.

Yes

Validation report

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

level

String

Severity level of the validation item. The possible values are: info, warn, error, fatal.

Yes

message

String

Description of the validation item.

Yes

details

String

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.

No

Constraints

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

type

String

Specifies the type of the constraint

See also

Yes

level

String

Specifies the severity level of the constraint. The possible values are: fatal, error, warning or info.

Yes

content

Object

Specifies the value of the non-programmatic constraint. This value can be a simple type, like a String, or a JSON Object.

No

min

Integer

Specifies the minimum value for excludeSegment constraint type.

No

max

Integer

Specifies the maximum value for excludeSegment constraint type.

No

message

String

Specifies the validation message returned when the value of the field does not comply with the constraint.

Yes

blocksCommit

String

Specifies the control policy management for blocking or non-blocking constraint.

See Blocking and non-blocking constraints for more information.

No

Constraint Types

This section lists the non-programmatic constraints types.

Type

Description

mandatory

Defines the field is mandatory

fixedLengthStatic

Defines the exact number of characters required for this field.

fixedLengthDynamic

Points out a field which provides the exact number of characters required for this one.

minLengthStatic

Defines the minimum number of characters allowed for this field.

minLengthDynamic

Points out a field which provides the minimum number of characters allowed for this one.

maxLengthStatic

Defines the maximum number of characters allowed for this field.

maxLengthDynamic

Points out a field which provides the maximum number of characters allowed for this field.

excludeSegment

Defines an inclusive range of not allowed values for this field.

excludeValue

Defines a list of not allowed values for this field.

fractionDigits

Defines the maximum number of decimal allowed for this field.

pattern

Defines the regular expression pattern that must be match by the field's value.

totalDigits

Defines the maximum number of digits allowed for this integer or decimal field.

boundaryMinInclusiveStatic

Defines the minimum value allowed (including the minimum value) for this field.

boundaryMinExclusiveStatic

Defines the minimum value allowed (excluding the minimum value) for this field.

boundaryMinInclusiveDynamic

Defines a field that provide the minimum value allowed (including the minimum value) for this field.

boundaryMinExclusiveDynamic

Defines a field that provide the minimum value allowed (excluding the minimum value) for this field.

boundaryMaxInclusiveStatic

Defines the maximum value allowed (including maximum value) for this field.

boundaryMaxExclusiveStatic

Defines the maximum value allowed (excluding the maximum value) for this field.

boundaryMaxInclusiveDynamic

Defines a field that provide the maximum value allowed (including the maximum value) for this field.

boundaryMaxExclusiveDynamic

Defines a field that provide the maximum value allowed (excluding the maximum value) for this field.

Content

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.

Node value

JSON property

JSON format

Description

Required

content

Content of simple type

Content of group and list

Contains the node value. Available for all nodes except for association and selection. However, their content can be retrieved by invoking the URL provided in their details property.

No

details

String

corresponding to an absolute REST resource URL.

Returns the node details when invoked.

The response type depends on the meta type.

  • foreignKey: target record (available on table, record and field operations).

  • resource: target resource (available on dataset node, table, record and field operations).

  • association: target table containing the associated records (available on table and record operations).

  • selection: target table containing the associated records (available on table and record operations).

  • group: target dataset group node (available on dataset tree operation).

  • table: target table (available on dataset tree operation).

Example:

http://.../BReference/dataset/root/table/pk/associationField

No

historyDetails

String

corresponding to an absolute REST resource URL.

Returns the node history details when invoked.

See also

No

label

String

Contains the foreign key or enumeration label in the current locale.

The default label is returned if the current locale is not supported.

No

inheritanceMode

String

Contains the node's inheritance state, considering only dataset inheritance. inheritedFieldMode and inheritanceMode properties cannot be both defined on the same node.

No

inheritedFieldMode

String

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. inheritedFieldMode and inheritanceMode properties cannot be both defined on the same node.

No

selector

String

corresponding to an absolute URL.

Contains the appropriate URL for selector operation.

Example:

http://.../BReference/dataset/root/table/pk/enumField?selector=true

No

validation

Array

Contains the validation report that concerns the current node context.

No

Content of simple type

A simple field value is stored in a JSON Object and its content is the value of the content property.

Content of group and list

XML Schema

JSON format

Examples

Meta type

Group

xs:complexType

Object

Contains a property per sub-node.

Example for a simple-occurrence group.

{
  "road": {
    "content": "11 rue scribe"
  },
  "zipcode": {
    "content": "75009"
  },
  "country": {
    "content": "France"
  }
}

group

List

maxOccurs > 1

Array

Contains an array of all field occurrences represented by a JSON Object.

Each object is represented as a node value.

Example for a multi-occurrence field of xs:int type.

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

Meta of simple type,

or

group

Selector

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": [
    {
      "content": "F",
      "label": "feminine"
    },
    {
      "content": "M",
      "label": "masculine"
    }
  ],
  "pagination": {
    "firstPage": null,
    "nextPage": null,
    "previousPage": null,
    "lastPage": null
  }
}
Documentation > Developer Guide > REST data services > JSON Formats