# 🧩 Schema Engine
### 🧩 Schema Engine 架構圖
```mermaid
flowchart TD
%% --- 定義層 ---
subgraph "Definition Layer（定義層）"
ST["Semantic Types / Constraints / Modifiers"]
VS["ValueSpec（單一值規格）"]
SCH["Schema（結構＋關係規格）"]
end
%% --- 執行層 ---
subgraph "Runtime Layer（執行層）"
SE["Use Cases"]
UC1["Schema Validator"]
UC2["UI Schema Generator"]
UC3["API Contract / I-O Schema Generator"]
UC4["Model Factory / Data Builder"]
UC5["Other Tools（Codegen / Doc / Policy 等）"]
end
%% 語意原子 → 值規格 → 結構規格
ST --> VS
VS --> SCH
%% 定義進入引擎
ST --> SE
VS --> SE
SCH --> SE
%% 引擎提供給各種 use cases 使用
SE --> UC1
SE --> UC2
SE --> UC3
SE --> UC4
SE --> UC5
```
- Use Case: Schema Validator
```mermaid
flowchart TD
subgraph "Runtime Validator"
RT["Data"]
VAL["Validate"]
RES["Result"]
RT --> VAL
VAL --> RES
end
subgraph "Schema Validation"
RSCH["Data Schema"]
CM["Compile"]
RSC["RuntimeSchemaContext"]
RSCH --> CM
CM --> RSC
end
```
### Schema Engine檔案結構
> note: 目前是草稿,未來需要調整
- Multi-usecase oriented：不只 Validator，一個 Schema Engine 可以支援多種 use case
```text
schema-engine/
├── core/ # 「語言」與「模型」：不綁定任何 use case
│ ├── semantic-types/ # Semantic Types 的定義 + registry
│ │ ├── core-schemaValidation.types.js
│ │ ├── domain-tw.js
│ │ └── registry.js
│ │
│ ├── value-spec/ # ValueSpec 模型 + 工具
│ │ ├── valueSpec.model.js
│ │ └── valueSpec.utils.js
│ │
│ ├── schema/ # Schema / PathSpecNode / SchemaMeta
│ │ ├── schema.model.js # Root Schema 結構
│ │ ├── pathSpecNode.model.js # PathSpecNode (valueSpec + nodeConstraints + meta)
│ │ └── schema-meta.js # 版本、tag、描述等
│ │
│ └── api/ # 對內的 core API 介面（非具體 use case）
│ ├── schemaValidation.types.js # typedef / JSDoc 集中
│ └── factories.js # 建立 ValueSpec / PathSpecNode 的工廠
│
├── engine/ # Schema Engine 的「編譯核心」
│ ├── compiler/ # Schema Compiler：Schema → SchemaRuntimeContext
│ │ ├── schemaCompiler.js
│ │ ├── ruleStringParser.js
│ │ └── diagnostics.js
│ │
│ ├── runtime-context/ # SchemaRuntimeContext 的定義與操作
│ │ ├── context.model.js # typedef SchemaRuntimeContext
│ │ └── context.utils.js # clone / merge / debug helpers
│ │
│ └── plugins/ # Engine 級別的 plugin 機制（types / rules）
│ ├── type-plugins.js # 註冊與查找型別 plugin 的機制
│ └── rule-plugins.js # 單值 / collection / cross-field 規則 plugin 機制
│
├── usecases/ # 各種 Schema Driven use cases（Validator 僅是其中一個）
│ ├── validator/ # 你現在這一套 Schema Validator
│ │ ├── runtime/ # _runValidationWithCtx 等
│ │ └── validatorFac.js # createSchemaValidator / validatorFac
│ │
│ ├── form-builder/ # 例：Form 產生器（根據 Schema/ValueSpec 出 UI Schema）
│ │ ├── formSchemaMapper.js
│ │ └── widgetHints.js
│ │
│ ├── api-docs/ # 例：API 文件 / OpenAPI 生成器
│ │ └── openapiEmitter.js
│ │
│ ├── mock-data/ # 例：依 Schema 產生假資料
│ │ └── mockGenerator.js
│ │
│ └── storage-mapping/ # 例：DB mapping / index mapping 之類
│ └── columnMapper.js
│
└── index.js # 對外暴露的高階 API
# 例如：
# - createSchemaValidator
# - registerSemanticType
# - compileSchema
# - generateMockFromSchema
# - buildFormSchemaFromSchema
```
---
## Schema
### Schema Node
### ✔︎ Schema Use Cases
* **rule string in rule-based validation**
```
rules: "type:StrictNumber|gt:0|lt:100|default:10"
```
* **schema definition in API / I/O contract**
```
{
"amount": {
"type": "LooseNumber",
"constraints": ["int", "nonNegative", "max:10000"],
"modifier": "nullable"
}
}
```
* **UI schema generation**
```
{
"field": "birthDate",
"valueSpec": {
"type": "DateYMDString",
"constraints": ["required"]
},
"uiSchema": { "widget": "datePicker" }
}
```
* **model factory**
```
{
"id": {
"valueSpec": {
"type": "UUIDString",
"constraints": ["required"]
}
}
}
```
* **array / object value Semantic（新的、合法的 ValueSpec）**
```
{
"tags": {
"valueSpec": {
"type": "StrictArray",
"constraints": ["itemsType:NonEmptyString"],
"modifier": { "default": [] }
}
}
}
```
---
### Value Spec and Schema Relationship Diagrams（Mermaid）
```mermaid
flowchart LR
T["Semantic Types
（語意型別）"]
C["Constraint
（單值限制）"]
M["Modifier
（值存在性修飾）"]
VS["ValueSpec
（單欄位值的語意範圍）"]
SCH["Schema
（結構與欄位關係）"]
T --> VS
C --> VS
M --> VS
VS --> SCH
```
## 📌 Schema Engine Use Case
### 🗺 Semantic Engine Use Case Map
```mermaid
flowchart TD
ST["Semantic Types"] --> VS["ValueSpec"]
ST --> UC1["Validation"]
ST --> UC2["UI Schema"]
ST --> UC3["API Schema( OpenAPI / RPC )"]
ST --> UC4["I/O Contract"]
ST --> UC5["Documentation( Auto doc )"]
ST --> UC6["Code Generation"]
ST --> UC7["Data Transformation"]
ST --> UC8["Storage Schema( DB mapping )"]
ST --> UC9["Runtime Enforcement( Access / Policy )"]
VS --> UC1
VS --> UC2
VS --> UC3
VS --> UC5
VS --> UC6
VS --> UC8
```
**語意架構解讀**
```
Semantic Types = 值的語意單位（獨立存在）
ValueSpec = 在特定 use case 下，定義此值允許的語意空間
Use Cases = 消費 Semantic Types / ValueSpec 的場域
```
---
### 📌 Schema Engine Use Case List
| Use Case | 說明 |
|--------------------------------------------|-----------------------------------------------|
| **Validation** | 檢查輸入值是否符合 ValueSpec 定義（值域、格式、語意） |
| **UI Schema** | 依語意決定 UI 控件與呈現方式，例如 Date → 日期選擇器、Money → 金額格式 |
| **API Schema( OpenAPI / RPC )** | 將語意投射為跨系統傳遞格式與型別定義 |
| **I/O Contract** | 讓不同系統之間以一致語意交換資料，不依賴語言層型別 |
| **Documentation( Auto doc )** | 由語意與 ValueSpec 自動生成欄位文件、參數定義與說明欄位 |
| **Code Generation** | 依型別語意產生 DTO、欄位型別、語言映射程式碼 |
| **Data Transformation** | 數值或字串在語意一致下做安全轉換，例如 normalize、unit conversion |
| **Storage Schema( DB mapping )** | 將語意對應 DB 型別，如 MoneyNumber → DECIMAL(12,2) |
| **Runtime Enforcement( Access / Policy )** | 根據語意值控制行為，例如 maskedString、readonlyId |
### 🧩 Schema and Schema Validator
- PathSpecNode × Schema × ValueSpec × SchemaValidator 關係圖（Mermaid）
```mermaid
flowchart LR
Schema["Schema"]
VS["ValueSpec"]
PS["PathSpecNode"]
V["SchemaValidator"]
Schema -->|" uses ValueSpec per field "| VS
Schema -->|" compiled into many "| PS
VS -->|" embedded in "| PS
PS -->|" drives runtime validation "| V
```
---
### 生物類比：
| 生物實體 | 你的系統對應 | 說明 |
|-------------|----------------------------------------------------|------------------|
| 鹼基（A/T/G/C） | Semantic Types | 最小不可分語意單元 |
| DNA 片段 | ValueSpec | 單一欄位語意序列 |
| 基因 | **PathSpecNode** | Schema 中具語意的欄位節點 |
| 染色體 | Schema | 多欄位組合形成的語意結構 |
| 細胞核 | Use Case（Validator / Form Builder Runtime Context） | 染色體在其中發揮作用的環境 |
---