TIBCO EBX®

Documentation > Developer Guide > REST data services

Navigation modeDocumentation > Developer Guide > REST data services

JSON format

Introduction

The JSON (JavaScript Object Notation) is the data-interchange format used by TIBCO EBX® RESTful operations.

This format is lightweight, self-describing and can be used to design UIs or to integrate EBX® in a company's information system.

The data context is exhaustive, except for association fields and selection nodes that are not directly returned. However, these fields are included in the response with a URL link named details included by default. It can be indirectly used to get the fields content.
The volume of data is limited by a pagination mechanism activated by default, it can be configured or disabled.

URL formatted links allow retrieving:

Tables, records, dataset non-terminal nodes, foreign keys, resource fields (property details).
Possible values for foreign keys or enumerations (selector parameter).

Note

JSON data are always encoded in UTF-8.

Global structure

JSON Request body

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

Auth category

The request body holds several properties directly placed in the root JSON Object.

Token creation
Specifies the login and password to use for an authentication token creation attempt.
```
{
  "login": "...",                  // JSON String
  "password": "..."                // JSON String
}
```
Specifies the specific attribute, to activate the user authentication against the HTTP request, for an authentication token creation attempt.
```
{
  "specific": true                // JSON Boolean
}
```
See also
- Create token operation

Password change

Specifies the login, password and passwordNew to use for the password change.

{
  "login": "...",                  // JSON String
  "password": "...",               // JSON String
  "passwordNew": "..."             // JSON String
}

Data category

The request body contains at least a content property where master data values will be defined.

Dataset node

Specifies the target values of terminal nodes under the specified node. This request is used on the dataset node update operation.

{
   "content": {
      "nodeName1": {
         "content": true
      },
      "nodeName2": {
         "content": 2
      },
      "nodeName3": {
         "content": "Hello"
      }
   }
}

JSON Response body

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

Admin category

The selection operation for this category only provides the values corresponding to the request under a content property.

System information

Contains EBX® instance's system information. The representation of these data can be flat or hierarchical.

Flat representation:

{
	"content": {
		"bootInfoEBX": {
			"label": "EBX® configuration",
			"content": {
				"product.version": {
					"label": "EBX® product version",
					"content": "5.8.1 [...] Enterprise Edition"
				},
				"product.configuration.file": {
					"label": "EBX® main configuration file",
					"content": "System property [ebx.properties=./ebx.properties]"
				}
				// others keys 
			}
		},
		"repositoryInfo": {
			"label": "Repository information",
			"content": {
				"repository.identity": {
					"label": "Repository identity",
					"content": "00905A5753FD"
				},
				"repository.label": {
					"label": "Repository label",
					"content": "My repository"
				}
				// others keys 
			}
		},
		"bootInfoVM": {
			"label": "System information",
			"content": {
				"java.home": {
					"label": "Java installation directory",
					"content": "C:\\JTools\\jdk1.8.0\\jre"
				},
				"java.vendor": {
					"label": "Java vendor",
					"content": "Oracle Corporation"
				}
				// others keys 
			}
		}
	}
}

Hierarchical representation:

{
	"content": {
		"bootInfoEBX": {
		    "label": "EBX® configuration",
			"content": {
				"product": {
					"content": {
						"version": {
							"label": "EBX® product version",
							"content": "5.8.1 [...] Enterprise Edition"
						},
						"configuration": {
							"content": {
								"file": {
									"label": "EBX® main configuration file",
									"content": "System property [ebx.properties=./ebx.properties]"
								}
							}
						}
					}
				},
				"vm": {
					"content": {
						"startTime": {
							"label": "VM start time",
							"content": "2017/09/11-10:04:17-0729 CEST"
						},
						"identifier": {
							"label": "VM identifier",
							"content": "1"
						}
					}
				}
				// other hierarchical keys 
			}
		}
	}
}

Auth category

The response body contains several properties directly placed in its root JSON object.

Token creation

Contains the token value and its type.

{
  "accessToken": "...",            // JSON String
  "tokenType": "..."               // JSON String
}

Data category

The selection operation contains two different parts.

