Skip to content

Commit d88b973

Browse files
committed
spec: Mermaid architecture diagram and MAT- prefix for MaterialDNA
- Replace ASCII diagram in 3.1 with Mermaid flowchart (Munich/Berlin/Vienna nodes) - MaterialDNA identifier format: add MAT- prefix (MAT-{COUNTRY}-{CITY}-...) - Update all MaterialDNA examples to use MAT- prefix Made-with: Cursor
1 parent c4a4afc commit d88b973

File tree

1 file changed

+31
-25
lines changed

1 file changed

+31
-25
lines changed

SPECIFICATION.md

Lines changed: 31 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -121,11 +121,16 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S
121121

122122
LOOP follows a federated architecture where each city operates an autonomous node. Nodes communicate using HTTPS and JSON-LD messages.
123123

124-
```bash
125-
126-
┌─────────────┐ ┌─────────────┐ │ Munich │◄────────┤ Berlin │ │ Node │ HTTPS │ Node │ └──────┬──────┘ └──────┬──────┘ │ │ │ ┌─────────────┐ │ └────┤ Vienna ├────┘ │ Node │ └─────────────┘
127-
124+
```mermaid
125+
flowchart LR
126+
Munich[Munich Node]
127+
Berlin[Berlin Node]
128+
Vienna[Vienna Node]
129+
Munich <-->|HTTPS| Berlin
130+
Munich --- Vienna
131+
Berlin --- Vienna
128132
```
133+
129134
### 3.2 Core Components
130135

131136
Each LOOP node MUST implement:
@@ -213,10 +218,11 @@ These extensions:
213218
MaterialDNA identifiers MUST follow this pattern:
214219

215220
```bash
216-
{COUNTRY}-{CITY}-{YEAR}-{CATEGORY}-{UNIQUE}
221+
MAT-{COUNTRY}-{CITY}-{YEAR}-{CATEGORY}-{UNIQUE}
217222
```
218223

219224
Where:
225+
- `MAT`: Fixed prefix identifying a material
220226
- `COUNTRY`: ISO 3166-1 alpha-2 code
221227
- `CITY`: Three-letter city code (locally defined)
222228
- `YEAR`: Four-digit year of registration
@@ -226,7 +232,7 @@ Where:
226232
Example:
227233

228234
```bash
229-
DE-MUC-2025-PLASTIC-B847F3
235+
MAT-DE-MUC-2025-PLASTIC-B847F3
230236
```
231237

232238
### 4.2 MaterialDNA Object
@@ -236,7 +242,7 @@ DE-MUC-2025-PLASTIC-B847F3
236242
"@context": "https://local-loop-io.github.io/projects/loop-protocol/contexts/loop-v0.1.1.jsonld",
237243
"@type": "MaterialDNA",
238244
"schema_version": "0.1.1",
239-
"id": "DE-MUC-2025-PLASTIC-B847F3",
245+
"id": "MAT-DE-MUC-2025-PLASTIC-B847F3",
240246
"category": "plastic-pet",
241247
"quantity": {
242248
"value": 1000,
@@ -340,7 +346,7 @@ This separation aligns with:
340346
```
341347
MaterialDNA (composition layer) ProductDNA (product layer, DPP-facing)
342348
├── category: plastic-hdpe ├── product_category: electronics-laptop
343-
├── quantity: 2kg ├── material_ids: [DE-MUC-2025-PLASTIC-..., ...]
349+
├── quantity: 2kg ├── material_ids: [MAT-DE-MUC-2025-PLASTIC-..., ...]
344350
├── origin_city: Munich ├── condition: good
345351
└── passport (DPP fields) ├── passport (DPP fields, ESPR-aligned)
346352
└── lifecycle_stage: in-use
@@ -390,8 +396,8 @@ PRD-DE-MUC-2025-DESK-F4A7B2
390396
"functional_status": "fully-functional",
391397
"lifecycle_stage": "end-of-first-use",
392398
"material_ids": [
393-
"DE-MUC-2025-METAL-4EB84C",
394-
"DE-MUC-2025-PLASTIC-96FE78"
399+
"MAT-DE-MUC-2025-METAL-4EB84C",
400+
"MAT-DE-MUC-2025-PLASTIC-96FE78"
395401
]
396402
}
397403
```
@@ -493,7 +499,7 @@ Each node's LoopCoin configuration:
493499
"to": "business:brewery@munich.loop",
494500
"amount": 50,
495501
"currency": "LC-MUC",
496-
"material_ref": "DE-MUC-2025-FOOD-B847F3",
502+
"material_ref": "MAT-DE-MUC-2025-FOOD-B847F3",
497503
"timestamp": "2025-05-27T14:30:00Z",
498504
"memo": "Payment for spent grain",
499505
"signature": "..."
@@ -703,7 +709,7 @@ Authorization: Bearer {token}
703709
{
704710
"@context": "https://local-loop-io.github.io/projects/loop-protocol/contexts/loop-v0.1.1.jsonld",
705711
"@type": "MaterialDNA",
706-
"id": "DE-MUC-2025-PLASTIC-B847F3",
712+
"id": "MAT-DE-MUC-2025-PLASTIC-B847F3",
707713
"category": "plastic-pet",
708714
"quantity": {"value": 1000, "unit": "kg"},
709715
...
@@ -713,7 +719,7 @@ Response: 201 Created
713719
{
714720
"@context": "https://local-loop-io.github.io/projects/loop-protocol/contexts/loop-v0.1.1.jsonld",
715721
"@type": "MaterialDNA",
716-
"id": "DE-MUC-2025-PLASTIC-B847F3",
722+
"id": "MAT-DE-MUC-2025-PLASTIC-B847F3",
717723
"status": "registered",
718724
...
719725
}
@@ -722,13 +728,13 @@ Response: 201 Created
722728
**GET /api/v1/material/{id}**
723729

724730
```http
725-
GET /api/v1/material/DE-MUC-2025-PLASTIC-B847F3
731+
GET /api/v1/material/MAT-DE-MUC-2025-PLASTIC-B847F3
726732
727733
Response: 200 OK
728734
{
729735
"@context": "https://local-loop-io.github.io/projects/loop-protocol/contexts/loop-v0.1.1.jsonld",
730736
"@type": "MaterialDNA",
731-
"id": "DE-MUC-2025-PLASTIC-B847F3",
737+
"id": "MAT-DE-MUC-2025-PLASTIC-B847F3",
732738
...
733739
}
734740
```
@@ -818,7 +824,7 @@ X-API-Key: {api-key}
818824
"@type": "MaterialStatusUpdate",
819825
"schema_version": "0.1.1",
820826
"id": "3c9a6a0b-8c1a-4d3f-9c2c-3c1c2f9d5c2a",
821-
"material_id": "DE-MUC-2025-PLASTIC-B847F3",
827+
"material_id": "MAT-DE-MUC-2025-PLASTIC-B847F3",
822828
"status": "reserved",
823829
"updated_at": "2025-06-03T09:15:00Z",
824830
"reason": "Reserved by city exchange",
@@ -891,7 +897,7 @@ Authorization: Bearer {token}
891897
"@context": "https://local-loop-io.github.io/projects/loop-protocol/contexts/loop-v0.1.1.jsonld",
892898
"@type": "MaterialTransaction",
893899
"id": "TXN-2025-05-27-001",
894-
"material": "DE-MUC-2025-PLASTIC-B847F3",
900+
"material": "MAT-DE-MUC-2025-PLASTIC-B847F3",
895901
"seller": "munich.loop",
896902
"buyer": "berlin.loop",
897903
"offer": {
@@ -925,7 +931,7 @@ X-Node-Signature: {signature}
925931
{
926932
"@context": "https://local-loop-io.github.io/projects/loop-protocol/contexts/loop-v0.1.1.jsonld",
927933
"@type": "MaterialAnnouncement",
928-
"material": "DE-MUC-2025-PLASTIC-B847F3",
934+
"material": "MAT-DE-MUC-2025-PLASTIC-B847F3",
929935
"origin": "munich.loop",
930936
"available": true
931937
}
@@ -940,7 +946,7 @@ X-Node-Signature: {signature}
940946
{
941947
"@context": "https://local-loop-io.github.io/projects/loop-protocol/contexts/loop-v0.1.1.jsonld",
942948
"@type": "MaterialOffer",
943-
"material": "DE-MUC-2025-PLASTIC-B847F3",
949+
"material": "MAT-DE-MUC-2025-PLASTIC-B847F3",
944950
"from": "berlin.loop",
945951
"base_price": 120,
946952
"loop_cost": 156,
@@ -956,9 +962,9 @@ Standard error format:
956962
{
957963
"error": {
958964
"code": "MATERIAL_NOT_FOUND",
959-
"message": "Material with ID DE-MUC-2025-PLASTIC-B847F3 not found",
965+
"message": "Material with ID MAT-DE-MUC-2025-PLASTIC-B847F3 not found",
960966
"details": {
961-
"searched_id": "DE-MUC-2025-PLASTIC-B847F3",
967+
"searched_id": "MAT-DE-MUC-2025-PLASTIC-B847F3",
962968
"timestamp": "2025-05-27T15:30:00Z"
963969
}
964970
}
@@ -1116,7 +1122,7 @@ POST munich.loop/api/v1/material
11161122
{
11171123
"@context": "https://local-loop-io.github.io/projects/loop-protocol/contexts/loop-v0.1.1.jsonld",
11181124
"@type": "MaterialDNA",
1119-
"id": "DE-MUC-2025-FOOD-B847F3",
1125+
"id": "MAT-DE-MUC-2025-FOOD-B847F3",
11201126
"category": "organic-food",
11211127
"quantity": {"value": 500, "unit": "kg"},
11221128
"quality": 0.90,
@@ -1133,7 +1139,7 @@ Response:
11331139
{
11341140
"@context": "https://local-loop-io.github.io/projects/loop-protocol/contexts/loop-v0.1.1.jsonld",
11351141
"@type": "MaterialDNA",
1136-
"id": "DE-MUC-2025-FOOD-B847F3",
1142+
"id": "MAT-DE-MUC-2025-FOOD-B847F3",
11371143
"status": "registered"
11381144
}
11391145
```
@@ -1145,7 +1151,7 @@ POST vienna.loop/api/v1/federate/announce
11451151
{
11461152
"@context": "https://local-loop-io.github.io/projects/loop-protocol/contexts/loop-v0.1.1.jsonld",
11471153
"@type": "MaterialAnnouncement",
1148-
"material": "DE-MUC-2025-FOOD-B847F3",
1154+
"material": "MAT-DE-MUC-2025-FOOD-B847F3",
11491155
"origin": "munich.loop",
11501156
"category": "organic-food",
11511157
"quantity": 500,
@@ -1170,7 +1176,7 @@ POST munich.loop/api/v1/federate/offer
11701176
{
11711177
"@context": "https://local-loop-io.github.io/projects/loop-protocol/contexts/loop-v0.1.1.jsonld",
11721178
"@type": "MaterialOffer",
1173-
"material": "DE-MUC-2025-FOOD-B847F3",
1179+
"material": "MAT-DE-MUC-2025-FOOD-B847F3",
11741180
"from": "vienna.loop",
11751181
"base_price": 60,
11761182
"loop_cost": 104,

0 commit comments

Comments
 (0)