文件	说明
`schema-building.json`	建筑几何 + 核心实体（Building, Floor, Room, Aperture, Boundary, Element, Shaft 等）
`schema-energy.json`	能耗模拟领域（Material, Construction, RoomProgram, Schedule 等）

Schema 规则

1. JSON 为唯一真理源

所有类型定义以 JSON 文件为准。TypeScript / Python 等语言的绑定代码均从 JSON 生成，不得手工维护。

2. 不保存派生数据

Schema 只保存原始定义数据，不包含任何可从已有字段计算得出的值。

❌ area        — 可由 region 计算
❌ volume      — 可由 region + height 计算
❌ boundingBox — 可由子实体几何计算
✅ region      — 房间轮廓点集
✅ height      — 房间高度

3. 字段命名

规则	示例
使用 camelCase	`siteBasePoint`, `sillHeight`, `openRatio`
避免缩写（广为人知的除外）	`identifier` 而非 `id`, `displayName` 而非 `name`
布尔值用正面语义	`operable` 而非 `nonOperable`
枚举值用 snake_case	`exterior_wall`, `curtain_wall`

4. 类型系统

基础类型：

string — 字符串
number — 浮点数
integer — 整数
boolean — 布尔值
object — 任意对象

复合类型：

TypeName[] — 数组，如 Polyline3d 的 points 字段类型为 Point3d[]
TypeName — 引用自定义类型或实体

自定义类型定义在 types 段，描述纯数据结构，不是业务实体。例如 Point3d（三维点）、Polyline3d（多段线）、TimePoint（时刻点）。

5. 实体结构

"EntityName": {
  "description": "中文说明",
  "tags": { "scale": ["building"], "simulation": ["energy"] },
  "attributes": {
    "fieldName": {
      "type": "string",
      "required": true,
      "unit": "m",
      "default": 0,
      "description": "字段说明",
      "tags": { "scale": ["building"], "simulation": ["energy", "daylight"] }
    }
  },
  "children": {
    "childName": {
      "type": "ChildEntity",
      "multiple": true,
      "description": "子实体说明"
    }
  }
}

attributes — 标量字段（string, number, boolean, enum, 自定义类型）
children — 关联的子实体（1:1 或 1:N）
required: true — 必填字段，序列化时必须存在
default — 缺省值（可选字段未提供时使用）
unit — 单位标注（仅文档用途）

6. 判别联合体（Discriminated Union）

当一个实体存在多种形态时，使用 variants 表达：

"Room": {
  "discriminator": "creationMethod",
  "variants": {
    "planar_extrude": { ... },
    "mass_slice": { ... },
    "manual": { ... }
  }
}

不同变体可包含不同的必填字段。判别字段的值决定了使用哪个变体。当前使用判别联合体的实体：

Room — 判别字段 creationMethod，变体：planar_extrude、mass_slice、manual
Aperture — 判别字段 sourceType，变体：hosted、declarative

7. 枚举

枚举定义在 enums 段，每个枚举列出所有允许值。

8. 尺度与模拟类型标签（tags）

每个字段可标注两个维度的标签：

尺度（scale）：

标签	说明
`building`	建筑尺度
`community`	社区/街区尺度
`urban`	城市尺度

模拟类型（simulation）：

标签	说明
`energy`	能耗模拟
`daylight`	采光分析
`solar`	日照分析
`thermal_comfort`	热舒适分析
`carbon`	碳排放核算
`wind`	风环境模拟
`general`	通用（不特定于某种模拟）

标签用于快速筛选特定尺度或某类模拟分析所需的字段。例如：

"northAngle": {
  "type": "number",
  "tags": { "simulation": ["energy", "daylight", "solar", "thermal_comfort", "wind"] }
}

表示 northAngle 对能耗、采光、日照、热舒适、风环境模拟均有影响。

"embodiedCarbon": {
  "type": "number",
  "tags": { "scale": ["building", "community", "urban"], "simulation": ["carbon"] }
}

表示 embodiedCarbon 适用于建筑/社区/城市三个尺度，仅用于碳排放核算。

9. 只描述数据本身

Schema 只描述建筑数据本身，不描述数据的生成方式。

使用方式

各项目从 JSON schema 生成对应语言的类型代码：

# TypeScript（示例）
python3 scripts/gen-ts.py schema-building.json > dist/building.d.ts

# Python Pydantic（示例）
python3 scripts/gen-py.py schema-building.json > archgen_schema/building.py

具体生成器暂时不在本仓库维护。

TODO

定义 building / community / urban 每个尺度的最小字段集合
制定 required 与 default 的判定规则文档
梳理影响模拟性能的字段并标注影响等级
明确"智能优化"的定义和 scope（形态优化 vs 性能目标驱动）
确定优化变量、约束条件在 schema 中的表达方式
考察与 GSA Rules YAML 轨的复用可能性
完善 schema 的 tags 系统（如需新增 minScale / maxScale / performanceImpact / optimizable 等属性）

README.md Unescape Escape

bps-schema

仓库文件