@tracepass/dpp-schemas 0.1.0

package/schema.json

@@ -0,0 +1,519 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tracepass.eu/schema/dpp-template/v1.json",
+  "title": "DPP Category Template",
+  "description": "A machine-readable field specification for one Digital Product Passport product category under EU law. Each field carries its regulatory citation, datatype, validation rules, access level, and localized labels.",
+  "type": "object",
+  "required": [
+    "category",
+    "categoryLabel",
+    "version",
+    "isLatest",
+    "regulation",
+    "fields",
+    "fieldCount",
+    "requiredFieldCount",
+    "categories",
+    "createdBy"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "category": {
+      "type": "string",
+      "description": "Stable machine key for the product category.",
+      "examples": [
+        "battery",
+        "textile",
+        "steel"
+      ]
+    },
+    "categoryLabel": {
+      "$ref": "#/$defs/localizedString",
+      "description": "Human-readable category name, keyed by ISO 639-1 locale."
+    },
+    "version": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Template version. Increments when fields are added, removed, or their validation changes."
+    },
+    "isLatest": {
+      "type": "boolean",
+      "description": "True for the current version of this category."
+    },
+    "regulation": {
+      "type": "object",
+      "description": "The EU instrument that mandates this category's passport.",
+      "required": [
+        "name",
+        "number",
+        "effectiveDate",
+        "mandatoryDate"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "examples": [
+            "EU Battery Regulation"
+          ]
+        },
+        "number": {
+          "type": "string",
+          "examples": [
+            "(EU) 2023/1542",
+            "(EU) 2024/1781"
+          ]
+        },
+        "effectiveDate": {
+          "type": "string",
+          "format": "date",
+          "description": "ISO 8601 date (YYYY-MM-DD). A string, not a timestamp."
+        },
+        "mandatoryDate": {
+          "type": "string",
+          "format": "date",
+          "description": "ISO 8601 date (YYYY-MM-DD) from which the passport is legally required."
+        }
+      }
+    },
+    "fields": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/templateField"
+      }
+    },
+    "fieldCount": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Must equal fields.length."
+    },
+    "requiredFieldCount": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Must equal the count of fields whose validation.required is true."
+    },
+    "categories": {
+      "type": "array",
+      "description": "Field-group sections, in display order. Older templates store plain strings; newer ones store objects carrying localized headers.",
+      "items": {
+        "oneOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "object",
+            "required": [
+              "key"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "key": {
+                "type": "string"
+              },
+              "label": {
+                "$ref": "#/$defs/localizedString"
+              },
+              "fieldCount": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "sortOrder": {
+                "type": "integer"
+              }
+            }
+          }
+        ]
+      }
+    },
+    "createdBy": {
+      "type": "string"
+    },
+    "changelog": {
+      "type": "string"
+    },
+    "_note": {
+      "type": "string",
+      "description": "Free-text annotation for maintainers. Not consumed by any code."
+    }
+  },
+  "$defs": {
+    "localizedString": {
+      "type": "object",
+      "description": "Locale code to translated string, restricted to the 24 official EU languages. 'en' is always present; other locales are provided where translated.",
+      "required": [
+        "en"
+      ],
+      "propertyNames": {
+        "enum": [
+          "bg",
+          "cs",
+          "da",
+          "de",
+          "el",
+          "en",
+          "es",
+          "et",
+          "fi",
+          "fr",
+          "ga",
+          "hr",
+          "hu",
+          "it",
+          "lt",
+          "lv",
+          "mt",
+          "nl",
+          "pl",
+          "pt",
+          "ro",
+          "sk",
+          "sl",
+          "sv"
+        ]
+      },
+      "additionalProperties": {
+        "type": "string"
+      }
+    },
+    "templateField": {
+      "type": "object",
+      "required": [
+        "key",
+        "label",
+        "dataType",
+        "validation",
+        "category",
+        "categoryLabel",
+        "sortOrder",
+        "defaultAccessLevel"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "key": {
+          "type": "string",
+          "description": "Stable machine key, unique within the template.",
+          "examples": [
+            "batteryCapacity",
+            "carbonFootprint"
+          ]
+        },
+        "label": {
+          "$ref": "#/$defs/localizedString"
+        },
+        "description": {
+          "$ref": "#/$defs/localizedString"
+        },
+        "placeholder": {
+          "$ref": "#/$defs/localizedString"
+        },
+        "dataType": {
+          "type": "string",
+          "enum": [
+            "string",
+            "number",
+            "boolean",
+            "date",
+            "enum",
+            "multi_enum",
+            "array",
+            "object",
+            "url",
+            "file_reference"
+          ]
+        },
+        "unit": {
+          "description": "Unit of measure. Must be a canonical key from units.json — the historical free-text spellings are no longer permitted. `null` when the field has no unit.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "string",
+              "enum": [
+                "%",
+                "% P2O5",
+                "%/month",
+                "Ah",
+                "EUR/tCO2",
+                "GB",
+                "J",
+                "L",
+                "MJ",
+                "MPa",
+                "Mohs",
+                "N",
+                "N/kN",
+                "Ohm",
+                "TB",
+                "V",
+                "W",
+                "Wh/kg",
+                "ct",
+                "cycles",
+                "dB",
+                "dB(A)",
+                "g",
+                "g/L",
+                "g/cm³",
+                "gCO2/kWh",
+                "grade",
+                "hours",
+                "inches",
+                "kPa",
+                "kWh",
+                "kWh/t",
+                "kg",
+                "kg CFC-11 eq.",
+                "kg CO2e",
+                "kg CO2e/kWh",
+                "kg N eq.",
+                "kg NMVOC eq.",
+                "kg P eq.",
+                "kg Sb eq.",
+                "kg/24h",
+                "kg/m3",
+                "kgCO2e/kg",
+                "km",
+                "km/h",
+                "l eq",
+                "l/wash",
+                "m",
+                "m3 world eq.",
+                "mAh",
+                "mL",
+                "mPa·s",
+                "mPt",
+                "mg/kg",
+                "mg/kg per wash",
+                "mg/km",
+                "mg/m3",
+                "millesimal",
+                "minutes",
+                "mm",
+                "mol H+ eq.",
+                "mol N eq.",
+                "months",
+                "m²/L",
+                "points",
+                "ppm",
+                "rpm",
+                "tCO2/t",
+                "tCO2e/t",
+                "ug/cm2/week",
+                "ug/m3",
+                "weight_%",
+                "working days",
+                "years",
+                "°C"
+              ]
+            }
+          ]
+        },
+        "translatable": {
+          "type": "boolean",
+          "description": "Whether this field's value is free text that should be translated for multilingual passports."
+        },
+        "defaultValue": {
+          "description": "Any JSON value matching dataType, or null when the field has no default."
+        },
+        "enumOptions": {
+          "type": [
+            "array",
+            "null"
+          ],
+          "description": "Permitted values when dataType is 'enum' or 'multi_enum'. Explicitly null otherwise.",
+          "items": {
+            "type": "object",
+            "required": [
+              "value",
+              "label"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "value": {
+                "type": "string"
+              },
+              "label": {
+                "$ref": "#/$defs/localizedString"
+              }
+            }
+          }
+        },
+        "validation": {
+          "type": "object",
+          "description": "Constraints on the field's value, and whether the law requires it. `required` means an instrument IN FORCE compels the data; `anticipated` means a named future instrument is expected to. They are mutually exclusive.",
+          "required": [
+            "required"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "required": {
+              "type": "boolean"
+            },
+            "minLength": {
+              "type": [
+                "integer",
+                "null"
+              ],
+              "minimum": 0
+            },
+            "maxLength": {
+              "type": [
+                "integer",
+                "null"
+              ],
+              "minimum": 0
+            },
+            "min": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "max": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "pattern": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "description": "ECMAScript regular expression the value must match."
+            },
+            "anticipated": {
+              "type": "boolean",
+              "description": "A named future instrument is expected to require this data, and none in force does. Does not block publishing. Never set alongside `required: true`."
+            },
+            "anticipatedUnder": {
+              "type": "string",
+              "description": "CELEX id of the instrument expected to impose it, e.g. \"32024R1781\"."
+            },
+            "anticipatedNote": {
+              "type": "string",
+              "description": "Why it is expected — e.g. \"ESPR Annex I(p), pending a delegated act under Art. 4\"."
+            }
+          }
+        },
+        "category": {
+          "type": "string",
+          "description": "Field-group key this field belongs to. Matches an entry in the template's `categories`."
+        },
+        "categoryLabel": {
+          "$ref": "#/$defs/localizedString"
+        },
+        "sortOrder": {
+          "type": "integer"
+        },
+        "defaultAccessLevel": {
+          "type": "string",
+          "enum": [
+            "public",
+            "restricted",
+            "authority"
+          ],
+          "description": "Who may read this field by default. 'public' is visible to anyone scanning the QR code; 'restricted' requires a granted token; 'authority' is for market-surveillance bodies."
+        },
+        "regulationRef": {
+          "type": [
+            "object",
+            "null"
+          ],
+          "description": "Where this field's obligation comes from. `article` is the legacy unstructured form, retained until every template carries `instrument` + `provision` + `kind`.",
+          "additionalProperties": false,
+          "properties": {
+            "article": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "examples": [
+                "Art. 77"
+              ]
+            },
+            "annex": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "examples": [
+                "Annex XIII"
+              ]
+            },
+            "description": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "instrument": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "description": "CELEX id of the instrument, e.g. \"32023R1542\"."
+            },
+            "provision": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "description": "The provision within it, e.g. \"Art. 77(1)\"."
+            },
+            "kind": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "enum": [
+                "legislation",
+                "standard",
+                "scheme",
+                "national",
+                "international",
+                "specification",
+                null
+              ],
+              "description": "What kind of claim this reference is. `legislation` binds; `standard` supports a presumption of conformity but binds nothing; `scheme` is voluntary; `national` is one member state's law; `international` is a convention outside EU law; `specification` is not a reference at all."
+            },
+            "source": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "description": "Free-text name when the reference is not EU legislation."
+            }
+          }
+        },
+        "aiHints": {
+          "type": "object",
+          "description": "Hints for automated extraction of this field from unstructured supplier documents.",
+          "required": [
+            "alternateNames",
+            "extractionPriority"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "alternateNames": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Synonyms a datasheet might use for this field."
+            },
+            "expectedFormat": {
+              "type": "string"
+            },
+            "extractionPriority": {
+              "type": "integer",
+              "description": "Higher runs first when extraction budget is limited."
+            }
+          }
+        }
+      }
+    }
+  }
+}