feat: add regulatory compatibility roadmap (#13)

Author: alpha912

README.md

@@ -14,6 +14,7 @@ Local Optimization with Overflow Protocol. A federated circular economy concept
 - `schemas/`: JSON Schema definitions.
 - `examples/`: sample payloads for interop.
 - `contexts/`: JSON-LD contexts.
+- `docs/regulatory-alignment-roadmap.md`: long-horizon EU and German compatibility plan.
 - `rfcs/`: RFCs and design notes.
 
 ## Quickstart

SPECIFICATION.md

@@ -167,7 +167,9 @@ This subsection defines the smallest interoperable flow required for lab-only de
 
 #### Required entities
 
-All payloads MUST include `@context`, `@type`, and `schema_version` set to `0.1.1`.
+All payloads MUST include `@context`, `@type`, and `schema_version`.
+Emitters targeting the v0.1.1 baseline MUST set `schema_version` to `0.1.1`.
+Receivers SHOULD accept additive `0.1.x` patch-line versions when unknown fields can be preserved or ignored without data loss.
 
 - **MaterialDNA**  
   Schema: `https://local-loop-io.github.io/projects/loop-protocol/schemas/v0.1.1/material-dna.schema.json`
@@ -182,6 +184,16 @@ All payloads MUST include `@context`, `@type`, and `schema_version` set to `0.1.
 
 To remain GDPR-aligned for lab demos, payloads **MUST NOT** include personal data. Node identifiers, city names, and organization identifiers are permitted; emails, phone numbers, and names are not permitted in these entities.
 
+#### Additive compatibility extensions
+
+To improve forward compatibility with emerging regulatory data requirements, implementations MAY attach additive extension blocks such as `passport`, `classification`, and `traceability`.
+These extensions:
+
+- MUST remain optional in the v0.1.1 baseline
+- MUST NOT weaken the data-minimization rule above
+- SHOULD use the canonical JSON-LD context or explicit namespaced terms
+- SHOULD preserve unknown fields when relaying payloads between nodes
+
 ---
 
 ## 4. MaterialDNA Specification
@@ -785,7 +797,7 @@ Nodes maintain a registry of peers:
       "id": "munich.loop",
       "endpoint": "https://munich.loop/api/v1",
       "public_key": "-----BEGIN PUBLIC KEY-----...",
-      "capabilities": ["v0.1", "loopcoin", "loopsignal"],
+      "capabilities": ["interop-v0.1.1", "loopcoin", "loopsignal"],
       "location": {"lat": 48.1351, "lon": 11.5820},
       "status": "active",
       "last_seen": "2025-05-27T15:00:00Z"
@@ -1078,40 +1090,18 @@ Goal: Submit to standards body (W3C, IETF) after v1.0
 
 ## Appendix A: JSON-LD Context
 
-```json
-{
-  "@context": {
-    "@version": 1.1,
-    "loop": "https://local-loop-io.github.io/projects/loop-protocol/contexts/loop-v0.1.1.jsonld/",
-    "schema": "https://schema.org/",
-    "MaterialDNA": "loop:MaterialDNA",
-    "LoopCoin": "loop:LoopCoin",
-    "LoopSignal": "loop:LoopSignal",
-    "LoopCost": "loop:LoopCost",
-    "id": "@id",
-    "type": "@type",
-    "category": {
-      "@id": "loop:category",
-      "@type": "@id"
-    },
-    "quantity": "loop:quantity",
-    "value": "schema:value",
-    "unit": "schema:unitText",
-    "quality": "loop:quality",
-    "location": "schema:location",
-    "lat": "schema:latitude",
-    "lon": "schema:longitude",
-    "available_from": {
-      "@id": "schema:availabilityStarts",
-      "@type": "schema:DateTime"
-    },
-    "expires": {
-      "@id": "schema:availabilityEnds",
-      "@type": "schema:DateTime"
-    }
-  }
-}
-```
+The canonical JSON-LD context is published at:
+
+`https://local-loop-io.github.io/projects/loop-protocol/contexts/loop-v0.1.1.jsonld`
+
+Implementations MUST treat that file as the source of truth.
+This appendix is intentionally brief to avoid drift between the specification text and the published context file.
+
+Key properties of the canonical context:
+
+- It defines stable mappings for the published v0.1.1 fields
+- It sets `@vocab` to the LOOP terms namespace so additive fields expand predictably
+- It keeps date-time fields typed for interoperable processing
 
 ---
 

contexts/loop-v0.1.1.jsonld

@@ -1,11 +1,15 @@
 {
   "@context": {
     "@version": 1.1,
-    "loop": "https://local-loop-io.github.io/projects/loop-protocol/contexts/",
+    "@vocab": "https://local-loop-io.github.io/projects/loop-protocol/terms/",
+    "loop": "https://local-loop-io.github.io/projects/loop-protocol/terms/",
     "schema_version": "loop:schema_version",
     "node_id": "loop:node_id",
     "name": "loop:name",
-    "endpoint": "loop:endpoint",
+    "endpoint": {
+      "@id": "loop:endpoint",
+      "@type": "@id"
+    },
     "capabilities": "loop:capabilities",
     "timestamp": {
       "@id": "loop:timestamp",
@@ -17,22 +21,75 @@
     "Transfer": "loop:Transfer",
     "id": "@id",
     "category": "loop:category",
-    "quantity": {
-      "@id": "loop:quantity",
-      "@type": "@id"
-    },
+    "quantity": "loop:quantity",
     "value": "loop:value",
     "unit": "loop:unit",
+    "quality": "loop:quality",
     "origin_city": "loop:origin_city",
     "current_city": "loop:current_city",
+    "location": "loop:location",
+    "lat": "loop:lat",
+    "lon": "loop:lon",
+    "address": "loop:address",
     "available_from": {
       "@id": "loop:available_from",
       "@type": "http://www.w3.org/2001/XMLSchema#dateTime"
     },
+    "expires": {
+      "@id": "loop:expires",
+      "@type": "http://www.w3.org/2001/XMLSchema#dateTime"
+    },
     "available_until": {
       "@id": "loop:available_until",
       "@type": "http://www.w3.org/2001/XMLSchema#dateTime"
     },
+    "certifications": "loop:certifications",
+    "images": {
+      "@id": "loop:images",
+      "@type": "@id"
+    },
+    "metadata": "loop:metadata",
+    "source": "loop:source",
+    "batch_number": "loop:batch_number",
+    "notes": "loop:notes",
+    "passport": "loop:passport",
+    "passport_id": "loop:passport_id",
+    "passport_url": {
+      "@id": "loop:passport_url",
+      "@type": "@id"
+    },
+    "backup_copy_url": {
+      "@id": "loop:backup_copy_url",
+      "@type": "@id"
+    },
+    "passport_status": "loop:passport_status",
+    "data_carrier_id": "loop:data_carrier_id",
+    "issuer": "loop:issuer",
+    "access_scope": "loop:access_scope",
+    "supported_regimes": "loop:supported_regimes",
+    "classification": "loop:classification",
+    "ewc_code": "loop:ewc_code",
+    "hs_code": "loop:hs_code",
+    "cn_code": "loop:cn_code",
+    "battery_category": "loop:battery_category",
+    "traceability": "loop:traceability",
+    "batch_id": "loop:batch_id",
+    "serial_number": "loop:serial_number",
+    "lot_number": "loop:lot_number",
+    "source_operator_id": "loop:source_operator_id",
+    "facility_id": "loop:facility_id",
+    "retention_until": {
+      "@id": "loop:retention_until",
+      "@type": "http://www.w3.org/2001/XMLSchema#dateTime"
+    },
+    "document_refs": {
+      "@id": "loop:document_refs",
+      "@type": "@id"
+    },
+    "due_diligence_ref": "loop:due_diligence_ref",
+    "material_id": "loop:material_id",
+    "offer_id": "loop:offer_id",
+    "match_id": "loop:match_id",
     "from_city": "loop:from_city",
     "to_city": "loop:to_city",
     "status": "loop:status",
@@ -47,6 +104,14 @@
     "received_at": {
       "@id": "loop:received_at",
       "@type": "http://www.w3.org/2001/XMLSchema#dateTime"
-    }
+    },
+    "updated_at": {
+      "@id": "loop:updated_at",
+      "@type": "http://www.w3.org/2001/XMLSchema#dateTime"
+    },
+    "reason": "loop:reason",
+    "source_node": "loop:source_node",
+    "route": "loop:route",
+    "mode": "loop:mode"
   }
 }

docs/implementation-guide.md

@@ -1,6 +1,6 @@
 # Implementation Guide
 
-This guide summarizes the minimum steps to build a compliant LOOP node. For normative requirements, follow `SPECIFICATION.md`.
+This guide summarizes the minimum steps to build a compatibility-oriented LOOP lab node. For normative requirements, follow `SPECIFICATION.md`.
 
 ## Minimum viable node
 - HTTPS server with TLS 1.3+ and valid certificates.

docs/regulatory-alignment-roadmap.md

@@ -0,0 +1,111 @@
+# Regulatory Alignment Roadmap
+
+LocalLoop remains a lab-demo project with no public pilots or production deployments.
+This roadmap is a compatibility plan, not a certification claim and not legal advice.
+
+## Why this roadmap exists
+
+The LOOP Protocol now needs to stay additive and interoperable as EU product, packaging, battery, and waste-traceability rules become more digital.
+The immediate goal is to make v0.1.1 payloads easier to extend without breaking existing lab integrations.
+
+## Current baseline
+
+- `v0.1.1` remains the emitter baseline for minimal interop payloads.
+- Receivers should accept additive `0.1.x` patch releases when they can preserve or safely ignore unknown fields.
+- Minimal interop payloads must stay free of personal contact data.
+- Passport, classification, and traceability blocks are optional extension points, not required fields.
+
+## Regulatory signals to track
+
+### EU ESPR and Digital Product Passport
+
+- Regulation (EU) 2024/1781 entered into force on July 18, 2024.
+- The regulation establishes the Digital Product Passport framework and requires delegated acts to define product-specific rules.
+- The first ESPR Working Plan for 2025-2030 prioritizes product groups including textiles, furniture, tyres, mattresses, iron and steel, and aluminium.
+- Implication for LocalLoop:
+  use additive passport identifiers, access-scope metadata, classification hints, and stable traceability references without hard-coding product-specific delegated-act fields too early.
+
+### EU Batteries Regulation
+
+- Regulation (EU) 2023/1542 entered into force on August 17, 2023.
+- Digital battery passport obligations start applying from February 18, 2027 for light means of transport, industrial batteries above 2 kWh, and electric-vehicle batteries.
+- Implication for LocalLoop:
+  support passport IDs, battery category hints, due-diligence references, retention metadata, and role-based access boundaries.
+
+### EU Packaging and Packaging Waste Regulation
+
+- Regulation (EU) 2025/40 entered into force on February 11, 2025 and applies from August 12, 2026, with later phased obligations.
+- Reusable transport packaging and grouped packaging will increasingly rely on harmonized identification and data-carrier requirements.
+- Implication for LocalLoop:
+  preserve packaging identifiers, reusable-loop references, and document links without assuming a single passport format yet.
+
+### EU Waste Shipment and Traceability
+
+- Regulation (EU) 2024/1157 entered into force on May 20, 2024.
+- The move toward electronic documentation and stricter cross-border controls makes evidence references and retention windows more important.
+- Implication for LocalLoop:
+  keep document references, facility IDs, operator IDs, and retention dates attachable to material records and transfer events.
+
+### Germany National Circular Economy Strategy
+
+- Germany adopted the National Circular Economy Strategy in December 2024.
+- The strategy emphasizes digital product information, reuse, repair, municipal circularity, and better data availability across value chains.
+- Implication for LocalLoop:
+  keep municipal-node interoperability, reusable material identity, and digital passport alignment as first-class design goals.
+
+### GDPR and green claims governance
+
+- GDPR Article 5 requires personal data to be adequate, relevant, and limited to what is necessary.
+- Directive (EU) 2024/825 on empowering consumers for the green transition tightens how sustainability claims can be presented.
+- The Green Claims proposal remains in legislative process as of March 7, 2026.
+- Implication for LocalLoop:
+  do not present protocol metadata as proof of compliance or environmental performance unless the required evidence and verification model exists.
+
+## Delivery plan
+
+### Horizon 1: now to 90 days
+
+- Accept `application/ld+json` end-to-end in the backend.
+- Remove PII-bearing fields from minimal interop payloads.
+- Publish canonical versioned schema paths in the site mirror.
+- Expand the JSON-LD context so additive fields expand predictably.
+- Add sync and validation checks so protocol, backend copies, and site mirrors cannot silently drift.
+
+### Horizon 2: 3 to 12 months
+
+- Introduce profile-based extension guidance for battery, packaging, and waste-shipment use cases.
+- Model access scopes for public, operator, and regulator-visible passport data.
+- Add retention-policy and evidence-reference guidance for transfer and status events.
+- Map current LOOP categories to product and waste classifications without freezing product-specific delegated-act structures too early.
+
+### Horizon 3: 12 to 24 months
+
+- Add conformance tests for additive patch releases and profile-specific extensions.
+- Prototype adapter layers for battery passport and DPP service-provider integrations once implementing acts mature.
+- Add reusable packaging and municipal reuse scenarios to lab flows.
+
+### Horizon 4: 24 months and beyond
+
+- Track product-specific delegated acts and standards as they are adopted.
+- Promote stable extension profiles into normative schema modules only when rules are sufficiently concrete.
+- Add machine-readable evidence and verification models before making any compliance-facing product claims.
+
+## Design guardrails
+
+- Preserve backward compatibility by keeping the v0.1.1 baseline payloads valid.
+- Preserve forward compatibility by allowing additive patch-line versions and unknown extension fields.
+- Keep regulated or sensitive attributes optional until a delegated act or standard makes them precise enough to model safely.
+- Avoid embedding personal data in shared protocol payloads.
+- Separate interoperability readiness from legal compliance claims in every public-facing document.
+
+## Official sources
+
+- ESPR Regulation (EU) 2024/1781: https://eur-lex.europa.eu/eli/reg/2024/1781/oj/eng
+- ESPR Working Plan 2025-2030: https://environment.ec.europa.eu/publications/ecodesign-sustainable-products-and-energy-labelling-working-plan-2025-2030_en
+- Batteries Regulation (EU) 2023/1542: https://eur-lex.europa.eu/eli/reg/2023/1542/oj/eng
+- Packaging and Packaging Waste Regulation (EU) 2025/40: https://eur-lex.europa.eu/eli/reg/2025/40/oj/eng
+- Waste Shipment Regulation (EU) 2024/1157: https://eur-lex.europa.eu/eli/reg/2024/1157/oj/eng
+- Germany National Circular Economy Strategy: https://www.bmuv.de/en/topics/circular-economy/national-circular-economy-strategy
+- GDPR Regulation (EU) 2016/679: https://eur-lex.europa.eu/eli/reg/2016/679/oj/eng
+- Empowering Consumers for the Green Transition Directive (EU) 2024/825: https://eur-lex.europa.eu/eli/dir/2024/825/oj/eng
+- Green Claims proposal status page: https://eur-lex.europa.eu/legal-content/EN/HIS/?uri=CELEX:52023PC0166

examples/01-material-registration.json

@@ -25,10 +25,34 @@
   "images": [
     "https://example.com/material-photo.jpg"
   ],
-  "contact": {
-    "name": "Munich Recycling Center",
-    "email": "materials@munich.loop",
-    "phone": "+49-89-123456"
+  "passport": {
+    "passport_id": "DPP-DE-MUC-2025-B847F3",
+    "passport_url": "https://example.com/passports/DPP-DE-MUC-2025-B847F3",
+    "backup_copy_url": "https://example.com/passports/DPP-DE-MUC-2025-B847F3/backup",
+    "passport_status": "available",
+    "data_carrier_id": "urn:epc:id:sgtin:426001.123456.2025B847F3",
+    "issuer": "lab-hub.loop",
+    "access_scope": "role-based",
+    "supported_regimes": [
+      "espr-dpp",
+      "waste-shipment",
+      "nkws"
+    ]
+  },
+  "classification": {
+    "ewc_code": "15 01 02",
+    "hs_code": "391510",
+    "cn_code": "39151000"
+  },
+  "traceability": {
+    "batch_id": "2025-W22-01",
+    "source_operator_id": "munich-recycling-center",
+    "facility_id": "munich-sort-line-02",
+    "retention_until": "2030-06-03T10:00:00Z",
+    "document_refs": [
+      "https://example.com/documents/dispatch-note-2025-W22-01"
+    ],
+    "due_diligence_ref": "DD-2025-PLASTIC-0042"
   },
   "metadata": {
     "source": "consumer-collection",

schemas/match.schema.json

@@ -28,9 +28,13 @@
       "const": "Match"
     },
     "schema_version": {
-      "description": "Schema version for the minimal interop flow",
+      "description": "Schema version for the minimal interop flow. Emitters SHOULD use 0.1.1; receivers SHOULD accept additive 0.1.x patch releases.",
       "type": "string",
-      "const": "0.1.1"
+      "pattern": "^0\\.1\\.[1-9]\\d*$",
+      "examples": [
+        "0.1.1",
+        "0.1.2"
+      ]
     },
     "id": {
       "description": "Match identifier",