The first one named meta contains the exhaustive structure of the response.

The other, 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",
         "content": {
            "settings": {
               "details": "http://.../rootName/settings",
               "content": {
                  "weekTimeSheet": {
                     "details": "http://.../rootName/settings/settingA"
                  },
                  "vacationRequest": {
                     "details": "http://.../rootName/settings/settingB"
                  }
               }
            },
            "table1": {
               "details": "http://.../rootName/table1"
            },
            "table2": {
               "details": "http://.../rootName/table2"
            }
         }
      }
   }
}

The meta and validation properties are optional.

Note

Node, records and field in meta, rows and content may be hidden depending on their resolved permissions (see permissions).

Meta-data

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.

Structure of table

Table meta-data is represented by a JSON object with the following properties:

JSON property	JSON format	Description	Required
`name`	`String`	Name of the table defined in schema.	Yes
`label`	`String`	Table label. If undefined, the name of the schema node is returned.	Yes
`description`	`String`	Table description.	No
`type`	`String`	Always equal to: `table`.	Yes
`minOccurs`	`Number`	Number of minimum authorized record(s).	Yes
`maxOccurs`	`Number` or `String`	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 History	No
`primaryKeyFields`	`Array`	Array of the paths corresponding to the primary key.	Yes
`inheritance`	`Boolean`	Specifies whether the dataset inheritance is activated for the table. Its value is `true` if inheritance is activated, `false` otherwise. See also Inheritance and value resolution	No
`fields`	`Array`	Array of fields, that are direct children of the record node. Each field may also recursively contain sub-fields.	Yes

Structure of field

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

JSON property	JSON format	Description	Required
`name`	`String`	Name of the current authorized schema node.	Yes
`label`	`String`	Node label. If undefined, the name of the schema node is returned.	Yes
`description`	`String`	Node description.	No
`type`	`String`	Node type: simple type, `group`, `table`, `foreignKey`, etc.	Yes
`minOccurs`	`Number`	Number of minimum authorized occurrence(s).	Yes
`maxOccurs`	`Number` or `String`	Number of maximum authorized occurrence(s) or `unbounded`.	Yes
`inheritedField`	`Object`	Holds information related to the inherited field's value source. "inheritedField": { "sourceRecord": "/path/to/record", // (optional) "sourceNode": "./path/to/Node" } See also Inheritance and value resolution	No
`foreignKey`	`Object`	Contains information related to the target table. { "dataspace": "BAuthors", "dataset": "Authors", "tablePath": "/root/Authors", "details": "http://.../BAuthors/Authors/root/Authors" }	No (*)
`dataspace`	`String`	Target dataspace or snapshot identifier. This property is placed under the `foreignKey` property.	No (*)
`dataset`	`String`	Target dataset identifier. This property is placed under the `foreignKey` property.	No (*)
`tablePath`	`String`	Target table path. This property is placed under the `foreignKey` property.	Yes
`details`	`String`	Target table URL. This property is placed under the `foreignKey` property and is included by default.	No
`enumeration`	`String`	Specifies if the field is an enumeration value. Possible values are: `foreignKey` `static` `dynamic` `programmatic` `nomenclature` `resource` See also `SchemaFacetEnumeration` Specifies whether the field can be used for retrieving possible values by using the `selector` request parameter.	No
`valueFunction`	`Boolean`	Specifies if the field is a computed value. See also Computed values	No
`pathInDataset`	`String`	Relative field path starting from the schema node.	No (**)
`pathInRecord`	`String`	Relative field path starting from the table node.	No (*)
`filterable`	`Boolean`	Specifies whether the field can be used for filtering record using `filter` request parameter.	No (*)
`sortable`	`Boolean`	Specifies whether the field can be used in sort criteria using `sort` request parameter.	No (*)
`fields`	`Array` of `Object` elements	Contains the structure and typing of each group field.	No

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

(**) Only available for dataset tree operations.

Sort criteria information

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 contains a JSON Array that contains ordered sort criteria, and for each sort criterion, a JSON Object is added with the following properties:

