C.4 Custom operation

29.5013GPP5G SystemPrinciples and Guidelines for Services DefinitionRelease 18Stage 3TS

The custom operation archetype can be used to model an unsafe and non-idempotent operation that is not a Create on a collection.

A custom operation does not operate directly on the resource that would be identified by the custom operation URI. Instead, when the custom operation is associated with a resource, the operation is performed on this associated resource. For instance, a custom operation may modify the associated resource in a special way. This associated resource is identified by stripping the suffix string "/<custOpName>" from the custom operation URI template in clause 4.4.2.

When the custom operation is not associated with any resource but with the service, it acts as an executable function with input parameters and returns the result of the executed function in the response body, not modifying any resource.

POST is the only method allowed with a custom operation URI.

The semantic of the custom operation is encoded in the last segment of the URI template in clause 4.4.2: /{custOpName}.

Annex D (informative):
Example of an OpenAPI specification file for Patch

As described in clause 4.6.1.1.3.2, the bodies of HTTP PATCH requests will either use a "JSON Merge Patch" encoding as defined in IETF RFC 7396 [7], or a "JSON Patch" encoding as defined IETF RFC 6902 [8]. This annex provides an example OpenAPI Specification [4] allowing both encodings.

NOTE: Both encoding possibilities are shown in this example for illustrative purposes. However, only a single of the above encodings will be specified for each resource where the PATCH method is supported unless backward compatibility considerations necessitate the support of both encodings.

openapi: 3.0.0

info:

version: "1.0.0"

title: PATCH Example

paths:

/inventory:

post:

summary: adds an inventory item

operationId: addInventory

description: Adds an item to the system

responses:

‘201’:

description: item created

‘400’:

description: ‘invalid input, object invalid’

‘409’:

description: an existing item already exists

requestBody:

content:

application/json:

schema:

$ref: ‘#/components/schemas/InventoryItem’

description: Inventory item to add

/inventory/{id}:

get:

summary: read inventory item

parameters:

– name: id

in: path

required: true

schema:

type: integer

responses:

‘200’:

description: search results matching criteria

content:

application/json:

schema:

$ref: ‘#/components/schemas/InventoryItem’

‘400’:

description: bad input parameter

patch:

summary: patch inventory item

parameters:

– name: id

in: path

required: true

schema:

type: integer

requestBody:

required: true

content:

application/json-patch+json:

schema:

$ref: ‘#/components/schemas/PatchInventoryItem’

application/merge-patch+json:

schema:

$ref: ‘#/components/schemas/MergePatchInventoryItem’

responses:

‘200’:

description: Patch was succesfull and updated Inventory Item is returned.

content:

application/json:

schema:

$ref: ‘#/components/schemas/InventoryItem’

‘204’:

description: Patch was succesfull

‘400’:

description: bad input parameter

components:

schemas:

InventoryItem:

type: object

required:

– name

– manufacturer

properties:

id:

type: integer

name:

type: string

manufacturer:

$ref: ‘#/components/schemas/Manufacturer’

customers:

type: array

items:

type: string

Manufacturer:

type: object

required:

– name

properties:

name:

type: string

homePage:

type: string

format: url

phone:

type: string

PatchInventoryItem:

type: array

description: A JSON PATCH body schema to Patch selected parts of an Inventory Item

items:

anyOf:

– oneOf:

– type: object

description: Modifies the URL of a Manufacturer

properties:

op:

type: string

enum:

– "add"

– "remove"

– "replace"

path:

type: string

pattern: ‘^\/manufacturer\/homePage$’

value:

type: string

format: url

required:

– "op"

– "path"

– type: object

description: Modifies a Manufacturer

properties:

op:

type: string

enum:

– "replace"

path:

type: string

pattern: ‘^\/manufacturer$’

value:

$ref: ‘#/components/schemas/Manufacturer’

required:

– "op"

– "path"

– "value"

– type: object

description: Modifies a Customer

properties:

op:

type: string

enum:

– "add"

– "remove"

– "replace"

path:

type: string

pattern: ‘^\/customers\/(-|\d+)$’

value:

type: string

required:

– "op"

– "path"

– type: object

description: Open Alternative

minItems: 1

MergePatchInventoryItem:

description: A JSON Merge PATCH body schema to Patch selected parts of an Inventory Item

type: object

properties:

manufacturer:

$ref: ‘#/components/schemas/Manufacturer’

nullable: true

customers:

type: array

description: Allows to replace the entire array, but not to modify individual elements.

items:

type: string

Annex E (Informative):
Considerations for handling of JSON arrays

