本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 格式规范
Cloud Directory 架构会向数据目录中的数据添加结构。Cloud Directory 提供了两种机制，供您定义架构。开发人员可以使用特定 API 操作构建架构，也可以使用架构上传功能完全上传架构。架构文档可以通过 API 调用或通过控制台进行上传。本节介绍上传整个架构文档时要使用的格式。
## JSON 架构格式
架构文档是采用以下整体格式的 JSON 文档。
```
{
"facets": {
"facet name": {
"facetAttributes": {
"attribute name": Attribute JSON Subsection
}
}
}
}
```
架构文档包含分面名称到分面的映射。每个分面进而包含一个映射，其中包含属性。架构中的所有分面名称都必须唯一。分面中的所有属性名称都必须唯一。
### 属性 JSON 子部分
分面包含属性。每个属性都定义可以存储在属性中的值的类型。以下 JSON 格式描述一个属性。
```
{
"attributeDefinition": Attribute Definition Subsection,
"attributeReference": Attribute Reference Subsection,
"requiredBehavior": "REQUIRED_ALWAYS" or "NOT_REQUIRED"
}
```
必须提供属性定义或属性引用。有关每个内容的更多信息，请参阅相关子部分。
必需行为字段指示此属性是否为必需的。必须提供此字段。可能值如下所示：
+ `REQUIRED_ALWAYS`：创建对象或是向对象添加分面时必须提供此属性。无法删除此属性。
+ `NOT_REQUIRED`：此属性可以存在，也可以不存在。
### 属性定义子部分
属性定义与属性值关联的类型和规则。下面的 JSON 布局对格式进行说明。
```
{
"attributeType": One of "STRING", "NUMBER", "BINARY", "BOOLEAN" or "DATETIME",
"defaultValue": Default Value Subsection,
"isImmutable": true or false,
"attributeRules": "Attribute Rules Subsection"
}
```
### 默认值子部分
精确指定以下默认值之一。长数值和布尔值应在引号外部提供 (作为其相应的 Javascript 类型而不是字符串)。二进制值使用 URL 安全 Base64 编码字符串提供 (如 RFC 4648 中所述)。日期时间采用自纪元 (1970 年 1 月 1 日 00:00:00 UTC) 以来的毫秒数提供。
```
{
"stringValue": "a string value",
"longValue": an integer value,
"booleanValue": true or false,
"binaryValue": a URL-safe Base64 encoded string,
"datetimeValue": an integer value representing milliseconds since epoch
}
```
### 属性规则子部分
属性规则对属性值定义约束。可以为每个属性定义多个规则。属性规则包含规则的规则类型和参数集。可以在[属性规则](schemas_attributerules.md) 一节中找到更多详细信息。
```
{
"rule name": {
"parameters": {
"rule parameter key 1": "value",
"rule parameter key 2": "value"
},
"ruleType": "rule type value"
}
}
```
### 属性引用子部分
属性引用是高级功能。它们使多个分面可以共享属性定义和存储的值。有关更多信息，请参阅[属性引用](schemas_attributereferences.md)部分。可以使用以下模板在 JSON 架构中定义属性引用。
```
{
"targetSchemaArn": "schema ARN"
"targetFacetName": "facet name"
"targetAttributeName": "attribute name"
}
```
## 架构文档示例
以下为显示有效 JSON 格式设置的架构文档示例。
**注意**
在 `allowedValues` 字符串中表示的所有值必须以逗号分隔并且没有空格。例如：`"SENSITIVE,CONFIDENTIAL,PUBLIC"`。
### 基本架构文档
```
{
"facets": {
"Employee": {
"facetAttributes": {
"Name": {
"attributeDefinition": {
"attributeType": "STRING",
"isImmutable": false,
"attributeRules": {
"NameLengthRule": {
"parameters": {
"min": "3",
"max": "100"
},
"ruleType": "STRING_LENGTH"
}
}
},
"requiredBehavior": "REQUIRED_ALWAYS"
},
"EmailAddress": {
"attributeDefinition": {
"attributeType": "STRING",
"isImmutable": true,
"attributeRules": {
"EmailAddressLengthRule": {
"parameters": {
"min": "3",
"max": "100"
},
"ruleType": "STRING_LENGTH"
}
}
},
"requiredBehavior": "REQUIRED_ALWAYS"
},
"Status": {
"attributeDefinition": {
"attributeType": "STRING",
"isImmutable": false,
"attributeRules": {
"rule1": {
"parameters": {
"allowedValues": "ACTIVE,INACTIVE,TERMINATED"
},
"ruleType": "STRING_FROM_SET"
}
}
},
"requiredBehavior": "REQUIRED_ALWAYS"
}
},
"objectType": "LEAF_NODE"
},
"DataAccessPolicy": {
"facetAttributes": {
"AccessLevel": {
"attributeDefinition": {
"attributeType": "STRING",
"isImmutable": true,
"attributeRules": {
"rule1": {
"parameters": {
"allowedValues": "SENSITIVE,CONFIDENTIAL,PUBLIC"
},
"ruleType": "STRING_FROM_SET"
}
}
},
"requiredBehavior": "REQUIRED_ALWAYS"
}
},
"objectType": "POLICY"
},
"Group": {
"facetAttributes": {
"Name": {
"attributeDefinition": {
"attributeType": "STRING",
"isImmutable": true
},
"requiredBehavior": "REQUIRED_ALWAYS"
}
},
"objectType": "NODE"
}
}
}
```
### 具有类型化链接的架构文档
```
{
"sourceSchemaArn": "",
"facets": {
"employee_facet": {
"facetAttributes": {
"employee_login": {
"attributeDefinition": {
"attributeType": "STRING",
"isImmutable": true,
"attributeRules": {}
},
"requiredBehavior": "REQUIRED_ALWAYS"
},
"employee_id": {
"attributeDefinition": {
"attributeType": "STRING",
"isImmutable": true,
"attributeRules": {}
},
"requiredBehavior": "REQUIRED_ALWAYS"
},
"employee_name": {
"attributeDefinition": {
"attributeType": "STRING",
"isImmutable": true,
"attributeRules": {}
},
"requiredBehavior": "REQUIRED_ALWAYS"
},
"employee_role": {
"attributeDefinition": {
"attributeType": "STRING",
"isImmutable": true,
"attributeRules": {}
},
"requiredBehavior": "REQUIRED_ALWAYS"
}
},
"objectType": "LEAF_NODE"
},
"device_facet": {
"facetAttributes": {
"device_id": {
"attributeDefinition": {
"attributeType": "STRING",
"isImmutable": true,
"attributeRules": {}
},
"requiredBehavior": "REQUIRED_ALWAYS"
},
"device_type": {
"attributeDefinition": {
"attributeType": "STRING",
"isImmutable": true,
"attributeRules": {}
},
"requiredBehavior": "REQUIRED_ALWAYS"
}
},
"objectType": "NODE"
},
"region_facet": {
"facetAttributes": {},
"objectType": "NODE"
},
"group_facet": {
"facetAttributes": {
"group_type": {
"attributeDefinition": {
"attributeType": "STRING",
"isImmutable": true,
"attributeRules": {}
},
"requiredBehavior": "REQUIRED_ALWAYS"
}
},
"objectType": "NODE"
},
"office_facet": {
"facetAttributes": {
"office_id": {
"attributeDefinition": {
"attributeType": "STRING",
"isImmutable": true,
"attributeRules": {}
},
"requiredBehavior": "REQUIRED_ALWAYS"
},
"office_type": {
"attributeDefinition": {
"attributeType": "STRING",
"isImmutable": true,
"attributeRules": {}
},
"requiredBehavior": "REQUIRED_ALWAYS"
},
"office_location": {
"attributeDefinition": {
"attributeType": "STRING",
"isImmutable": true,
"attributeRules": {}
},
"requiredBehavior": "REQUIRED_ALWAYS"
}
},
"objectType": "NODE"
}
},
"typedLinkFacets": {
"device_association": {
"facetAttributes": {
"device_type": {
"attributeDefinition": {
"attributeType": "STRING",
"isImmutable": false,
"attributeRules": {}
},
"requiredBehavior": "REQUIRED_ALWAYS"
},
"device_label": {
"attributeDefinition": {
"attributeType": "STRING",
"isImmutable": false,
"attributeRules": {}
},
"requiredBehavior": "REQUIRED_ALWAYS"
}
},
"identityAttributeOrder": [
"device_label",
"device_type"
]
}
}
}
```