附录 A. JSON Schema 表示 (JSON Schema Representation)
中文导读: 本节对应 RFC 9944 的 附录 A. JSON Schema 表示 (JSON Schema Representation) 部分, 对应文档标题为 RFC 9944 - SCIM 模型的设备模式扩展. 下方若包含英文 RFC 原文, 注册表名称, 字段名, 算法名, 对象标识符, 媒体类型, 邮箱地址, URL, 代码, ABNF, ASN.1, YANG, JSON, XML, 测试向量或参考文献条目, 均按规范原样保留, 因为这些内容需要与 RFC 文本, IANA 注册表, 实现代码或验证工具逐字一致. 中文段落用于说明本节的作用, 阅读重点和实现含义, 不改变任何协议语义或注册值.
本页包含机器可读或接近机器可读的规范材料. 对 ASN.1, YANG, JSON Schema, XML Schema, 伪代码, 注册模板, 常量表和算法标识符, 翻译时必须保留关键字, 类型名, OID, namespace, 枚举值, 字段名和语法结构. 实现者应把这些块视为生成代码, 配置模型, 验证输入或一致性测试的依据.
补充实现说明: 本页英文比例高, 是因为主要内容属于可复制的规范材料或实现材料. 在这类页面中, 语法关键字, 缩进, 字符串字面量, 枚举值, 路径, OID, namespace, JSON member, YANG leaf, ASN.1 type 和错误文本都可能被测试工具, 代码生成器或互操作实现直接消费. 因此, 译文只在代码块外说明结构和用途, 不在代码块内替换术语. 实现者应结合正文的语义说明检查默认值, 约束, 必选字段, 扩展点和安全影响, 并用原样保留的块进行验证.
进一步使用说明: 本页保留的英文内容在审计中占比较高, 但这种保留是有意的. 对参考文献页而言, 英文题名, 作者, DOI, RFC 编号和 URL 是正式引用的一部分, 翻译后反而会降低检索和核对的准确性. 对 Schema, YANG, ASN.1, 伪代码, 示例和测试向量而言, 英文字段, 字符串, 枚举, 缩进和换行可能直接影响工具解析或一致性测试. 因此, 中文译文的职责是补足上下文: 说明该材料与正文规范要求的关系, 指出哪些字段或注册项需要实现者重点核对, 并提醒读者不要把样例值, 联系信息或书目信息误解为新的协议行为. 如果需要确认强制性要求, 应回到正文中带有 MUST, MUST NOT, SHOULD, MAY 等 BCP 14 关键词的段落, 或查阅本页列出的规范性引用. 这种处理方式在可读性和逐字保真之间取平衡, 确保中文读者能够理解页面用途, 同时保留可复制, 可验证, 可追溯的 RFC 原始材料.
本附录给出 SCIM Device 和 EndpointApp 资源及其扩展的 JSON Schema 表示. 代码块中的 schema URI, 属性名, 枚举值, 示例字符串和结构均为可实现材料, 因此保持原样.
Appendix A. JSON Schema Representation
A.1. Resource Schema
<CODE BEGINS>
[
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"\
],
"id": "Device",
"name": "Device",
"endpoint": "/Devices",
"description": "Device account.",
"schema": "urn:ietf:params:scim:schemas:core:2.0:Device",
"meta": {
"location": "https://example.com/v2/ResourceTypes/Device",
"resourceType": "ResourceType"
}
},
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"\
],
"id": "EndpointApp",
"name": "EndpointApp",
"endpoint": "/EndpointApps",
"description": "Endpoint application such as device control and \
telemetry.",
"schema": "urn:ietf:params:scim:schemas:core:2.0:EndpointApp",
"meta": {
"location": "https://example.com/v2/ResourceTypes/EndpointApps",
"resourceType": "ResourceType"
}
}
]
<CODE ENDS>
A.2. Core Device Schema
<CODE BEGINS>
{
"id": "urn:ietf:params:scim:schemas:core:2.0:Device",
"name": "Device",
"description": "Entry containing attributes about a device.",
"attributes" : [
{
"name": "displayName",
"type": "string",
"description": "Human-readable name of the device, suitable \
for displaying to end users, for example, 'BLE Heart Monitor' etc.",
"multiValued": false,
"required": false,
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
},
{
"name": "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.",
"multiValued": false,
"required": true,
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
},
{
"name": "mudUrl",
"type": "reference",
"description": "A URL to MUD file of the device (RFC 8520).",
"multiValued": false,
"required": false,
"caseExact": true,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
},
{
"name": "groups",
"type": "complex",
"multiValued": true,
"description": "A list of groups to which the device belongs, \
either through direct membership, through nested groups, or \
dynamically calculated.",
"required": false,
"subAttributes": [
{
"name": "value",
"type": "string",
"multiValued": false,
"description": "The identifier of the device's group.",
"required": false,
"caseExact": false,
"mutability": "readOnly",
"returned": "default",
"uniqueness": "none"
},
{
"name": "$ref",
"type": "reference",
"referenceTypes": [
"Group"
],
"multiValued": false,
"description": "The URI of the corresponding 'Group' \
resource to which the device belongs.",
"required": false,
"caseExact": false,
"mutability": "readOnly",
"returned": "default",
"uniqueness": "none"
},
{
"name": "display",
"type": "string",
"multiValued": false,
"description": "A human-readable name, primarily used for \
display purposes. READ-ONLY.",
"required": false,
"caseExact": false,
"mutability": "readOnly",
"returned": "default",
"uniqueness": "none"
},
{
"name": "type",
"type": "string",
"multiValued": false,
"description": "A label indicating the attribute's \
function, e.g., 'direct' or 'indirect'.",
"required": false,
"caseExact": false,
"canonicalValues": [
"direct",
"indirect"
],
"mutability": "readOnly",
"returned": "default",
"uniqueness": "none"
}
],
"mutability": "readOnly",
"returned": "default"
}
],
"meta" : {
"resourceType" : "Schema",
"location" :
"/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:Device"
}
}
<CODE ENDS>
A.3. EndpointApp Schema
<CODE BEGINS>
{
"id": "urn:ietf:params:scim:schemas:core:2.0:EndpointApp",
"name": "EndpointApp",
"description": "Endpoint application and their credentials.",
"attributes" : [
{
"name": "applicationType",
"type": "string",
"description": "This attribute will only contain two values: \
deviceControl or telemetry.",
"multiValued": false,
"required": true,
"caseExact": false,
"mutability": "readOnly",
"returned": "default",
"uniqueness": "none"
},
{
"name": "applicationName",
"type": "string",
"description": "Human-readable name of the application.",
"multiValued": false,
"required": true,
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
},
{
"name": "certificateInfo",
"type": "complex",
"description": "Contains X.509 certificate's subject name and \
root CA information associated with the device control or telemetry \
app.",
"multiValued": false,
"required": false,
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none",
"subAttributes" : [
{
"name" : "rootCA",
"type" : "string",
"description" : "The base64 encoding of the DER encoding \
of the CA certificate.",
"multiValued" : false,
"required" : false,
"caseExact" : true,
"mutability" : "readWrite",
"returned" : "default",
"uniqueness" : "none"
},
{
"name" : "subjectName",
"type" : "string",
"description" : "A Common Name (CN) of the form of CN = \
dnsName.",
"multiValued" : false,
"required" : true,
"caseExact" : true,
"mutability" : "readWrite",
"returned" : "default",
"uniqueness" : "none"
}
]
},
{
"name": "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.",
"multiValued": false,
"required": false,
"caseExact": true,
"mutability": "readOnly",
"returned": "default",
"uniqueness": "none"
},
{
"name": "groups",
"type": "complex",
"multiValued": true,
"description": "A list of groups to which an endpoint \
application belongs, either through direct membership, through \
nested groups, or dynamically calculated.",
"required": false,
"subAttributes": [
{
"name": "value",
"type": "string",
"multiValued": false,
"description": "The identifier of the endpoint application\
's group.",
"required": false,
"caseExact": false,
"mutability": "readOnly",
"returned": "default",
"uniqueness": "none"
},
{
"name": "$ref",
"type": "reference",
"referenceTypes": [
"Group"
],
"multiValued": false,
"description": "The URI of the corresponding 'Group' \
resource to which the endpoint application belongs.",
"required": false,
"caseExact": false,
"mutability": "readOnly",
"returned": "default",
"uniqueness": "none"
},
{
"name": "display",
"type": "string",
"multiValued": false,
"description": "A human-readable name, primarily used for \
display purposes. READ-ONLY.",
"required": false,
"caseExact": false,
"mutability": "readOnly",
"returned": "default",
"uniqueness": "none"
},
{
"name": "type",
"type": "string",
"multiValued": false,
"description": "A label indicating the attribute's \
function, e.g., 'direct' or 'indirect'.",
"required": false,
"caseExact": false,
"canonicalValues": [
"direct",
"indirect"
],
"mutability": "readOnly",
"returned": "default",
"uniqueness": "none"
}
],
"mutability": "readOnly",
"returned": "default"
}
],
"meta" : {
"resourceType" : "Schema",
"location" :
"/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:EndpointApp"
}
}
<CODE ENDS>
A.4. BLE Extension Schema
<CODE BEGINS>
[
{
"id": "urn:ietf:params:scim:schemas:extension:ble:2.0:Device",
"name": "bleExtension",
"description": "BLE extension for device account.",
"attributes" : [
{
"name": "versionSupport",
"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]\
.",
"multiValued": true,
"required": true,
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
},
{
"name": "deviceMacAddress",
"type": "string",
"pattern": "^[0-9A-Fa-f]{2}(:[0-9A-Fa-f]{2}){5}$",
"description": "A unique public MAC address assigned by the \
manufacturer.",
"multiValued": false,
"required": true,
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "Manufacturer"
},
{
"name": "isRandom",
"type": "boolean",
"description": "The isRandom flag is taken from the BLE \
core specifications 5.4. If true, device is using a random address\
. Default value is false.",
"multiValued": false,
"required": false,
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
},
{
"name": "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.",
"multiValued": true,
"required": false,
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
},
{
"name": "irk",
"type": "string",
"description": "Identity Resolving Key (IRK), which is \
unique for every device. It is used to resolve a random address. \
This value MUST NOT be set when separateBroadcastAddress is set.",
"multiValued": false,
"required": false,
"caseExact": false,
"mutability": "writeOnly",
"returned": "never",
"uniqueness": "Manufacturer"
},
{
"name": "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.",
"multiValued": false,
"required": false,
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
},
{
"name": "pairingMethods",
"type": "string",
"description": "List of pairing methods associated with the \
BLE device, stored as schema URI.",
"multiValued": true,
"required": true,
"caseExact": true,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
}
],
"meta" : {
"resourceType" : "Schema",
"location" : "/v2/Schemas/urn:ietf:params:scim:schemas:\
extension:ble:2.0:Device"
}
},
{
"id": "urn:ietf:params:scim:schemas:extension:pairingNull:2.0:\
Device",
"name": "nullPairing",
"description": "Null pairing method for BLE. It is included for \
the devices that do not have a pairing method.",
"meta" : {
"resourceType" : "Schema",
"location" : "/v2/Schemas/urn:ietf:params:scim:schemas:\
extension:pairingNull:2.0:Device"
}
},
{
"id": "urn:ietf:params:scim:schemas:extension:pairingJustWorks:2\
.0:Device",
"name": "pairingJustWorks",
"description": "Just Works pairing method for BLE.",
"attributes" : [
{
"name": "key",
"type": "integer",
"description": "Just Works does not have any key value. For \
completeness, it is added with a key value 'null'.",
"multiValued": false,
"required": false,
"caseExact": false,
"mutability": "immutable",
"returned": "default",
"uniqueness": "none"
}
],
"meta" : {
"resourceType" : "Schema",
"location" : "/v2/Schemas/urn:ietf:params:scim:schemas:\
extension:pairingJustWorks:2.0:Device"
}
},
{
"id": "urn:ietf:params:scim:schemas:extension:pairingPassKey:2.0\
:Device",
"name": "pairingPassKey",
"description": "Pass key pairing method for BLE.",
"attributes" : [
{
"name": "key",
"type": "integer",
"description": "A six-digit passkey for BLE a device. The \
pattern of key is ^[0-9]{6}$.",
"multiValued": false,
"required": true,
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
}
],
"meta" : {
"resourceType" : "Schema",
"location" : "/v2/Schemas/urn:ietf:params:scim:schemas:\
extension:pairingPassKey:2.0:Device"
}
},
{
"id": "urn:ietf:params:scim:schemas:extension:pairingOOB:2.0:\
Device",
"name": "pairingOOB",
"description": "Out-of-band pairing method for BLE.",
"attributes" : [
{
"name": "key",
"type": "string",
"description": "A key value retrieved from out-of-band \
source such as NFC.",
"multiValued": false,
"required": true,
"caseExact": true,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
},
{
"name": "randomNumber",
"type": "integer",
"description": "Nonce added to the key.",
"multiValued": false,
"required": true,
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
},
{
"name": "confirmationNumber",
"type": "integer",
"description": "Some solutions require confirmation number \
in RESTful message exchange.",
"multiValued": false,
"required": false,
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
}
],
"meta" : {
"resourceType" : "Schema",
"location" : "/v2/Schemas/urn:ietf:params:scim:schemas:\
extension:pairingOOB:2.0:Device"
}
}
]
<CODE ENDS>
A.5. DPP Extension Schema
<CODE BEGINS>
{
"id": "urn:ietf:params:scim:schemas:extension:dpp:2.0:Device",
"name": "dppExtension",
"description": "Device extension schema for Wi-Fi Easy \
Connect / Device Provisioning Protocol (DPP).",
"attributes" : [
{
"name": "dppVersion",
"type": "integer",
"description": "Version of DPP this device supports.",
"multiValued": false,
"required": true,
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
},
{
"name": "bootstrappingMethod",
"type": "string",
"description": "The list of all the bootstrapping methods \
available on the enrollee device, for example, [QR, NFC].",
"multiValued": true,
"required": false,
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
},
{
"name": "bootstrapKey",
"type": "string",
"description": "A base64-encoded Elliptic Curve Diffie-\
Hellman public key (may be P-256, P-384, or P-521).",
"multiValued": false,
"required": true,
"caseExact": true,
"mutability": "writeOnly",
"returned": "never",
"uniqueness": "none"
},
{
"name": "deviceMacAddress",
"type": "string",
"pattern": "^[0-9A-Fa-f]{2}(:[0-9A-Fa-f]{2}){5}$",
"description": "A unique public MAC address assigned by the \
manufacturer.",
"multiValued": false,
"required": false,
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "Manufacturer"
},
{
"name": "classChannel",
"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'.",
"multiValued": true,
"required": false,
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
},
{
"name": "serialNumber",
"type": "string",
"description": "An alphanumeric serial number that may also \
be passed as bootstrapping information.",
"multiValued": false,
"required": false,
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
}
],
"meta" : {
"resourceType" : "Schema",
"location" : "/v2/Schemas/urn:ietf:params:scim:schemas:\
extension:dpp:2.0:Device"
}
}
<CODE ENDS>
A.6. Ethernet MAB Extension Schema
<CODE BEGINS>
{
"id": "urn:ietf:params:scim:schemas:extension:ethernet-mab:2.0:\
Device",
"name": "ethernetMabExtension",
"description": "Device extension schema for MAC Authentication \
Bypass.",
"attributes" : [
{
"name": "deviceMacAddress",
"type": "string",
"pattern": "^[0-9A-Fa-f]{2}(:[0-9A-Fa-f]{2}){5}$",
"description": "A MAC address assigned by the manufacturer.",
"multiValued": false,
"required": true,
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "Manufacturer"
}
],
"meta" : {
"resourceType" : "Schema",
"location" : "/v2/Schemas/urn:ietf:params:scim:schemas:extension\
:ethernet-mab:2.0:Device"
}
}
<CODE ENDS>
A.7. FDO Extension Schema
<CODE BEGINS>
{
"id": "urn:ietf:params:scim:schemas:extension:fido-device-onboard:\
2.0:Device",
"name": "FDOExtension",
"description": "Device extension schema for FIDO Device Onboard (\
FDO).",
"attributes" : [
{
"name": "fdoVoucher",
"type": "string",
"description": "A voucher as defined in the FDO \
specification.",
"multiValued": false,
"required": true,
"caseExact": false,
"mutability": "writeOnly",
"returned": "never",
"uniqueness": "Manufacturer"
}
],
"meta" : {
"resourceType" : "Schema",
"location" : "/v2/Schemas/urn:ietf:params:scim:schemas:extension\
:fido-device-onboard:2.0:Device"
}
}
<CODE ENDS>
A.8. Zigbee Extension Schema
<CODE BEGINS>
{
"id": "urn:ietf:params:scim:schemas:extension:zigbee:2.0:Device",
"name": "zigbeeExtension",
"description": "Device extension schema for Zigbee.",
"attributes" : [
{
"name": "versionSupport",
"type": "string",
"description": "Provides a list of all the Zigbee versions \
supported by the device, for example, [3.0].",
"multiValued": true,
"required": true,
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
},
{
"name": "deviceEui64Address",
"type": "string",
"pattern": "^[0-9A-Fa-f]{2}(:[0-9A-Fa-f]{2}){7}$",
"description": "The 64-bit Extended Unique Identifier \
(EUI-64) device address.",
"multiValued": false,
"required": true,
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
}
],
"meta" : {
"resourceType" : "Schema",
"location" : "/v2/Schemas/urn:ietf:params:scim:schemas:extension\
:zigbee:2.0:Device"
}
}
<CODE ENDS>
A.9. endpointAppsExt Extension Schema
<CODE BEGINS>
{
"id": "urn:ietf:params:scim:schemas:extension:endpointAppsExt:2.0:\
Device",
"name": "endpointAppsExt",
"description": "Extension for partner endpoint applications that \
can onboard, control, and communicate with the device.",
"attributes" : [
{
"name": "applications",
"type": "complex",
"description": "Includes references to two types of \
applications that connect with enterprise, i.e., deviceControl and \
telemetry.",
"multiValued": true,
"required": true,
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none",
"subAttributes" : [
{
"name" : "value",
"type" : "string",
"description" : "The identifier of the EndpointApp.",
"multiValued" : false,
"required" : true,
"caseExact" : false,
"mutability" : "readWrite",
"returned" : "default",
"uniqueness" : "none"
},
{
"name" : "$ref",
"type" : "reference",
"referenceTypes" : "EndpointApps",
"description" : "The URI of the corresponding EndpointApp\
resource that will control or obtain data from the device.",
"multiValued" : false,
"required" : true,
"caseExact" : true,
"mutability" : "readOnly",
"returned" : "default",
"uniqueness" : "none"
}
]
},
{
"name": "deviceControlEnterpriseEndpoint",
"type": "reference",
"description": "The URL of the enterprise endpoint that \
device control apps use to reach enterprise network gateway.",
"multiValued": false,
"required": true,
"caseExact": true,
"mutability": "readOnly",
"returned": "default",
"uniqueness": "Enterprise"
},
{
"name": "telemetryEnterpriseEndpoint",
"type": "reference",
"description": "The URL of the enterprise endpoint that \
telemetry apps use to reach enterprise network gateway.",
"multiValued": false,
"required": false,
"caseExact": true,
"mutability": "readOnly",
"returned": "default",
"uniqueness": "Enterprise"
}
],
"meta" : {
"resourceType" : "Schema",
"location" : "/v2/Schemas/urn:ietf:params:scim:schemas:extension\
:endpointAppsExt:2.0:Device"
}
}
<CODE ENDS>