Content for TS 29.501 Word version: 19.0.0
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
RFC 7396 , a
"JSON Patch" encoding as defined
RFC 6902 , or an HTTP multipart message with the multipart/mixed content-type as described in
RFC 2046 . 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'
multipart/mixed:
schema:
$ref: '#/components/schemas/MultipartPatch'
encoding:
patch: # The patch part shall be the first part
contentType: application/json-patch+json
headers:
Content-Id:
schema:
type: string
required: true
binaryBlocks: # 0 or more block parts may follow the patch part
contentType: '*/*' # Block part can be of any type
headers:
Content-Id: # Block identifier is defined by the Content-Id header.
schema:
type: string
required: true
Content-Transfer-Encoding:
schema:
type: string
required: true
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
description: Represents the manufacturer.
required:
- name
properties:
name:
type: string
homePage:
type: string
format: url
phone:
type: string
ManufacturerRm:
type: object
description: >
This data type is defined in the same way as the "Manufacturer" data type,
but with the OpenAPI "nullable: true" property.
required:
- name
properties:
name:
type: string
homePage:
type: string
format: url
phone:
type: string
nullable: true
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/ManufacturerRm'
customers:
type: array
description: Allows to replace the entire array, but not to modify individual elements.
items:
type: string
BinaryBlock:
description: A Block can be of any type
example: >-
"QmxvY2sgY29udGVudA=="
MultipartPatch:
description: Definition of a Record Patch
type: object
properties:
patch:
# json patch as defined in RFC 6902
type: array
items:
$ref: 'TS29571_CommonData.yaml#/components/schemas/PatchItem'
minItems: 1
blocks:
# List of multipart data
type: array
description: list of opaque Block's being reffered to by PatchItems
items:
$ref: '#/components/schemas/BinaryBlock'
minItems: 1
required:
- patch
example: >-
{"patch" : [{ "op" : "add" , "path" : "/firstBodyPart/callbackReference" ,
"value" : "https://example.com " },
{ "op" : "copy" , "from" : "/binaryBlocks/blockID1" , "to" : "/Binaryblocks/blockID2" },
{ "op" : "add" , "path" : "/binaryBlocks/blockID1" , "value" : "addedBlock1" }],
"blocks" : [{"Content-Id" : "addedBlock1" ,
"Content-Type" : "text/plain" , "content" : "QmxvY2sgY29udGVudA==" }]}
