Content for TS 29.501 Word version: 18.4.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 , or a
"JSON Patch" encoding as defined
RFC 6902 . 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
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
