Appendix B. OpenAPI Representation
この節では SCIM device schema extensions の RFC 原文を保持し, Device and EndpointApp resource types, BLE, DPP, Ethernet MAB, FDO, Zigbee, endpointAppsExt, JSON Schema, OpenAPI, IANA registrations, security considerations を含めます.
Appendix B. OpenAPI Representation
The following sections are provided for informational purposes.
B.1. Core Device Schema OpenAPI Representation
OpenAPI representation of core device schema is as follows:
<CODE BEGINS>
openapi: 3.1.0
info:
title: SCIM Device Schema
version: 1.0.0
components:
schemas:
Group:
type: object
description: A list of groups to which the device belongs,
either through direct membership, through nested
groups, or dynamically calculated.
properties:
value:
type: string
description: The unique identifier of a group,
typically a UUID.
readOnly: true
writeOnly: false
display:
type: string
description: A display string for the group.
readOnly: true
writeOnly: false
$ref:
type: string
format: uri
description: Reference to the group object.
readOnly: true
writeOnly: true
Device:
description: Entry containing attributes about a device.
type: object
properties:
displayName:
type: string
description: "Human-readable name of the device, suitable
for displaying to end users, for example,
'BLE Heart Monitor' etc."
readOnly: false
writeOnly: false
active:
type: boolean
description: A mutable boolean value indicating the device
administrative status. If true, the
commands (such as connect, disconnect,
subscribe) that control app sends to the
controller for the devices will be processed
by the controller. If false, any command
coming from the control app for the device
will be rejected by the controller.
readOnly: false
writeOnly: false
mudUrl:
type: string
format: uri
description: A URL to MUD file of the device (RFC 8520).
It is added for future use. Current usage is
not defined yet.
readOnly: false
writeOnly: false
groups:
type: array
description: List of groups to which a device belongs to.
items:
$ref: '#/components/schemas/Group'
required:
- active
additionalProperties: false
allOf:
- $ref: '#/components/schemas/CommonAttributes'
CommonAttributes:
type: object
properties:
schemas:
type: array
items:
type: string
enum:
- urn:ietf:params:scim:schemas:core:2.0:Device
description: The list of schemas that define the resource.
id:
type: string
format: uri
description: The unique identifier for a resource.
readOnly: true
writeOnly: false
externalId:
type: string
description: An identifier for the resource that is
defined by the provisioning client.
readOnly: false
writeOnly: false
meta:
type: object
readOnly: true
properties:
resourceType:
type: string
description: The name of the resource type of the
resource.
readOnly: true
writeOnly: false
location:
type: string
format: uri
description: The URI of the resource being returned.
readOnly: true
writeOnly: false
created:
type: string
format: date-time
description: The date and time the resource was added
to the service provider.
readOnly: true
writeOnly: false
lastModified:
type: string
format: date-time
description: The most recent date and time that the
details of this resource were updated at
the service provider.
readOnly: true
writeOnly: false
version:
type: string
description: The version of the resource.
readOnly: true
writeOnly: false
additionalProperties: false
<CODE ENDS>
B.2. EndpointApp Schema OpenAPI Representation
OpenAPI representation of EndpointApp schema is as follows:
<CODE BEGINS>
openapi: 3.1.0
info:
title: SCIM Endpoint App Schema
version: 1.0.0
components:
schemas:
Group:
type: object
description: A list of groups to which the endpoint
application belongs, either through
direct membership, through nested
groups, or dynamically calculated.
properties:
value:
type: string
description: The unique identifier of a group,
typically a UUID.
readOnly: true
writeOnly: false
display:
type: string
description: A display string for the group.
readOnly: true
writeOnly: false
$ref:
type: string
format: uri
description: Reference to the group object.
readOnly: true
writeOnly: true
EndpointApp:
title: EndpointApp
description: Endpoint application resource.
type: object
properties:
applicationType:
type: string
description: This attribute will only contain two values:
deviceControl or telemetry.
readOnly: false
writeOnly: false
applicationName:
type: string
description: Human-readable name of the application.
readOnly: false
writeOnly: false
groups:
type: array
description: List of groups to which the EndpointApp
belongs.
items:
$ref: '#/components/schemas/Group'
required:
- applicationType
- applicationName
additionalProperties: true
oneOf:
- $ref: '#/components/schemas/clientToken'
- $ref: '#/components/schemas/certificateInfo'
allOf:
- $ref: '#/components/schemas/CommonAttributes'
clientToken:
type: string
description: "This attribute contains a token that the client
will use to authenticate itself. Each token may
be a string up to 500 characters in length."
readOnly: true
writeOnly: false
certificateInfo:
type: object
description: "Contains X.509 certificate's subject name and
root CA information associated with the device
control or telemetry app."
properties:
rootCA:
type: string
description: "The base64 encoding of a trust anchor
certificate, as per RFC 4648, Section 4."
readOnly: false
writeOnly: false
subjectName:
type: string
description: "Also known as the Common Name (CN), the
Subject Name is a field in the X.509
certificate that identifies the primary
domain or IP address for which the
certificate is issued."
readOnly: false
writeOnly: false
required:
- subjectName
CommonAttributes:
type: object
properties:
schemas:
type: array
items:
type: string
enum:
- urn:ietf:params:scim:schemas:core:2.0:EndpointApp
description: The list of schemas that define the resource.
id:
type: string
format: uri
description: The unique identifier for a resource.
readOnly: true
writeOnly: false
meta:
type: object
readOnly: true
properties:
resourceType:
type: string
description: The name of the resource type of the
resource.
readOnly: true
writeOnly: false
location:
type: string
format: uri
description: The URI of the resource being returned.
readOnly: true
writeOnly: false
created:
type: string
format: date-time
description: The date and time the resource was added
to the service provider.
readOnly: true
writeOnly: false
lastModified:
type: string
format: date-time
description: The most recent date and time that the
details of this resource were updated at
the service provider.
readOnly: true
writeOnly: false
version:
type: string
description: The version of the resource.
readOnly: true
writeOnly: false
additionalProperties: false
<CODE ENDS>
B.3. BLE Extension Schema OpenAPI Representation
OpenAPI representation of BLE extension schema is as follows:
<CODE BEGINS>
openapi: 3.1.0
info:
title: SCIM Bluetooth Extension Schema
version: 1.0.0
components:
schemas:
BleDevice:
type: object
description: BLE device schema.
properties:
schemas:
type: array
items:
type: string
enum:
- urn:ietf:params:scim:schemas:extension:ble:2.0
:Device
urn:ietf:params:scim:schemas:extension:ble:2.0:Device:
$ref: '#/components/schemas/BleDeviceExtension'
required: true
BleDeviceExtension:
type: object
properties:
versionSupport:
type: array
items:
type: string
description: Provides a list of all the BLE versions
supported by the device, for example,
[4.1, 4.2, 5.0, 5.1, 5.2, 5.4].
readOnly: false
writeOnly: false
deviceMacAddress:
type: string
description: It is the public MAC address assigned by the
manufacturer. It is a unique 48-bit value. The
regex pattern is
^[0-9A-Fa-f]{2}(:[0-9A-Fa-f]{2}){5}.
readOnly: false
writeOnly: false
isRandom:
type: boolean
description: AddressType flag is taken from the BLE core
specifications 5.4. If false, the device is
using a public MAC address. If true, device
is using a random address.
readOnly: false
writeOnly: false
separateBroadcastAddress:
type: string
description: "When present, this address is used for
broadcasts/advertisements. This value
MUST NOT be set when an IRK is provided.
Its form is the same as deviceMacAddress."
readOnly: false
writeOnly: false
irk:
type: string
description: Identity Resolving Key (IRK), which is unique
for every device. It is used to resolve a
random address.
readOnly: false
writeOnly: true
mobility:
type: boolean
description: If set to true, the BLE device will
automatically connect to the closest AP. For
example, if a BLE device is connected with
AP-1 and moves out of range but comes in
range of AP-2, it will be disconnected with
AP-1 and connected with AP-2.
readOnly: false
writeOnly: false
pairingMethods:
type: array
items:
type: string
description: List of pairing methods associated with the
BLE device, stored as schema URI.
readOnly: false
writeOnly: false
urn:ietf:params:scim:schemas:extension:pairingNull:2.0
:Device:
$ref: '#/components/schemas/NullPairing'
required: false
urn:ietf:params:scim:schemas:extension:pairingJustWorks:2.0
:Device:
$ref: '#/components/schemas/PairingJustWorks'
required: false
urn:ietf:params:scim:schemas:extension:pairingPassKey:2.0
:Device:
$ref: '#/components/schemas/PairingPassKey'
required: false
urn:ietf:params:scim:schemas:extension:pairingOOB:2.0
:Device:
$ref: '#/components/schemas/PairingOOB'
required: false
required:
- versionSupport
- deviceMacAddress
- AddressType
- pairingMethods
additionalProperties: false
NullPairing:
type: object
PairingJustWorks:
type: object
description: Just Works pairing method for BLE.
properties:
key:
type: integer
description: Just Works does not have any key value. For
completeness, it is added with a key value
'null'.
readOnly: false
writeOnly: false
required:
- key
PairingPassKey:
type: object
description: Passkey pairing method for BLE.
properties:
key:
type: integer
description: A six-digit passkey for a BLE device.
The pattern of key is ^[0-9]{6}$.
readOnly: false
writeOnly: true
required:
- key
PairingOOB:
type: object
description: Out-of-band pairing method for BLE.
properties:
key:
type: string
description: The OOB key value for a BLE device.
readOnly: false
writeOnly: false
randomNumber:
type: integer
description: Nonce added to the key.
readOnly: false
writeOnly: true
confirmationNumber:
type: integer
description: Some solutions require a confirmation number
in the RESTful message exchange.
readOnly: false
writeOnly: true
required:
- key
- randomNumber
<CODE ENDS>
B.4. DPP Extension Schema OpenAPI Representation
OpenAPI representation of DPP extension schema is as follows:
<CODE BEGINS>
openapi: 3.1.0
info:
title: SCIM Device Provisioning Protocol Extension Schema
version: 1.0.0
components:
schemas:
DppDevice:
type: object
description: Wi-Fi Easy Connect (DPP) device extension schema.
properties:
schemas:
type: array
items:
type: string
enum:
- urn:ietf:params:scim:schemas:extension:dpp:2.0
:Device
urn:ietf:params:scim:schemas:extension:dpp:2.0:Device:
$ref: '#/components/schemas/DppDeviceExtension'
required: true
DppDeviceExtension:
type: object
properties:
dppVersion:
type: integer
description: Version of DPP this device supports.
readOnly: false
writeOnly: false
bootstrappingMethod:
type: array
items:
type: string
description: The list of all the bootstrapping methods
available on the enrollee device, for
example, [QR, NFC].
readOnly: false
writeOnly: false
bootstrapKey:
type: string
description: An Elliptic Curve Diffie-Hellman
(ECDH) public key. The base64-encoded length
for P-256, P-384, and P-521 is 80, 96, and
120 characters.
readOnly: false
writeOnly: true
deviceMacAddress:
type: string
description: The MAC address assigned by the manufacturer.
The regex pattern is
^[0-9A-Fa-f]{2}(:[0-9A-Fa-f]{2}){5}.
readOnly: false
writeOnly: false
classChannel:
type: array
items:
type: string
description: A list of global operating class and channel
shared as bootstrapping information. It is
formatted as class/channel, for example,
'81/1', '115/36'.
readOnly: false
writeOnly: false
serialNumber:
type: string
description: An alphanumeric serial number that may also
be passed as bootstrapping information.
readOnly: false
writeOnly: false
required:
- dppVersion
- bootstrapKey
additionalProperties: false
<CODE ENDS>
B.5. Ethernet MAB Extension Schema OpenAPI Representation
OpenAPI representation of Ethernet MAB extension schema is as
follows:
<CODE BEGINS>
openapi: 3.1.0
info:
title: SCIM MAC Authentication Bypass Extension Schema
version: 1.0.0
components:
schemas:
EthernetMABDevice:
type: object
description: Ethernet MAC Authenticated Bypass.
properties:
schemas:
type: array
items:
type: string
enum:
- urn:ietf:params:scim:schemas:extension:ethernet-mab
:2.0:Device
urn:ietf:params:scim:schemas:extension:ethernet-mab:2.0
:Device:
$ref: '#/components/schemas/EthernetMABDeviceExtension'
required: true
EthernetMABDeviceExtension:
type: object
properties:
deviceMacAddress:
type: string
description: It is the public MAC address assigned by the
manufacturer. It is a unique 48-bit value.
The regex pattern is
^[0-9A-Fa-f]{2}(:[0-9A-Fa-f]{2}){5}.
readOnly: false
writeOnly: false
required:
- deviceMacAddress
description: Device extension schema for Ethernet-MAB.
<CODE ENDS>
B.6. FDO Extension Schema OpenAPI Representation
OpenAPI representation of FDO extension schema is as follows:
<CODE BEGINS>
openapi: 3.1.0
info:
title: SCIM FIDO Device Onboarding Extension Schema
version: 1.0.0
components:
schemas:
FDODevice:
type: object
description: FIDO Device Onboarding (FDO) extension.
properties:
schemas:
type: array
items:
type: string
enum:
- urn:ietf:params:scim:schemas:extension:fido-device
-onboard:2.0:Device
urn:ietf:params:scim:schemas:extension:fido-device-onboard
:2.0:Device:
$ref: '#/components/schemas/FDODeviceExtension'
required: true
FDODeviceExtension:
type: object
properties:
fdoVoucher:
type: string
description: A FIDO Device Onboard (FDO) voucher.
readOnly: false
writeOnly: false
required:
- fdoVoucher
description: Device extension for a FIDO Device Onboard (FDO).
<CODE ENDS>
B.7. Zigbee Extension Schema OpenAPI Representation
OpenAPI representation of Zigbee extension schema is as follows:
<CODE BEGINS>
openapi: 3.1.0
info:
title: SCIM Zigbee Extension Schema
version: 1.0.0
components:
schemas:
ZigbeeDevice:
type: object
description: Zigbee device schema.
properties:
schemas:
type: array
items:
type: string
enum:
- urn:ietf:params:scim:schemas:extension:zigbee:2.0
:Device
urn:ietf:params:scim:schemas:extension:zigbee:2.0:Device:
$ref: '#/components/schemas/ZigbeeDeviceExtension'
required: true
ZigbeeDeviceExtension:
type: object
properties:
versionSupport:
type: array
items:
type: string
description: Provides a list of all the Zigbee versions
supported by the device, for example, [3.0].
readOnly: false
writeOnly: false
deviceEui64Address:
type: string
description: The 64-bit Extended Unique Identifier (EUI-64)
device address. The regex pattern is
^[0-9A-Fa-f]{16}$.
readOnly: false
writeOnly: false
required:
- versionSupport
- deviceEui64Address
description: Device extension schema for Zigbee.
<CODE ENDS>
B.8. endpointAppsExt Extension Schema OpenAPI Representation
OpenAPI representation of endpointAppsExt extension schema is as
follows:
<CODE BEGINS>
openapi: 3.1.0
info:
title: SCIM Endpoint Extension Schema
version: 1.0.0
components:
schemas:
EndpointAppsExt:
type: object
properties:
applications:
$ref: '#/components/schemas/applications'
deviceControlEnterpriseEndpoint:
type: string
format: url
description: The URL of the enterprise endpoint that
device control apps use to reach an
enterprise network gateway.
readOnly: true
writeOnly: false
telemetryEnterpriseEndpoint:
type: string
format: url
description: The URL of the enterprise endpoint that
telemetry apps use to reach an enterprise
network gateway.
readOnly: true
writeOnly: false
required:
- applications
- deviceControlEnterpriseEndpoint
applications:
type: array
items:
value:
type: string
description: The identifier of the EndpointApp.
readOnly: false
writeOnly: false
ref:
type: string
format: uri
description: The URI of the corresponding EndpointApp
resource that will control or obtain data
from the device.
readOnly: true
writeOnly: false
required:
- value
- ref
<CODE ENDS>