This Annex provides guidelines on the use of JSON arrays on the SBI APIs of the 5GC.

As described in clause 5.2.4, the data model of an API definition in a 5GC API consists of any of the different data types supported by OpenAPI, corresponding to the different data structures found in the JSON data format. One of these structures is the "array", representing a set of ordered values.

It should be noted that, while JSON allows that the value of the elements of an array may be of different types, in OpenAPI Specification [4]this is further restricted, and all elements of an array shall be of the same type.

Also, it is important to note that the JSON format itself, as specified in IETF RFC 8259 [3], does not define any syntax to refer to specific array elements.

However, there are certain conventions to specify mechanism to refer to array elements, e.g. based on the position a given element has in the array.

In particular, the JSON Pointer syntax defines a string syntax for identifying a specific value within a JSON document. This syntax consists of a number of tokens separated by the "/" character; in order to refer to a specific element in an array, then token shall contain an unsigned decimal value, indicating the zero-based index of the element in the array.

EXAMPLE:

JSON document:

{

"attr1": 0,

"attr2": true,

"attr3": [ 1, 2, 3 ]

}

JSON Pointer expression "/attr3/0" evaluated on such JSON document: 1

There are several scenarios, frequently employed in the 5GC APIs, that make use of the JSON Pointer mechanism to refer to specific elements in an array:

– Update of resources using the PATCH method, as described in clause 4.6.1.1.3.2. If the syntax used in the PATCH request payload is based on the "JSON Patch" format, then the JSON Pointer mechanism is used to specify patch operations applied to specific array elements.

– Notifications of events (such as data changes), as described in clause 4.6.2.3, using as notification payload the notation defined in "NotifyItem" / "ChangeItem" data types defined in 3GPP TS 29.571 [5]. This notation is similar to "JSON Patch", so it also makes use of the JSON Pointer syntax to refer to specific array elements.

– Explicit usage of attributes containing JSON Pointer expressions in request or response payloads.

In these scenarios, it is critical that any JSON Pointer expression is applied by both client and server on the exact same array representation, since otherwise the indexes may vary, and the JSON Pointer will give unexpected results.

A typical scenario that may create issues could be as follows:

1. NF Service Consumer sends a first GET request towards a NF Service Producer, including certain query parameters in the HTTP request, that result into retrieving a resource representation that contains a subset of the data that the NF Service Producer holds under such resource. When such subset refers to returning just some of the elements of an array, rather than the entire array, then the content of the array will differ between consumer and producer.

2a. The NF Service Consumer sends a subsequent PATCH request towards the NF Service Producer, with the intention to modify a given element of the array (specified by the array index, per the JSON Pointer syntax). This results into the server modifying a wrong element in the array, given that the NF Service Producer contains a different array.

2b. The NF Service Consumer may subscribe to be notified by the NF Service Producer when a given resource representation has changed. When the NF Service Producer detects such a change, it sends a notification that may include a reference to an array index, which may be different than the array index kept by the NF Service Producer.

2c. The NF Service Consumer is a stateless NF Service Consumer that has no local representation of the array that subscribes to be notified by the NF Service Producer when a given resource representation has changed.

Another scenario that may lead to incorrect array updates is:

1. Two different NF Service Consumer sends a GET request towards a NF Service Producer to retrieve the representation of a certain resource.

2. A first NF Service Consumer NF1 sends a PATCH request towards the NF Service Producer, with the intention to delete a given element of the array (specified by the array index, per the JSON Pointer syntax). This results in some of the array indexes being changed (of those elements placed after the deleted element)

3. A second NF Service Consumer NF2, sends another PATCH request towards the NF Service Producer, to modify any of the elements of the array whose index was affected by the previous operation done by NF1. This results in modifying unintendedly the wrong array element.

The design of 5GC SBI APIs should take into account these scenarios and provide mechanisms to avoid unintended modifications of array elements, when they are referred by their position index in the array.

To achieve these, both NF Service Consumer and Producer (taking the role of HTTP client and server) should ensure that any resource update takes place on a known and current resource representation, based on the content of ETag values sent along with resource representations by the resource owner.

If an NF Service Consumer needs to cache a resource representation received from an NF Service Producer (i.e. the JSON information received in an HTTP response message), it shall use the exact same representation of arrays as received from the service producer.

When sending notifications or modifications whose semantics is based on the JSON Pointer syntax, the sending NF shall use the exact same representation of arrays as previously signalled in a previous interaction with the receiver of such notifications/modifications.Further, when sending notifications whose semantics is based on the JSON Pointer syntax, if the NF Service Consumer is a stateless NF Service Consumer and thus has no local representation of the array, the NF Producer shall use the complete replacement array representation as the NF Service Consumer is otherwise required to request the complete data from the NF Service Producer with a GET request.

