7 Resource representation formats
32.1583GPPDesign rules for REpresentational State Transfer (REST) Solution Sets (SS)Management and orchestrationRelease 17TS
7.1 Introduction
According to clause 4.3 the media type specifies only that JSON is used as resource representation format carried in the HTTP request and HTTP response message bodies. Some resource patterns are quite common and it is desirable to use a common pattern throughout different APIs. This clause identifies some patterns frequently encountered and provides a JSON schema for them.
7.2 Top-level object
A single JSON object shall be at the top-level of the document carried in the message body of HTTP requests and HTTP responses.
{"type": "object"}
Example:
{}
Members of the top-level object can be either a data object, a data array or an error object.
7.3 Data objects
Data objects are carried in HTTP requests and in HTTP responses in case of success. One and only one data object shall be a member of a top-level object. If a data object is present, no error object shall be present.
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {}
}
}
}
Example:
{
"data": {}
}
7.4 Data arrays
Data arrays are carried in HTTP requests and in HTTP responses when data is transferred. One and only one data array shall be a member of a top-level object. If a data array is present, no error object shall be present.
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {}
}
}
}
Example JSON instance:
{
"data": []
}
7.5 Error objects
Error objects are carried in HTTP responses in case of failure. One and only one error object shall be a member of a top-level object.
{
"type": "object",
"properties": {
"error": {
"type": "object"
"properties": {}
}
}
}
Example JSON instance:
{
"error": {}
}
7.6 Resource objects
Resource objects (resources) are representations of managed object instances. They shall be compliant to the following JSON schema when one instance of a class is allowed.
{
"type": "object",
"properties": {
"ClassName": {
"type": "object",
"properties": {
"href": { "type": "string" },
"class": { "type": "string" },
"id": { "type": "string" },
"attributes": {
"type": "object",
"properties": {}
}
},
"required": ["id"]
}
}
}
or by the following schema when more than one instance of a class is allowed
{
"type": "object",
"properties": {
"ClassName": {
"type": "array",
"items": {
"type": "object",
"properties": {
"href": { "type": "string" },
"class": { "type": "string" },
"id": { "type": "string" },
"attributes": {
"type": "object",
"properties": {}
}
},
"required": ["id"]
}
}
}
}
An object, whose name is equal to the NRM class name, encapsulates the resource representation.
The "attributes" object contains NRM attributes as properties. In the generic schema above the "attributes" object has no properties. These properties are defined in other specifications.
Only the "id" is required to be always present. The "href" property with the URI of the resource and the "class" property with the name of the NRM class can be omitted, or not specified at all in concrete JSON schemas for resource representations.
TS 32.160 [16] specifies the complete mapping of stage 2 NRM definitions to stage 3 JSON schema definitions.
7.7 Resource objects carried in data objects and arrays
When a resource object is carried in a data object the schema is given by
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"ClassName": {
"type": "object",
"properties": {
"href": { "type": "string" },
"class": { "type": "string" },
"id": { "type": "string" },
"attributes": {
"type": "object",
"properties": {}
}
},
"required": ["id"]
}
}
}
}
}
Multiple instance of the same NRM class are supported by a JSON array.
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"ClassName": {
"type": "array",
"items": {
"type": "object",
"properties": {
"href": { "type": "string" },
"class": { "type": "string" },
"id": { "type": "string" },
"attributes": {
"type": "object",
"properties": {}
}
},
"required": ["id"]
}
}
}
}
}
}