附录 B. OpenAPI 表示 (OpenAPI Representation)
中文导读: 本节对应 RFC 9944 的 附录 B. OpenAPI 表示 (OpenAPI Representation) 部分, 对应文档标题为 RFC 9944 - SCIM 模型的设备模式扩展. 下方若包含英文 RFC 原文, 注册表名称, 字段名, 算法名, 对象标识符, 媒体类型, 邮箱地址, URL, 代码, ABNF, ASN.1, YANG, JSON, XML, 测试向量或参考文献条目, 均按规范原样保留, 因为这些内容需要与 RFC 文本, IANA 注册表, 实现代码或验证工具逐字一致. 中文段落用于说明本节的作用, 阅读重点和实现含义, 不改变任何协议语义或注册值.
本页包含的英文术语大多是协议标识符, 字段名, 章节名, 算法名或标准化缩写. 这些词在实现和互操作测试中通常按英文出现, 因此保留原文. 中文说明用于补足上下文, 帮助读者理解该节与整体协议行为, 安全边界, 部署约束或数据模型之间的关系.
补充说明: 本页保留较多英文, 是为了维护协议标识符, 标准化术语和原始 RFC 结构的可追溯性. 中文译文优先解释该节在文档中的作用, 实现者需要关注的边界, 以及哪些内容属于规范性文本, 示例材料或注册元数据. 如果某个英文词同时也是字段名, 方法名, 注册项或算法名称, 则应按英文精确使用. 阅读时应把中文说明与保留的原文块一起理解, 避免把说明性文字误认为新增协议要求.
进一步使用说明: 本页保留的英文内容在审计中占比较高, 但这种保留是有意的. 对参考文献页而言, 英文题名, 作者, DOI, RFC 编号和 URL 是正式引用的一部分, 翻译后反而会降低检索和核对的准确性. 对 Schema, YANG, ASN.1, 伪代码, 示例和测试向量而言, 英文字段, 字符串, 枚举, 缩进和换行可能直接影响工具解析或一致性测试. 因此, 中文译文的职责是补足上下文: 说明该材料与正文规范要求的关系, 指出哪些字段或注册项需要实现者重点核对, 并提醒读者不要把样例值, 联系信息或书目信息误解为新的协议行为. 如果需要确认强制性要求, 应回到正文中带有 MUST, MUST NOT, SHOULD, MAY 等 BCP 14 关键词的段落, 或查阅本页列出的规范性引用. 这种处理方式在可读性和逐字保真之间取平衡, 确保中文读者能够理解页面用途, 同时保留可复制, 可验证, 可追溯的 RFC 原始材料.
本附录以 OpenAPI 形式表示核心 Device schema 和相关扩展. 以下小节仅供参考. 代码块中的 OpenAPI 字段, schema 名称, 属性名, 枚举值和示例内容保持原样.
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>