Annex F (informative):
Change history

Change history

Date

Meeting

TDoc

CR

Rev

Cat

Subject/Comment

New version

2017-10

CT4#80

C4-175250

TS skeleton

0.1.0

2017-10

CT4#80

C4-175358

C4-175252

C4-175253

C4-175254

C4-175255

C4-175331

C4-175332

C4-175333

C4-175334

C4-175359

C4-175327

C4-175328

C4-175360

C4-175330

C4-175336

C4-175337

Inclusion of pCRs agreed at CT4#80

0.2.0

2017-12

CT4#81

C4-176414
C4-176372
C4-176447
C4-176415
C4-176416
C4-176417
C4-176418
C4-176250
C4-176419
C4-176422

Inclusion of pCRs agreed at CT4#81

0.3.0

2018-01

CT4#82

C4-181179
C4-181384

Inclusion of pCRs agreed at CT4#82

0.4.0

2018-03

CT4#83

C4-182396
C4-182397
C4-182394
C4-182395
C4-182399
C4-182261
C4-182184
C4-182330
C4-182398
C4-182332

Inclusion of pCRs agreed at CT4#83

0.5.0

2018-03

CT#79

CP-180029

Presented for information

1.0.0

2018-04

CT4#84

C4-183238
C4-183288
C4-183289
C4-183291
C4-183292
C4-183385
C4-183387
C4-183388
C4-183477
C4-183478

Inclusion of pCRs agreed at CT4#84

1.1.0

2018-05

29.xxx-SBI-Stage3 Template added in zip-file.

1.1.1

2018-05

CT4#85

C4-184492
C4-184493
C4-184494
C4-184495
C4-184496
C4-184544
C4-184614
C4-184503
C4-184497
C4-184592

Inclusion of pCRs agreed at CT4#85

1.2.0

2018-06

CT#80

CP-181099

Presented for approval

2.0.0

2018-06

CT#80

Approved in CT#80.

15.0.0

2018-07

TS template added in zip-file

15.0.1

2018-09

CT#81

CP-182054

0001

4

B

Security requirements for API design

15.1.0

2018-09

CT#81

CP-182054

0002

F

Example URIs in figures

15.1.0

2018-09

CT#81

CP-182054

0003

2

F

Clarification on the use of API version number

15.1.0

2018-09

CT#81

CP-182054

0004

2

F

External Docs Clause in OpenAPI file

15.1.0

2018-09

CT#81

CP-182054

0006

1

B

JSON Structures in Query Parameters

15.1.0

2018-09

CT#81

CP-182054

0008

1

F

Servers Selection in OpenAPI

15.1.0

2018-09

CT#81

CP-182054

0009

F

Query Parameter

15.1.0

2018-09

CT#81

CP-182054

0010

F

yaml file names

15.1.0

2018-09

CT#81

CP-182054

0011

F

OpenAPI servers field

15.1.0

2018-09

CT#81

CP-182054

0012

1

F

Query parameter

15.1.0

2018-09

CT#81

CP-182054

0013

1

F

presence condition and cardinality

15.1.0

2018-09

CT#81

CP-182054

0014

1

F

Clarification on Naming Conventions and Digits

15.1.0

2018-09

CT#81

CP-182054

0015

1

F

URIs of created resources

15.1.0

2018-09

CT#81

CP-182054

0016

1

F

Custom operation in resource structure presentation

15.1.0

2018-12

CT#82

CP-183012

0018

2

F

Attribute Presence Conditions

15.2.0

2018-12

CT#82

CP-183012

0019

1

F

Version addressed by references within OpenAPI files

15.2.0

2018-12

CT#82

CP-183012

0020

2

F

Resolve Editor’s Note

15.2.0

2018-12

CT#82

CP-183012

0021

F

Attribute with Any Type

15.2.0

2018-12

CT#82

CP-183012

0022

F

Incorrect resource URI structure presentation

15.2.0

2018-12

CT#82

CP-183012

0023

1

F

Storage of OpenAPI files within a central directory

15.2.0

2018-12

CT#82

CP-183012

0025

3

F

Complex query expression

15.2.0

2018-12

CT#82

CP-183012

0031

1

F

Correction and Clarification on Security Requirements

15.2.0

2018-12

CT#82

CP-183012

0032

2

R

Subscription Lifetime for Subscribe / Notify operations

15.2.0

2018-12

CT#82

CP-183012

0033

F

Usage of the "tags" field in OpenAPI

