Skip to main content

DPP API Contract

DPP API Contract

Purpose​

This document defines the API contract for interacting with Digital Product Passports (DPPs)** for physical products**, using the PierrieCardin Polo Shirt as an illustrative example.
It standardizes how manufacturers, distributors, and retailers expose DPPs, and how consumers, regulators, or recyclers can retrieve them in a consistent, secure, and interoperable way.

API Design Principles​

  1. REST + JSON-LD First

    • All endpoints must return JSON-LD (application/ld+json).
    • Responses must conform to the DPP Core Schema for Physical Products.

  2. Versioned Endpoints

    • APIs must be versioned for backward compatibility.
    • Example: /api/v1/dpp/...

  3. Lite vs Full

    • The same schema is used, but payload depth differs:
      • lite=true → Inline sections only.
      • lite=false (default) → Inline + ByRef for detailed traceability.

  4. Stateless and Cacheable

    • All GET endpoints must be stateless.
    • Use HTTP caching headers (ETag, Cache-Control) for performance.

  5. Security & Integrity

    • Lite DPPs are typically public.
    • Full DPPs may require authenticated access (e.g., auditors, regulators).
    • All DPP payloads must be digitally signed and include content hashes for integrity.

Endpoints​

1. Get Product Passport​

Request


GET /api/v1/dpp/{productId}/{version}?lite={true|false}
Accept: application/ld+json

Response

{
  "type": "dpp:Passport",
  "subject": "urn:pierriecardin:product:pc-polo-green:v1.2.0",
  "issuer": "did:pierriecardin:manufacturing:europe",
  "issuedAt": "2025-10-04T10:00:00Z",
  "status": "Valid",
  "signature": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..."
}
  • Default: Full DPP (Inline + ByRef).
  • Query param lite=true returns Lite DPP only (flattened summary for quick viewing).

2. Get Product Passport Status​

Request

GET /api/v1/dpp/{productId}/{version}/status

Response

{
  "subject": "urn:pierriecardin:product:pc-polo-green:v1.2.0",
  "status": "Valid",
  "validFrom": "2025-01-01T00:00:00Z",
  "validTo": "2026-12-31T23:59:59Z",
  "supersededBy": null,
  "revokedAt": null
}
  • Enables retailers, regulators, and recyclers to verify if a DPP is active or expired.

3. Get Product Passport Artifact​

Request

GET /api/v1/dpp/{productId}/{version}/artifact/{artifactType}
Accept: application/json

Path Parameters

  • artifactType = one of: composition, supplychain, manufacture, certification, sustainability, repair.

Response Example (Composition Artifact)

{
  "uri": "/composition/pierriecardin/polo-green/v1.2.0.json",
  "hash": "sha256-AAA",
  "mediaType": "application/json",
  "size": 12890,
  "downloadUrl": "https://cdn.pierriecardin.com/dpp/polo-green/v1.2.0/composition.json"
}
  • Returns metadata and download location of detailed composition or material data.
  • The hash ensures the artifact’s immutability.

4. Search Passports​

Request

GET /api/v1/dpp/search?issuer={issuerDid}&status=Valid&keyword=polo

Response

[
  {
    "subject": "urn:pierriecardin:product:pc-polo-green:v1.2.0",
    "issuer": "did:pierriecardin:manufacturing:europe",
    "status": "Valid",
    "issuedAt": "2025-10-04T10:00:00Z",
    "litePreview": {
      "compositionInline": {
        "materials": [
          { "name": "Organic Cotton", "percentage": 95 },
          { "name": "Elastane", "percentage": 5 }
        ]
      },
      "certificationInline": {
        "labels": ["OEKO-TEX Standard 100", "GOTS Certified"]
      }
    }
  }
]
  • Enables consumers or inspectors to search across available product passports.
  • Returns Lite previews for browsing efficiency.

Response Fields (Core)​

Every DPP response must include the following top-level fields:

  • type → always "dpp:Passport".
  • subject → Product identifier (URN).
  • issuer → Manufacturer or supply chain actor.
  • issuedAt → Timestamp (ISO 8601).
  • status → Valid | Revoked | Superseded.
  • contentHash → Hash of the full payload.
  • signature → Digital signature (JWS or W3C Verifiable Credential).

Errors​

Common API error responses:

  • 400 Bad Request → Invalid parameters.
  • 401 Unauthorized → Missing credentials for Full DPP.
  • 403 Forbidden → Insufficient access rights.
  • 404 Not Found → No DPP found for this model/version.
  • 410 Gone → Product discontinued or passport revoked.
  • 500 Internal Server Error → Server failure.

Example: Full DPP API Response​

{
  "type": "dpp:Passport",
  "subject": "urn:pierriecardin:product:pc-polo-green:v1.2.0",
  "issuer": "did:pierriecardin:manufacturing:europe",
  "issuedAt": "2025-10-04T10:00:00Z",
  "status": "Valid",
  "contentHash": "sha256-XYZ",
  "signature": "REPLACE",

  "compositionInline": {
    "materials": [
      { "name": "Organic Cotton", "percentage": 95 },
      { "name": "Elastane", "percentage": 5 }
    ],
    "dyeProcess": "Low-impact reactive dye (EU Compliant)"
  },
  "compositionByRef": {
    "uri": "/composition/pierriecardin/polo-green/v1.2.0.json",
    "hash": "sha256-AAA",
    "mediaType": "application/json",
    "size": 12890
  },
  "supplychainByRef": {
    "uri": "/supplychain/pierriecardin/polo-green/v1.2.0.ttl",
    "hash": "sha256-BBB",
    "mediaType": "text/turtle",
    "size": 52012
  },
  "certificationInline": {
    "labels": ["OEKO-TEX Standard 100", "GOTS Certified"],
    "lastAuditDate": "2025-06-15"
  },
  "sustainabilityInline": {
    "carbonFootprintKgCO2e": 2.3,
    "waterUsageLitres": 95,
    "energySource": "Solar + Hydro mix"
  }
}

Summary​

  • Lite DPP = Flattened summary of composition, certifications, and sustainability.
  • Full DPP = Inline + ByRef data for supply chain, provenance, and material traceability.
  • API contract provides a single, standard way for all participants — from manufacturers to regulators — to access trusted, verifiable information.
  • Security & lifecycle are mandatory: every passport must be signed, versioned, and revocable.

✅ PierrieCardin Example Recap

ConceptExample Value
ProductPierrieCardin Polo Shirt – Green, Size M
Product IDurn:pierriecardin:product:pc-polo-green:v1.2.0
Issuerdid:pierriecardin:manufacturing:europe
Passport TypeDPP – Physical Goods
AccessPublic (Lite), Authorized (Full)
Primary ArtifactsComposition, Supply Chain, Certification, Sustainability

To Conclude​

This API contract ensures that every PierrieCardin Polo Shirt model (and, by extension, any physical product) can provide an authenticated, machine-readable Digital Product Passport, enabling transparent traceability, sustainability validation, and consumer trust.


---