JSON property	JSON format	Description	Required
`path`	`String`	Field path.	Yes
`order`	`String`	Possible values are: `asc`, `lasc`, `desc` or `ldesc`.	Yes

Validation

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 a target node path, a validation property is added on the root node.

A validation property contains a JSON Array and for each message, corresponding to a validation item, a JSON Object with properties:

JSON property	JSON format	Description	Required
`level`	`String`	Severity of the validation item, the possible values are: `info`, `warn`, `error`.	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 the table and dataset scopes, if associated resources exist and if it is included. See also `includeDetails` parameter	No

JSON property

JSON format

Description

Required

level

String

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

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 the table and dataset scopes, if associated resources exist and if it is included.

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 `association` and `selection`. However, their content can be retrieved by invoking the URL provided in `details`.	`No`
`details`	`String` corresponding to an absolute URL.	By invocation, the node details are returned. Response type after invocation depending on the meta type. `foreignKey`: target record (available on table, record and field operation). `resource`: target resource (available on dataset node, table, record and field operations). `association`: target table containing associated records (available on table and record operations). `selection`: target table containing 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`
`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. See also `inheritedFieldMode` Record lookup mechanism	`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. See also `inheritanceMode` Value lookup mechanism	`No`
`selector`	`String` corresponding to an absolute URL.	Correspond to the 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 the content is the value of the content property.

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

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 the `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`

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 the 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,

group

Pagination

This feature allows returning a limited and parameterizable number of data. Pagination can be applied to data of the following types: records, association values, selection node values and selectors. A context named pagination is returned only if it has been activated. This context allows browsing data similarly to the UI.

Pagination is activated by default.

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 if data is available in this context and not in the response.

Note

(**) Not present on selector.

Selector

By invoking the URL represented by the property selector on a field that provides an enumeration, this returns a JSON Object containing the properties:

rows containing an Array of JSON Object where each one contains two entries, such as the returned content that can be persisted and the corresponding label. The list of possible items is established depending on the current context.
(Optional) pagination containing pagination information (activated by default).

{
   "rows": [
      {
         "content": "F",
         "label": "feminine"
      },
      {
         "content": "M",
         "label": "masculine"
      }
   ],
   "pagination": {
      "nextPage": null
   }
}

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 ObjectArray, where each element corresponds to the result of a request element.
code contains an int of the 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 the 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 the 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 the 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 the JSON Number type, corresponds to the number of deleted records.
occultedCount containing an integer of the JSON Number type, corresponds to the number of occulted records.
inheritedCount containing an integer of the JSON Number type, corresponds to the number of inherited records.

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

Technical data

Each returned record is completed with the properties corresponding to its technical data, containing:

JSON property	JSON format	Description	Required
`creationDate`	`String`	Creation date.	Yes
`creationUser`	`String`	Creation user identifier.	Yes
`lastUpdateDate`	`String`	Last update date.	Yes
`lastUpdateUser`	`String`	Last update user identifier.	Yes

{
   ...
   "creationDate": "2015-12-24T19:00:53.158",
   "creationUser": "admin",
   "lastUpdateDate": "2015-12-25T00:00:00.001",
   "lastUpdateUser": "admin",
   ...
}

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.

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.

Documentation > Developer Guide > REST data services

TIBCO EBX® Version 5.9.17. Copyright © TIBCO Software Inc.2001-2022. All rights reserved.

All third party product and company names and third party marks mentioned in this document are the property of their respective owners and are mentioned for identification.

JSON format

Introduction

See also

Note

Global structure

JSON Request body

Auth category

See also

See also

Data category

See also

See also

See also

See also

See also

See also

See also

See also

See also

See also

JSON Response body

Admin category

See also

Auth category

See also

Data category

See also

See also

See also

See also

See also

See also

See also

Note

Meta-data

See also

Structure of table

See also

See also

Structure of field

See also

See also

See also

Sort criteria information

Validation

See also

Content

Node value

See also

See also

Content of simple type

Content of group and list

Pagination

See also

Note

Note

Selector

See also

Insert operation report

See also

Delete operation report

See also

Technical data

Update modes

See also

Note

Known limitations

Field values