15.2.0

2018-12

CT#82

CP-183012

0035

2

F

Corrections to API versioning

15.2.0

2018-12

CT#82

CP-183012

0036

1

F

Security in Open API specification files

15.2.0

2018-12

CT#82

CP-183012

0037

1

F

Custom Operations

15.2.0

2019-03

CT#83

CP-190017

0039

2

F

Address Editor’s Note on implicit subscriptions

15.3.0

2019-03

CT#83

CP-190017

0040

F

Address Editor’s Note on partial representation in POST response

15.3.0

2019-03

CT#83

CP-190017

0041

1

F

Maximum HTTP payload size

15.3.0

2019-03

CT#83

CP-190017

0042

1

F

HTTP Scheme

15.3.0

2019-03

CT#83

CP-190017

0043

2

F

Resolve Editor’s Notes

15.3.0

2019-03

CT#83

CP-190017

0044

F

Correction to Minor Field Increment Rules in API Versioning

15.3.0

2019-03

CT#83

CP-190017

0045

1

F

Handling of unknown attributes during resource creation and modification

15.3.0

2019-03

CT#83

CP-190017

0046

1

F

Correct use of "OpenAPI" name

15.3.0

2019-03

CT#83

CP-190017

0047

1

F

Resolution of Editor´s Notes in Annex C

15.3.0

2019-03

CT#83

CP-190017

0048

2

F

IANA registration of "3gppHal+json" media type

15.3.0

2019-03

CT#83

CP-190017

0049

1

F

Addition of applicability column to query parameters table

15.3.0

2019-03

CT#83

CP-190017

0050

1

F

Removing multiple redundant appearances of major version number in TS template to ease update of that number

15.3.0

2019-03

CT#83

CP-190017

0051

2

F

Storage of OpenAPI specification files

15.3.0

2019-03

CT#83

CP-190017

0052

F

Use of Relative URI in Location Header

15.3.0

2019-06

CT#84

CP-191028

0053

2

F

Criteria for non-backward compatible changes

15.4.0

2019-06

CT#84

CP-191028

0056

1

F

Reuse of Structured Data Types

15.4.0

2019-06

CT#84

CP-191028

0057

1

F

Delete editor’s note on complex query

15.4.0

2019-06

CT#84

CP-191028

0059

F

Correction on Notifications

15.4.0

2019-06

CT#84

CP-191028

0060

1

F

Copyright Note in YAML files

15.4.0

2019-06

CT#84

CP-191028

0055

2

F

Precedence of OpenAPI file

15.4.0

2019-06

CT#84

CP-191028

0054

4

F

Withdrawing API versions

15.4.0

2019-06

CT#84

CP-191057

0061

2

F

Updates to TS Template for SBI

16.0.0

2019-09

CT#85

CP-192101

0065

1

F

Externaldoc version number change

16.1.0

2019-12

CT#86

CP-193025

0069

2

A

Fourth field of API versions

16.2.0

2019-12

CT#86

CP-193036

0070

1

F

Add Corresponding API descriptions in clause 5.1

16.2.0

2019-12

CT#86

CP-193063

0066

2

B

HAL-forms media type

16.2.0

2019-12

CT#86

CP-193063

0067

1

F

Extending ProblemDetails for Backward Compatibility

16.2.0

2020-03

CT#87e

CP-200054

0072

1

F

Storage of YAML files in ETSI Forge

16.3.0

2020-03

CT#87e

CP-200039

0073

1

F

New tables in 29.501 template

16.3.0

2020-06

CT#88e

CP-201034

0074

2

F

Clarifications to callback URI

16.4.0

2020-06

CT#88e

CP-201034

0075

1

B

Resource-Level Authorization

16.4.0

2020-06

CT#88e

CP-201034

0077

2

F

Delimiters – URI and SBI specific

16.4.0

2020-06

CT#88e

CP-201034

0078

2

F

URI types

16.4.0

2020-06

CT#88e

CP-201034

0080

F

Correct the Resource Tree Example

16.4.0

2020-06

CT#88e

CP-201034

0081

1

F

Requirements for secure API design

16.4.0

2020-06

CT#88e

CP-201034

0079

1

F

API URI correction and template udpate

16.4.0

2020-06

CT#88e

CP-201034

0082

1

F

Maximum JSON payload size

16.4.0

2020-06

CT#88e

CP-201071

0076

F

Correction of the method used for Notification

16.4.0

2020-06

CT#88e

CP-201071

0083

1

F

Missing abbreviations

16.4.0

2020-09

CT#89e

CP-202043

0093

A

Storage of YAML files in 3GPP Forge

