Skip to content

Commit c4637e8

Browse files
GsCommandGsCommand
authored
Create SCHEMAS.md
1 parent e52df2e commit c4637e8

1 file changed

Lines changed: 318 additions & 0 deletions

File tree

‎SCHEMAS.md‎

Lines changed: 318 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,318 @@
1+
2+
# **SCHEMAS.md — CommandLayer Protocol Commons (v1.0.0)**
3+
4+
This document defines the full schema layout for the CommandLayer Protocol Commons, including canonical verbs, directory conventions, field-level rules, `$id` structures, versioning, and interoperability requirements for x402 + ERC‑8004 aligned agents.
5+
6+
---
7+
8+
# **1. Purpose**
9+
10+
The Protocol Commons provides the **canonical verb namespace** and the **universal schema layer** for all agents in the CommandLayer ecosystem.
11+
It establishes:
12+
13+
- A stable verb dictionary
14+
- Strict JSON Schema Draft 2020‑12 request + receipt contracts
15+
- Deterministic `$id` URLs
16+
- Standardized x402 envelope embedding
17+
- Trace + status primitives (`_shared`)
18+
- Canonical alias mappings (`aliases`)
19+
- Example-driven validation for CI + reproducibility
20+
21+
Once published under a versioned directory, the Commons is **immutable forever**.
22+
23+
---
24+
25+
# **2. Directory Layout**
26+
27+
```
28+
schemas/v1.0.0/
29+
_shared/ # trace, x402, receipt base primitives
30+
aliases/ # global + per-verb alias maps
31+
commons/ # 10 canonical verbs (requests + receipts)
32+
analyze/
33+
classify/
34+
fetch/
35+
format/
36+
generate/
37+
parse/
38+
query/
39+
save/
40+
summarize/
41+
translate/
42+
```
43+
44+
Each verb directory contains:
45+
46+
```
47+
requests/<verb>.request.schema.json
48+
receipts/<verb>.receipt.schema.json
49+
aliases/<verb>.aliases.json (optional but included in v1.0.0)
50+
```
51+
52+
---
53+
54+
# **3. Canonical Verb Set (v1.0.0)**
55+
56+
| Verb | Purpose |
57+
|-----------|-----------------------------------------------------|
58+
| analyze | ML / rules-based content inspection |
59+
| classify | Taxonomy classification |
60+
| fetch | External data retrieval |
61+
| format | Transform content without semantic mutation |
62+
| generate | Content generation (LLM, generative models) |
63+
| parse | Structural extraction & parsing |
64+
| query | Structured lookup or filtering |
65+
| save | Persist arbitrary content |
66+
| summarize | Semantic summarization |
67+
| translate | Language translation |
68+
69+
Each verb defines:
70+
71+
- 1 **request schema**
72+
- 1 **receipt schema**
73+
- 1 **alias map**
74+
75+
Aliases never override canonicals.
76+
77+
---
78+
79+
# **4. Schema `$id` Structure**
80+
81+
All schema IDs follow this deterministic pattern:
82+
83+
### **Request**
84+
```
85+
https://commandlayer.org/schemas/v1.0.0/commons/<verb>/requests/<verb>.request.schema.json
86+
```
87+
88+
### **Receipt**
89+
```
90+
https://commandlayer.org/schemas/v1.0.0/commons/<verb>/receipts/<verb>.receipt.schema.json
91+
```
92+
93+
### **Aliases**
94+
```
95+
https://commandlayer.org/schemas/v1.0.0/aliases/commons/<verb>.aliases.json
96+
```
97+
98+
### **Shared Primitives**
99+
```
100+
https://commandlayer.org/schemas/v1.0.0/_shared/x402.schema.json
101+
https://commandlayer.org/schemas/v1.0.0/_shared/trace.schema.json
102+
https://commandlayer.org/schemas/v1.0.0/_shared/receipt.base.schema.json
103+
```
104+
105+
---
106+
107+
# **5. x402 Embedding Rules**
108+
109+
Every **request** must include:
110+
111+
```
112+
"x402": {
113+
"verb": "<verb>",
114+
"version": "1.0.0"
115+
}
116+
```
117+
118+
Every **receipt** must include:
119+
120+
```
121+
"x402": {
122+
"verb": "<verb>",
123+
"version": "1.0.0",
124+
"status": "ok" | "error"
125+
}
126+
```
127+
128+
x402 object rules:
129+
130+
- No `additionalProperties`
131+
- Fully validated against `_shared/x402.schema.json`
132+
- Version string must match the verb directory version
133+
134+
---
135+
136+
# **6. Request & Receipt Contracts**
137+
138+
## **6.1 Request Contract**
139+
140+
All requests share this required structure:
141+
142+
| Field | Description |
143+
|-------------|-----------------------------------------|
144+
| `x402` | verb + version metadata |
145+
| `actor` | freeform string, ENS, or DID |
146+
| `trace` | deterministic trace primitive |
147+
| `input` | verb‑specific input object |
148+
| `limits` | optional time/size constraints |
149+
150+
**Generic Example**
151+
152+
```
153+
{
154+
"x402": { "verb": "fetch", "version": "1.0.0" },
155+
"actor": "example.eth",
156+
"trace": { "ts": 1234567890, "requestId": "..." },
157+
"input": { "url": "https://..." }
158+
}
159+
```
160+
161+
---
162+
163+
## **6.2 Receipt Contract**
164+
165+
All receipts enforce the CommandLayer status model:
166+
167+
### **Status Rules**
168+
169+
| status | required fields |
170+
|--------|----------------------|
171+
| `ok` | `result`, `error=null` |
172+
| `error` | `error`, `result=null` |
173+
174+
Receipt must include:
175+
176+
- `x402`
177+
- `trace`
178+
- `status`
179+
- conditional `result` or `error`
180+
181+
Strict if/then/else validation is defined in:
182+
183+
```
184+
_shared/receipt.base.schema.json
185+
```
186+
187+
---
188+
189+
# **7. Trace Primitive**
190+
191+
Used by *every* request and receipt.
192+
193+
Fields:
194+
195+
- `ts`
196+
- `requestId`
197+
- `idempotencyKey`
198+
- `nonce`
199+
- `requestHash`
200+
- Optional: `parentId`, `callbackUri`, `schemaId`, `signature`, `metrics`
201+
202+
Located in:
203+
204+
```
205+
_shared/trace.schema.json
206+
```
207+
208+
---
209+
210+
# **8. Aliases**
211+
212+
Aliases provide controlled synonyms for each verb.
213+
214+
Structure:
215+
216+
```
217+
{
218+
"aliases": ["<alt1>", "<alt2>"]
219+
}
220+
```
221+
222+
Located at:
223+
224+
```
225+
aliases/commons/<verb>.aliases.json
226+
```
227+
228+
Rules:
229+
230+
- Canonical verb always takes precedence
231+
- Aliases must be lowercase, single word
232+
- Aliases cannot collide with another canonical verb
233+
234+
---
235+
236+
# **9. Versioning Rules**
237+
238+
The Commons follows strict immutability:
239+
240+
- `v1.0.0/` **will never change** once published
241+
- Any modification requires:
242+
- New versioned directory (e.g., `v1.0.1/`)
243+
- New IPFS CID
244+
- New checksums
245+
- Updated ENS TXT
246+
- Updated provenance
247+
248+
NPM package: `@commandlayer/protocol-commons`
249+
ENS: `commandlayer.eth`
250+
251+
---
252+
253+
# **10. Validation Rules**
254+
255+
The Commons enforces **strict Ajv mode**:
256+
257+
```
258+
strict: true
259+
strictTypes: true
260+
allowUnionTypes: false
261+
strictTuples: true
262+
```
263+
264+
Other rules:
265+
266+
- No `additionalProperties` unless explicitly included
267+
- All examples must validate with CI
268+
- Receipt conditionals must pass if/then/else logic
269+
270+
Validation commands:
271+
272+
```
273+
npm run validate
274+
npm run validate:all
275+
npm run validate:examples
276+
```
277+
278+
---
279+
280+
# **11. Examples**
281+
282+
Examples live at:
283+
284+
```
285+
examples/v1.0.0/commons/<verb>/
286+
valid/*.json
287+
invalid/*.json
288+
```
289+
290+
Requirements:
291+
292+
- Minimum **3 valid** examples per verb
293+
- Minimum **3 invalid** examples per verb
294+
- All examples must pass strict CI validation
295+
296+
---
297+
298+
# **12. Provenance**
299+
300+
The entire schema tree is pinned to IPFS:
301+
302+
```
303+
304+
```
305+
306+
Integrity is tracked via:
307+
308+
```
309+
checksums.txt
310+
manifest.json (coming soon)
311+
```
312+
313+
---
314+
315+
# **13. Contact**
316+
317+
- Governance and Security: **dev@commandlayer.org**
318+
- PGP Fingerprint: `5016 D496 9F38 22B2 C5A2 FA40 99A2 6950 197D AB0A`

0 commit comments

Comments
 (0)