Skip to content

Commit 9344c30

Browse files
GsCommandGsCommand
authored
Update SCHEMAS.md
1 parent 632b468 commit 9344c30

1 file changed

Lines changed: 284 additions & 0 deletions

File tree

‎SCHEMAS.md‎

Lines changed: 284 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,285 @@
11

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

0 commit comments

Comments
 (0)