16.5.0

2020-09

CT#89e

CP-202109

0085

2

D

Editorial fixes

16.5.0

2020-09

CT#89e

CP-202110

0086

2

F

Handling of JSON Arrays

16.5.0

2020-09

CT#89e

CP-202110

0087

F

Naming requirements for resource/operation-level scopes

16.5.0

2020-09

CT#89e

CP-202110

0088

1

F

Data types with string type

16.5.0

2020-09

CT#89e

CP-202110

0089

F

Content of Location header when TLS is used

16.5.0

2020-09

CT#89e

CP-202110

0090

F

Miscellaneous corrections

16.5.0

2020-09

CT#89e

CP-202110

0091

1

F

API URI correction and template update

16.5.0

2020-12

CT#90e

CP-203064

0094

F

API Versioning System based on Semantic Versioning

17.0.0

2020-12

CT#90e

CP-203064

0095

F

OpenAPI Reference

17.0.0

2020-12

CT#90e

CP-203064

0096

F

OpenAPI "description" fields in data type definitions

17.0.0

2021-03

CT#91e

CP-210027

0097

D

Use of inclusive terminology

17.1.0

2021-03

CT#91e

CP-210021

0098

F

Guidance on Error Response design for Indirect Communication

17.1.0

2021-03

CT#91e

CP-210021

0099

1

B

SBI TS Template Update

17.1.0

2021-03

CT#91e

CP-210021

0101

D

Editorial Corrections

17.1.0

2021-03

CT#91e

CP-210021

0102

F

Withdrawing API versions

17.1.0

2021-06

CT#92e

CP-211065

0105

A

Nested cardinality

17.2.0

2021-06

CT#92e

CP-211028

0103

1

F

Change Notification of Array to Stateless NF Consumer

17.2.0

2021-06

CT#92e

CP-211028

0103

1

B

Additional guidelines for OpenAPI specification files

17.2.0

2021-09

CT#93e

CP-212026

0107

1

F

Compatibility Clarification

17.3.0

2021-09

CT#93e

CP-212026

0108

2

F

Clarification to API name guidance in the SBI template

17.3.0

2021-09

CT#93e

CP-212026

0109

2

F

Corrections to the API URI and relative URI below root concepts

17.3.1

2021-12

CT#94e

CP-213085

0110

1

F

Miscellaneous clarifications

17.4.0

2021-12

CT#94e

CP-213087

0111

5

F

Resource URI structure in the Guidelines for Services Definition

17.4.0

2021-12

CT#94e

CP-213086

0112

2

F

Resource URI structure in the SBI skeleton

17.4.0

2021-12

CT#94e

CP-213086

0114

F

Subscription update with PUT request

17.4.0

2022-03

CT#95e

CP-220023

0115

1

F

Adding examples to the Resource URI structure clause

17.5.0

2022-03

CT#95e

CP-220023

0116

1

F

Handling Description field along with the ‘$ref’ keyword

17.5.0

2022-03

CT#95e

CP-220023

0117

1

F

Aligning SBI-Stage3-Template with TS 29.501

17.5.0

2022-03

CT#95e

CP-220023

0118

F

JSON schema example with a combination of restrictions

17.5.0

2022-03

CT#95e

CP-220024

0122

F

URL Encoding

17.5.0

2022-03

CT#95e

CP-220024

0120

1

D

Miscellaneous corrections to the 5GC SBI TS Skeleton

17.5.0

2022-03

CT#95e

CP-220025

0119

1

F

Formatting of Description Fields

17.5.0

2022-03

CT#95e

CP-220025

0121

1

F

Notification Clarification

17.5.0

2022-06

CT#96

CP-221027

0123

1

F

SBI stage 3 template update – OpenAPI

17.6.0

2022-06

CT#96

CP-221027

0124

1

F

SBI stage 3 template update – Data models

17.6.0

2022-06

CT#96

CP-221027

0125

F

Remove the apiVersion placeholder from the resource URI variables table

17.6.0

2022-06

CT#96

CP-221028

0127

F

oAuth2 clarification

17.6.0

2022-06

CT#96

CP-221029

0126

1

F

Default logical relationship between query parameters

17.6.0

2022-09

CT#97e

CP-222070

0129

1

A

Essential Correction for Location Header in 201 Response

17.7.0

2022-09

CT#97e

CP-222026

0130

1

F

Limits for number and length of query parameters

17.7.0

2022-12

CT#98e

CP-223027

0132

F

Standalone Notifications

18.0.0

2022-12

CT#98e

CP-223029

0131

1

F

Description fields in enumerations

18.0.0