feat: add ProductDNA schema — DPP-aligned product-level entity

Introduces ProductDNA as a higher-level entity for product reuse flows,
aligned with EU ESPR Art. 9-10 and UNTP ProductPassport. Updates Offer,
Match, and Transfer schemas to accept either material_id or product_id
via JSON Schema anyOf. Adds JSON-LD context terms, OpenAPI endpoints,
specification section 4.5, and two new validated examples.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: alpha912

SPECIFICATION.md

@@ -16,6 +16,7 @@
 3. [Protocol Overview](#3-protocol-overview)
 3.5. [Minimal Interop Flow v0.1.1](#35-minimal-interop-flow-v011)
 4. [MaterialDNA Specification](#4-materialdna-specification)
+4.5. [ProductDNA Specification](#45-productdna-specification)
 5. [LoopCoin Specification](#5-loopcoin-specification)
 6. [LoopSignal Specification](#6-loopsignal-specification)
 7. [LoopCost Calculation](#7-loopcost-calculation)
@@ -95,6 +96,8 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S
 
 **MaterialDNA**: Globally unique identifier for any material item or batch
 
+**ProductDNA**: Globally unique identifier for a product or product batch, referencing constituent MaterialDNA entries
+
 **LoopCoin (LC)**: Local digital currency with expiry properties
 
 **LoopSignal**: Community-expressed preference percentage for material categories
@@ -174,6 +177,8 @@ Payloads using `schema_version: "0.1.1"` remain valid against v0.2.0 schemas (ba
 
 - **MaterialDNA**
   Schema: `https://local-loop-io.github.io/projects/loop-protocol/schemas/v0.2.0/material-dna.schema.json`
+- **ProductDNA**
+  Schema: `https://local-loop-io.github.io/projects/loop-protocol/schemas/v0.2.0/product-dna.schema.json`
 - **Offer**
   Schema: `https://local-loop-io.github.io/projects/loop-protocol/schemas/v0.2.0/offer.schema.json`
 - **Match**
@@ -317,6 +322,141 @@ electronics/
 
 ---
 
+## 4.5 ProductDNA Specification
+
+### 4.5.1 Overview
+
+ProductDNA represents the **product layer** in LOOP's two-tier hierarchy: materials compose products. While MaterialDNA tracks raw or processed materials (e.g., plastic-hdpe, metal-copper), ProductDNA tracks finished or semi-finished products (e.g., office desks, laptops) that contain those materials.
+
+This separation aligns with:
+- **EU ESPR (Art. 9-10)**: Digital Product Passports are defined at the product level
+- **UNTP ProductPassport**: Materials are nested inside product passports
+- **GS1/EPCIS**: Trade items (products) are the primary tracking unit
+
+### 4.5.2 Hierarchy
+
+```
+MaterialDNA (composition layer)     ProductDNA (product layer, DPP-facing)
+  ├── category: plastic-hdpe          ├── product_category: electronics-laptop
+  ├── quantity: 2kg                   ├── material_ids: [DE-MUC-2025-PLASTIC-..., ...]
+  ├── origin_city: Munich             ├── condition: good
+  └── passport (DPP fields)          ├── passport (DPP fields, ESPR-aligned)
+                                      └── lifecycle_stage: in-use
+```
+
+A ProductDNA entry MAY reference zero or more MaterialDNA entries via `material_ids`. This composition link enables traceability from product to constituent materials.
+
+### 4.5.3 Identifier Format
+
+ProductDNA identifiers MUST follow this pattern:
+
+```bash
+PRD-{COUNTRY}-{CITY}-{YEAR}-{CATEGORY}-{UNIQUE}
+```
+
+Where:
+- `PRD`: Fixed prefix identifying a product
+- `COUNTRY`: ISO 3166-1 alpha-2 code
+- `CITY`: Three-letter city code
+- `YEAR`: Four-digit year of registration
+- `CATEGORY`: Product category keyword
+- `UNIQUE`: Alphanumeric unique identifier (min 6 characters)
+
+Example:
+```bash
+PRD-DE-MUC-2025-DESK-F4A7B2
+```
+
+### 4.5.4 ProductDNA Object
+
+```json
+{
+  "@context": "https://local-loop-io.github.io/projects/loop-protocol/contexts/loop-v0.2.0.jsonld",
+  "@type": "ProductDNA",
+  "schema_version": "0.2.0",
+  "id": "PRD-DE-MUC-2025-DESK-F4A7B2",
+  "product_category": "furniture-office",
+  "name": "Standing Desk — Ergotron WorkFit",
+  "condition": "good",
+  "quantity": { "value": 12, "unit": "piece" },
+  "origin_city": "Munich",
+  "current_city": "Munich",
+  "available_from": "2026-03-15T08:00:00Z",
+  "manufacturer": "Ergotron",
+  "model": "WorkFit-S",
+  "manufacture_year": 2021,
+  "functional_status": "fully-functional",
+  "lifecycle_stage": "end-of-first-use",
+  "material_ids": [
+    "DE-MUC-2025-METAL-4EB84C",
+    "DE-MUC-2025-PLASTIC-96FE78"
+  ]
+}
+```
+
+### 4.5.5 Required Fields
+
+- `schema_version`: Schema version (0.2.0)
+- `id`: Unique ProductDNA identifier (PRD- prefix)
+- `product_category`: Standardized product category
+- `name`: Product name (2-200 characters)
+- `condition`: Physical condition (new, like-new, good, fair, poor, for-parts)
+- `quantity`: Amount and unit
+- `origin_city`: Registering city
+- `current_city`: Current custodian city
+- `available_from`: When product becomes available
+
+### 4.5.6 Product Categories
+
+```
+furniture/
+  furniture-office        # Office furniture
+  furniture-residential   # Residential furniture
+  furniture-industrial    # Industrial furniture
+
+building/
+  building-structural     # Structural building components
+  building-fixture        # Fixtures and fittings
+  building-hvac           # HVAC equipment
+  building-electrical     # Electrical installations
+
+electronics/
+  electronics-computing   # Computers and peripherals
+  electronics-mobile      # Mobile devices
+  electronics-appliance   # Household appliances
+  electronics-components  # Electronic components
+
+textiles/
+  textile-garment         # Garments and clothing
+  textile-industrial      # Industrial textiles
+
+packaging/
+  packaging-reusable      # Reusable packaging
+
+vehicles/
+  vehicle-parts           # Vehicle parts and components
+
+equipment/
+  equipment-industrial    # Industrial equipment
+  equipment-medical       # Medical equipment
+```
+
+### 4.5.7 Offer/Match/Transfer with Products
+
+The Offer, Match, and Transfer schemas accept either `material_id` or `product_id`. At least one MUST be present. This allows the same lifecycle flow (Offer → Match → Transfer) to work for both materials and products.
+
+```json
+{
+  "@type": "Offer",
+  "product_id": "PRD-DE-MUC-2025-DESK-F4A7B2",
+  "from_city": "Munich",
+  "to_city": "Berlin",
+  ...
+}
+```
+
+---
+
 ## 5. LoopCoin Specification
 
 ### 5.1 Currency Properties
@@ -1058,6 +1198,8 @@ POST munich.loop/api/v1/federate/offer
 - Conformity claims model (UNTP-aligned)
 - EPCIS event references and W3C VC pointers in traceability blocks
 - Schema versioning policy (RFC-0003)
+- **ProductDNA schema** — product-level DPP entity referencing MaterialDNA composition
+- Offer/Match/Transfer schemas accept `product_id` as alternative to `material_id`
 
 ### 13.2 Future Features
 
@@ -1141,6 +1283,10 @@ Key properties of the v0.2.0 context:
 - Clarified dual license (MIT for code, CC BY-SA 4.0 for prose)
 - Established schema versioning policy (RFC-0003)
 - Backend API paths aligned to `/api/v1/`
+- Added ProductDNA schema (product-level DPP entity, ESPR Art. 9-10 aligned)
+- Offer/Match/Transfer schemas now accept `product_id` as alternative to `material_id` (anyOf)
+- Added product category enum (17 categories across furniture, building, electronics, textile, packaging, vehicle, equipment)
+- Added ProductDNA term mappings to JSON-LD context
 
 ### Version 0.1.1 (2025-12-20)
 

contexts/loop-v0.2.0.jsonld

@@ -18,6 +18,7 @@
     },
 
     "MaterialDNA": "loop:MaterialDNA",
+    "ProductDNA": "loop:ProductDNA",
     "Offer": "loop:Offer",
     "Match": "loop:Match",
     "Transfer": "loop:Transfer",
@@ -202,6 +203,27 @@
     "temperature_c": "loop:temperature_c",
     "humidity_percent": "loop:humidity_percent",
 
+    "product_id": "loop:product_id",
+    "product_category": "loop:product_category",
+    "condition": "loop:condition",
+    "manufacturer": "loop:manufacturer",
+    "model": "loop:model",
+    "manufacture_year": "loop:manufacture_year",
+    "functional_status": "loop:functional_status",
+    "lifecycle_stage": "loop:lifecycle_stage",
+    "material_ids": "loop:material_ids",
+    "dimensions": "loop:dimensions",
+    "length_cm": "loop:length_cm",
+    "width_cm": "loop:width_cm",
+    "height_cm": "loop:height_cm",
+    "weight_kg": "loop:weight_kg",
+    "reuse_potential": "loop:reuse_potential",
+    "issued_at": {
+      "@id": "loop:issued_at",
+      "@type": "http://www.w3.org/2001/XMLSchema#dateTime"
+    },
+    "issuer_node": "loop:issuer_node",
+
     "material_id": "loop:material_id",
     "offer_id": "loop:offer_id",
     "match_id": "loop:match_id",

examples/14-product-reuse-registration.json

@@ -0,0 +1,36 @@
+{
+  "@context": "https://local-loop-io.github.io/projects/loop-protocol/contexts/loop-v0.2.0.jsonld",
+  "@type": "ProductDNA",
+  "schema_version": "0.2.0",
+  "id": "PRD-DE-MUC-2025-DESK-F4A7B2",
+  "product_category": "furniture-office",
+  "name": "Standing Desk — Ergotron WorkFit",
+  "condition": "good",
+  "quantity": { "value": 12, "unit": "piece" },
+  "origin_city": "Munich",
+  "current_city": "Munich",
+  "available_from": "2026-03-15T08:00:00Z",
+  "manufacturer": "Ergotron",
+  "model": "WorkFit-S",
+  "manufacture_year": 2021,
+  "functional_status": "fully-functional",
+  "lifecycle_stage": "end-of-first-use",
+  "material_ids": [
+    "DE-MUC-2025-METAL-4EB84C",
+    "DE-MUC-2025-PLASTIC-96FE78"
+  ],
+  "dimensions": {
+    "length_cm": 120,
+    "width_cm": 60,
+    "height_cm": 130,
+    "weight_kg": 18.5
+  },
+  "reuse_potential": "Fully functional standing desks from office clearance. Minor cosmetic wear.",
+  "passport": {
+    "passport_id": "PP-PRD-2026-F4A7B2",
+    "issued_at": "2026-03-10T10:00:00Z",
+    "issuer_node": "munich.loop",
+    "repair_score": 8,
+    "durability_score": 9
+  }
+}

examples/15-product-offer-flow.json

@@ -0,0 +1,43 @@
+[
+  {
+    "@context": "https://local-loop-io.github.io/projects/loop-protocol/contexts/loop-v0.2.0.jsonld",
+    "@type": "Offer",
+    "schema_version": "0.2.0",
+    "id": "OFR-PRD-8C4F2A1B",
+    "product_id": "PRD-DE-MUC-2025-DESK-F4A7B2",
+    "from_city": "Munich",
+    "to_city": "Berlin",
+    "quantity": { "value": 12, "unit": "piece" },
+    "status": "open",
+    "available_until": "2026-03-20T18:00:00Z",
+    "terms": "Pickup from Munich office building. Palletized and ready for transport."
+  },
+  {
+    "@context": "https://local-loop-io.github.io/projects/loop-protocol/contexts/loop-v0.2.0.jsonld",
+    "@type": "Match",
+    "schema_version": "0.2.0",
+    "id": "MCH-PRD-3D7E9F45",
+    "product_id": "PRD-DE-MUC-2025-DESK-F4A7B2",
+    "offer_id": "OFR-PRD-8C4F2A1B",
+    "from_city": "Munich",
+    "to_city": "Berlin",
+    "status": "accepted",
+    "matched_at": "2026-03-16T14:30:00Z"
+  },
+  {
+    "@context": "https://local-loop-io.github.io/projects/loop-protocol/contexts/loop-v0.2.0.jsonld",
+    "@type": "Transfer",
+    "schema_version": "0.2.0",
+    "id": "TRF-PRD-1A5B8C2D",
+    "product_id": "PRD-DE-MUC-2025-DESK-F4A7B2",
+    "match_id": "MCH-PRD-3D7E9F45",
+    "status": "completed",
+    "handoff_at": "2026-03-18T09:00:00Z",
+    "received_at": "2026-03-18T17:30:00Z",
+    "route": {
+      "from_city": "Munich",
+      "to_city": "Berlin",
+      "mode": "road"
+    }
+  }
+]

examples/README.md

@@ -15,6 +15,8 @@ This directory contains JSON examples that validate against the schemas in `sche
 - `11-handshake-response.json`: Node handshake response payload.
 - `12-material-dna-dpp-extensions.json`: MaterialDNA with comprehensive DPP passport fields (v0.2.0).
 - `13-conformity-claims.json`: MaterialDNA with multiple conformity claims (v0.2.0).
+- `14-product-reuse-registration.json`: ProductDNA registration for office furniture reuse (v0.2.0).
+- `15-product-offer-flow.json`: Complete Offer→Match→Transfer flow using product_id (v0.2.0).
 
 ## Validation
 Run `npm test` from the repository root to validate all examples.

openapi.json

@@ -18,6 +18,7 @@
   ],
   "tags": [
     { "name": "Material" },
+    { "name": "Product" },
     { "name": "Node" },
     { "name": "Signals" },
     { "name": "Transactions" },
@@ -34,6 +35,9 @@
       "MaterialDNA": {
         "$ref": "https://local-loop-io.github.io/projects/loop-protocol/schemas/v0.2.0/material-dna.schema.json"
       },
+      "ProductDNA": {
+        "$ref": "https://local-loop-io.github.io/projects/loop-protocol/schemas/v0.2.0/product-dna.schema.json"
+      },
       "Offer": {
         "$ref": "https://local-loop-io.github.io/projects/loop-protocol/schemas/v0.2.0/offer.schema.json"
       },
@@ -196,6 +200,51 @@
         }
       }
     },
+    "/product": {
+      "post": {
+        "tags": ["Product"],
+        "summary": "Register ProductDNA",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/ld+json": {
+              "schema": { "$ref": "#/components/schemas/ProductDNA" }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Created",
+            "content": {
+              "application/ld+json": {
+                "schema": { "$ref": "#/components/schemas/ProductDNA" }
+              }
+            }
+          },
+          "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
+        }
+      }
+    },
+    "/product/{id}": {
+      "get": {
+        "tags": ["Product"],
+        "summary": "Get ProductDNA by ID",
+        "parameters": [
+          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/ld+json": {
+                "schema": { "$ref": "#/components/schemas/ProductDNA" }
+              }
+            }
+          },
+          "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
+        }
+      }
+    },
     "/node/info": {
       "get": {
         "tags": ["Node"],

schemas/README.md

@@ -4,9 +4,10 @@ JSON Schema definitions for LOOP payloads.
 
 ## Files
 - `material-dna.schema.json` — Material identity and metadata (v0.2.0)
-- `offer.schema.json` — Offer payload definition (v0.2.0)
-- `match.schema.json` — Match payload definition (v0.2.0)
-- `transfer.schema.json` — Transfer payload definition (v0.2.0)
+- `product-dna.schema.json` — Product identity and metadata, DPP-aligned (v0.2.0)
+- `offer.schema.json` — Offer payload definition (v0.2.0, supports material_id or product_id)
+- `match.schema.json` — Match payload definition (v0.2.0, supports material_id or product_id)
+- `transfer.schema.json` — Transfer payload definition (v0.2.0, supports material_id or product_id)
 - `material-status.schema.json` — Material status updates (v0.2.0)
 - `handshake.schema.json` — Federation handshake protocol (v0.2.0)
 - `loopcoin.schema.json`