ewderna/Beyond-KLE
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

schema: IDX/ELCスキーマを確定した仕様に追従させる

Browse Source 
ELCをELCレイヤー.mdの保存形式で書き直した。microcontrollerとmatrixの列挙は
捨てたモデルなので削除し、提供者・端子・LEDチェーンに置き換え。参照先もIDXからPHYへ。
IDXからはrow/colとラベルを外し、キーIDとキー番号の対応だけにした。
PHYはcompatibilityブロックを、キー側と同じ形のファイル単位kleCompatibilityに置換。
clusterのnameは保存形式に無いため必須から外した。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
ewderna
2026-09-20 21:56:32 +09:00
co-authored by Claude Opus 5
parent 8c47e547b4
commit d858361586
1 changed files with 156 additions and 78 deletions
Download Patch File Download Diff File Expand all files Collapse all files
phase1-json-schema.md
+156 -78
View File
@@ -2,11 +2,16 @@
## レイヤー間データフロー
```txt
PHY (物理配置)
├─→ ELC (電気配線)
└─→ IDX (キー識別)
└─→ MAP (キーマップ)
```
PHY (物理配置) → IDX (キー識別) → ELC (電気配線) + MAP (キーマップ)
↓ ↓
ファームウェア生成 VIA/Remap出力
```
ELCとIDXはどちらもPHYを参照する。ELCはIDXを参照しない。
ファームウェアやVIA/Remap向けの出力は、各レイヤーの情報を統合して生成する。
他レイヤーからキーや部品を指す参照には、PHYのノードIDを使う。
## 1. PHYレイヤー JSON Schema
@@ -38,23 +43,10 @@ PHY (物理配置) → IDX (キー識別) → ELC (電気配線) + MAP (キー
"modified": { "type": "string", "format": "date-time" }
}
},
"compatibility": {
"kleCompatibility": {
"type": "object",
"description": "Information for external tool compatibility",
"properties": {
"kleJson": {
"type": "object",
"properties": {
"source": { "type": "string" },
"checksum": { "type": "string" },
"preservedFields": { "type": "array", "items": { "type": "string" } }
}
},
"originalFormat": {
"type": "string",
"enum": ["kle", "via", "qmk", "native"]
}
}
"description": "File-level opaque KLE fields kept for round-trip output (switchMount, switchBrand, switchType, backcolor, radii, background, css). The owning layer is undecided; see P-6 in PHYレイヤー.md",
"additionalProperties": true
},
"profiles": {
"type": "array",
@@ -196,7 +188,7 @@ PHY (物理配置) → IDX (キー識別) → ELC (電気配線) + MAP (キー
},
"cluster": {
"type": "object",
"required": ["type", "id", "name", "transform", "children"],
"required": ["type", "id", "transform", "children"],
"properties": {
"type": {
"type": "string",
@@ -324,6 +316,10 @@ PHY (物理配置) → IDX (キー識別) → ELC (電気配線) + MAP (キー
## 2. IDXレイヤー JSON Schema
IDXが持つのは、PHYのキーとキー番号の対応だけとする [推測:P-1]。
マトリックス座標(row/col)とLEDの識別番号はここに置かない。どちらも配線で決まる情報で、
row/col はELCの配線から導く派生情報、LEDの番号はELCが正本を持つ。
### 基本構造
```json
@@ -331,7 +327,7 @@ PHY (物理配置) → IDX (キー識別) → ELC (電気配線) + MAP (キー
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://beyond-kle.org/schemas/idx-layer.json",
"title": "IDX Layer - Key Identification",
"description": "Mapping between physical keys and logical identifiers",
"description": "Mapping between PHY keys and key numbers",
"type": "object",
"required": ["version", "phyReference", "keyMap"],
"properties": {
@@ -354,26 +350,16 @@ PHY (物理配置) → IDX (キー識別) → ELC (電気配線) + MAP (キー
"$defs": {
"keyMapping": {
"type": "object",
"required": ["physicalId", "logicalId"],
"required": ["keyId", "index"],
"properties": {
"physicalId": {
"keyId": {
"type": "string",
"description": "Reference to PHY layer key ID"
},
"logicalId": {
"type": "object",
"required": ["index"],
"properties": {
"index": { "type": "integer", "minimum": 0 },
"matrix": {
"type": "object",
"properties": {
"row": { "type": "integer", "minimum": 0 },
"col": { "type": "integer", "minimum": 0 }
}
},
"label": { "type": "string" }
}
"index": {
"type": "integer",
"minimum": 0,
"description": "Key number"
}
}
}
@@ -383,19 +369,21 @@ PHY (物理配置) → IDX (キー識別) → ELC (電気配線) + MAP (キー
## 3. ELCレイヤー JSON Schema
各フィールドの意味は `ELCレイヤー.md` を正とする。
### 基本構造
```json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://beyond-kle.org/schemas/elc-layer.json",
"title": "ELC Layer - Electrical Configuration",
"description": "Electrical wiring and pin mapping",
"title": "ELC Layer - Electrical Wiring",
"description": "Wiring between provider pins and key terminals",
"type": "object",
"required": ["version", "idxReference", "microcontroller", "matrix"],
"required": ["version", "phyReference", "providers", "keys"],
"properties": {
"version": { "type": "string" },
"idxReference": {
"phyReference": {
"type": "object",
"required": ["source", "checksum"],
"properties": {
@@ -403,41 +391,124 @@ PHY (物理配置) → IDX (キー識別) → ELC (電気配線) + MAP (キー
"checksum": { "type": "string" }
}
},
"microcontroller": {
"providers": {
"type": "array",
"items": { "$ref": "#/$defs/provider" }
},
"keys": {
"type": "array",
"items": { "$ref": "#/$defs/keyWiring" }
},
"ledChains": {
"type": "array",
"items": { "$ref": "#/$defs/ledChain" }
}
},
"$defs": {
"pinRef": {
"type": "string",
"pattern": "^(VCC|GND|[^.]+\\.[^.]+)$",
"description": "\"<provider id>.<pin name>\", or the reserved power rails VCC / GND"
},
"provider": {
"oneOf": [
{ "$ref": "#/$defs/mcuProvider" },
{ "$ref": "#/$defs/analogMuxProvider" }
]
},
"mcuProvider": {
"type": "object",
"required": ["type", "pinMapping"],
"required": ["id", "kind", "part"],
"properties": {
"type": { "type": "string" },
"pinMapping": {
"id": { "type": "string" },
"kind": { "const": "mcu" },
"part": {
"type": "string",
"description": "Part number. Used to interpret pin names"
}
}
},
"analogMuxProvider": {
"type": "object",
"required": ["id", "kind", "channels", "select", "common"],
"properties": {
"id": { "type": "string" },
"kind": { "const": "analog-mux" },
"channels": {
"type": "integer",
"minimum": 1,
"description": "Number of logical pins provided. Pin names are \"0\"..\"channels-1\""
},
"select": {
"type": "array",
"items": { "$ref": "#/$defs/pinRef" },
"description": "Select pins, least significant bit first"
},
"common": { "$ref": "#/$defs/pinRef" },
"enable": { "$ref": "#/$defs/pinRef" }
}
},
"keyWiring": {
"oneOf": [
{ "$ref": "#/$defs/contactKey" },
{ "$ref": "#/$defs/analogKey" }
]
},
"contactKey": {
"type": "object",
"required": ["key", "detect", "terminals"],
"properties": {
"key": {
"type": "string",
"description": "Reference to PHY layer key ID"
},
"detect": { "const": "contact" },
"terminals": {
"type": "object",
"description": "Non-polar. a and b carry no ordering meaning",
"required": ["a", "b"],
"properties": {
"rows": {
"type": "array",
"items": { "type": "string" }
},
"cols": {
"type": "array",
"items": { "type": "string" }
}
"a": { "$ref": "#/$defs/pinRef" },
"b": { "$ref": "#/$defs/pinRef" }
}
},
"diode": {
"type": "string",
"enum": ["a-to-b", "b-to-a"],
"description": "Anode side comes first. Omitted means no diode"
}
}
},
"analogKey": {
"type": "object",
"required": ["key", "detect", "terminals"],
"properties": {
"key": {
"type": "string",
"description": "Reference to PHY layer key ID"
},
"detect": { "const": "analog" },
"terminals": {
"type": "object",
"required": ["out", "vcc", "gnd"],
"properties": {
"out": { "$ref": "#/$defs/pinRef" },
"vcc": { "$ref": "#/$defs/pinRef" },
"gnd": { "$ref": "#/$defs/pinRef" }
}
}
}
},
"matrix": {
"ledChain": {
"type": "object",
"required": ["type", "dimensions"],
"required": ["id", "data", "order"],
"properties": {
"type": {
"type": "string",
"enum": ["standard", "charlieplexing", "direct"]
},
"dimensions": {
"type": "object",
"required": ["rows", "cols"],
"properties": {
"rows": { "type": "integer", "minimum": 1 },
"cols": { "type": "integer", "minimum": 1 }
}
"id": { "type": "string" },
"data": { "$ref": "#/$defs/pinRef" },
"order": {
"type": "array",
"items": { "type": "string" },
"description": "PHY node IDs. The position in the array is the LED number"
}
}
}
@@ -505,25 +576,32 @@ PHY (物理配置) → IDX (キー識別) → ELC (電気配線) + MAP (キー
### PHY → IDX変換
1. PHYレイヤーから物理キーリストを取得
2. 各キーに論理IDを割り当て
3. マトリックス座標の自動生成（行列最適化）
1. PHYレイヤーからキーのリストを取得
2. 各キーにキー番号を割り当て
### IDX → ELC変換
### PHY → ELC変換
1. マトリックス次元を算出
2. ピン配置の最適化提案
3. 配線効率の検証
1. ピン提供者を置き、各提供者が消費する上位ピンを指定
2. 各キーの端子の接続先を指定
3. LEDチェーンの並びを指定
### IDX + ELC → MAP変換
### IDX + ELC + MAP → ファームウェア出力
1. キーインデックス配列の生成
2. デフォルトキーマップの提案
1. ELCの配線から、ターゲットが要求する row / col を割り当て
2. キー番号の配列とキーマップ配列の生成
3. VIA/QMK形式への出力
## 次のステップ
1. **TypeScriptでの型定義作成**
1. **型定義の作成**(言語は `implementation-plan.md` で選定)
2. **変換ロジックのプロトタイプ実装**
3. **テストケース（60%、Split等）での検証**
4. **既存KLE JSONからの変換機能**
## 未確認事項
### P-1 IDXがキー番号以外に持つものがあるか
- 位置づけ: 本文「2. IDXレイヤー JSON Schema」が前提にしている。IDXには仕様ドキュメントがなく、
決定済みの情報(row/col と LEDの番号はELC)から引き算した最小形として書いている
- 格上げ条件: IDXレイヤーの仕様をユーザーと決め、`IDXレイヤー.md` に書く