@bsv/dpp-profiles 0.3.0-beta.1

package/schemas/profile-manifest-v2.schema.json

@@ -0,0 +1,1087 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://bsv-blockchain.github.io/dpp/profiles/schemas/profile-manifest-v2.schema.json",
+  "title": "DPP industry profile manifest, version 2",
+  "description": "The canonical, immutable definition of one industry data profile under manifest version 2 (spec/profiles.md section 2, spec/passport-projections.md section 6). Everything version 1 declares survives unchanged; version 2 adds a requirement status per field (what asks for the value, and whether that is enacted, guidance, anticipated, under review or explicitly not to be displayed), a declarative applicability rule that composes category, jurisdiction, effective date and technical thresholds and can say unresolved, date precision, subject scope and override declarations per field, the shared evidence value types, and a succession record naming the version this one follows and the migration outcome of every changed field. Forms, validators, consumer documents and registry endpoints are generated from it and never edit it.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "manifestVersion",
+    "id",
+    "version",
+    "profile",
+    "kind",
+    "status",
+    "title",
+    "regulatoryLine",
+    "baseline",
+    "roles",
+    "applicability",
+    "schemaDialect",
+    "schemaUri",
+    "schemaDigest",
+    "restrictedSchemaUri",
+    "restrictedSchemaDigest",
+    "contextRefs",
+    "extends",
+    "stamps",
+    "fields",
+    "eventMappings",
+    "accessPolicyRef",
+    "accessTiers",
+    "sourceRefs",
+    "identity"
+  ],
+  "properties": {
+    "manifestVersion": {
+      "const": "2"
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$"
+    },
+    "version": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "profile": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*@[0-9]+$"
+    },
+    "kind": {
+      "const": "industry"
+    },
+    "status": {
+      "enum": [
+        "draft",
+        "current",
+        "superseded"
+      ]
+    },
+    "supersededBy": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*@[0-9]+$"
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1
+    },
+    "description": {
+      "type": "string"
+    },
+    "regulatoryLine": {
+      "type": "string",
+      "minLength": 1,
+      "description": "One sentence, aligned with and never compliant."
+    },
+    "baseline": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*@[0-9]+$"
+    },
+    "roles": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "enum": [
+          "passport-writer",
+          "attestation-issuer",
+          "registry",
+          "passport-reader"
+        ]
+      }
+    },
+    "applicability": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "categories",
+        "jurisdictions",
+        "statements"
+      ],
+      "properties": {
+        "categories": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/option"
+          }
+        },
+        "categoryKey": {
+          "type": "string",
+          "description": "The payload key that names the product category the applicability rules read."
+        },
+        "jurisdictions": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "statements": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "text",
+              "status"
+            ],
+            "properties": {
+              "text": {
+                "type": "string",
+                "minLength": 1
+              },
+              "status": {
+                "enum": [
+                  "enacted",
+                  "anticipated",
+                  "needs-review",
+                  "guidance"
+                ]
+              },
+              "source": {
+                "type": "string"
+              },
+              "effectiveDate": {
+                "type": "string",
+                "format": "date"
+              }
+            }
+          }
+        }
+      }
+    },
+    "schemaDialect": {
+      "const": "https://json-schema.org/draft/2020-12/schema"
+    },
+    "schemaUri": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The generated JSON Schema for the public payload."
+    },
+    "schemaDigest": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "restrictedSchemaUri": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The generated JSON Schema for the off-chain restricted tiers."
+    },
+    "restrictedSchemaDigest": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "contextRefs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "name",
+          "version",
+          "use"
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "version": {
+            "type": "string"
+          },
+          "repository": {
+            "type": "string"
+          },
+          "licence": {
+            "type": "string"
+          },
+          "retrieved": {
+            "type": "string",
+            "format": "date"
+          },
+          "urnPattern": {
+            "type": "string"
+          },
+          "use": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "extends": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "pattern": "^[a-z][a-z0-9-]*@[0-9]+$"
+    },
+    "stamps": {
+      "type": "array",
+      "description": "Reserved payload keys the platform writes and a consumer must not read as product data.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "key",
+          "description",
+          "valueType"
+        ],
+        "properties": {
+          "key": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string"
+          },
+          "valueType": {
+            "enum": [
+              "text",
+              "id",
+              "integer",
+              "enum"
+            ]
+          },
+          "const": {
+            "type": [
+              "string",
+              "integer"
+            ]
+          },
+          "codeList": {
+            "$ref": "#/$defs/codeList"
+          },
+          "pattern": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "fields": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/field"
+      }
+    },
+    "eventMappings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "nativeOperation",
+          "eventType",
+          "externalEvent",
+          "requires",
+          "withoutEvidence"
+        ],
+        "properties": {
+          "nativeOperation": {
+            "enum": [
+              "ACTIVATE",
+              "SOLD",
+              "RESOLD",
+              "REPAIRED",
+              "RECYCLED",
+              "EDIT",
+              "TRANSFER"
+            ]
+          },
+          "eventType": {
+            "enum": [
+              "Origin",
+              "Transfer",
+              "Transformation",
+              "Disposition"
+            ]
+          },
+          "externalEvent": {
+            "type": "string",
+            "description": "The external lifecycle semantics the operation may map to when its evidence condition holds."
+          },
+          "requires": {
+            "type": "string",
+            "description": "The evidence without which the mapping is not made."
+          },
+          "withoutEvidence": {
+            "enum": [
+              "insufficient-data",
+              "unsupported",
+              "transformed"
+            ]
+          }
+        }
+      }
+    },
+    "accessPolicyRef": {
+      "type": "string"
+    },
+    "accessTiers": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "description",
+          "storage"
+        ],
+        "properties": {
+          "id": {
+            "enum": [
+              "public",
+              "owner",
+              "legitimate",
+              "authority"
+            ]
+          },
+          "description": {
+            "type": "string"
+          },
+          "storage": {
+            "enum": [
+              "on-chain public payload",
+              "off-chain encrypted"
+            ]
+          }
+        }
+      }
+    },
+    "sourceRefs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "name",
+          "use"
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "reference": {
+            "type": "string"
+          },
+          "version": {
+            "type": "string"
+          },
+          "licence": {
+            "type": "string"
+          },
+          "licensedText": {
+            "type": "boolean",
+            "description": "True when the text is licensed and is cited by clause only, never reproduced."
+          },
+          "use": {
+            "type": "string"
+          },
+          "fields": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
+    "groups": {
+      "type": "array",
+      "description": "Presentation grouping, informative.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "title"
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "blurb": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "identity": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "passportIdentifier",
+        "granularities",
+        "parentRelations"
+      ],
+      "properties": {
+        "passportIdentifier": {
+          "type": "string",
+          "description": "How the enduring passport identifier is formed for this profile."
+        },
+        "granularities": {
+          "type": "array",
+          "items": {
+            "enum": [
+              "model",
+              "batch",
+              "item"
+            ]
+          }
+        },
+        "itemIdentifier": {
+          "type": "string",
+          "description": "The field key that identifies the one physical unit, when the profile declares one."
+        },
+        "modelIdentifier": {
+          "type": "string"
+        },
+        "batchIdentifier": {
+          "type": "string"
+        },
+        "parentRelations": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "child",
+              "parent"
+            ],
+            "properties": {
+              "child": {
+                "enum": [
+                  "item",
+                  "batch"
+                ]
+              },
+              "parent": {
+                "enum": [
+                  "model",
+                  "batch"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "succession": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "of",
+        "migration"
+      ],
+      "description": "The profile version this manifest succeeds and what became of every field whose meaning, type or key changed. A field not listed is unchanged. The old manifest is never edited; a reader of a state under the old version decodes it under the old version.",
+      "properties": {
+        "of": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*@[0-9]+$"
+        },
+        "migration": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "from",
+              "outcome",
+              "note"
+            ],
+            "properties": {
+              "from": {
+                "type": "string",
+                "minLength": 1,
+                "description": "The field key in the preceding version, or the new key for outcome new."
+              },
+              "to": {
+                "type": "string",
+                "minLength": 1
+              },
+              "outcome": {
+                "enum": [
+                  "unchanged",
+                  "renamed",
+                  "retyped",
+                  "split",
+                  "new",
+                  "withdrawn",
+                  "relabelled"
+                ]
+              },
+              "note": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "option": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "value",
+        "label"
+      ],
+      "properties": {
+        "value": {
+          "type": "string"
+        },
+        "label": {
+          "type": "string"
+        }
+      }
+    },
+    "codeList": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "closed",
+        "options"
+      ],
+      "properties": {
+        "closed": {
+          "type": "boolean",
+          "description": "True: a value outside the options is invalid. False: the list is what is known in practice and a value outside it is valid."
+        },
+        "options": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/option"
+          }
+        }
+      }
+    },
+    "valueType": {
+      "enum": [
+        "id",
+        "text",
+        "enum",
+        "multi",
+        "decimal",
+        "integer",
+        "percent",
+        "monthYear",
+        "date",
+        "url",
+        "document",
+        "graphic",
+        "country",
+        "record",
+        "any",
+        "measurement",
+        "certification",
+        "claimEvidence",
+        "localisedText",
+        "relatedDocument",
+        "warrantyTerms"
+      ]
+    },
+    "constraints": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "minimum": {
+          "type": "number"
+        },
+        "maximum": {
+          "type": "number"
+        },
+        "step": {
+          "type": "number"
+        },
+        "pattern": {
+          "type": "string"
+        },
+        "patternHint": {
+          "type": "string"
+        },
+        "maxLength": {
+          "type": "integer",
+          "minimum": 1
+        }
+      }
+    },
+    "part": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "key",
+        "label",
+        "valueType"
+      ],
+      "properties": {
+        "key": {
+          "type": "string"
+        },
+        "label": {
+          "type": "string"
+        },
+        "valueType": {
+          "enum": [
+            "text",
+            "decimal",
+            "percent",
+            "integer",
+            "enum",
+            "country"
+          ]
+        },
+        "unit": {
+          "type": "string"
+        },
+        "codeList": {
+          "$ref": "#/$defs/codeList"
+        },
+        "constraints": {
+          "$ref": "#/$defs/constraints"
+        },
+        "required": {
+          "type": "boolean"
+        }
+      }
+    },
+    "applicabilityRule": {
+      "description": "always: the field applies. category-in: it applies only to the named categories. needs-review: an obligation holds only under a condition a form cannot decide, stated in words, and is unresolved until a person decides. all and any compose rules; jurisdiction-in, effective and threshold are decidable from the context an evaluator is given; unresolved records that the primary source could not be established and is never satisfied. Unknown applicability cannot become a pass, and it does not prevent an adopter retaining incomplete draft data.",
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "rule"
+          ],
+          "properties": {
+            "rule": {
+              "const": "always"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "rule",
+            "categories"
+          ],
+          "properties": {
+            "rule": {
+              "const": "category-in"
+            },
+            "categories": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "rule",
+            "condition"
+          ],
+          "properties": {
+            "rule": {
+              "const": "needs-review"
+            },
+            "condition": {
+              "type": "string",
+              "minLength": 1
+            },
+            "categories": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "type": "string"
+              },
+              "description": "Narrows the categories the review concerns."
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "rule",
+            "rules"
+          ],
+          "properties": {
+            "rule": {
+              "enum": [
+                "all",
+                "any"
+              ]
+            },
+            "rules": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "$ref": "#/$defs/applicabilityRule"
+              }
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "rule",
+            "jurisdictions"
+          ],
+          "properties": {
+            "rule": {
+              "const": "jurisdiction-in"
+            },
+            "jurisdictions": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "rule"
+          ],
+          "properties": {
+            "rule": {
+              "const": "effective"
+            },
+            "from": {
+              "type": "string",
+              "format": "date"
+            },
+            "until": {
+              "type": "string",
+              "format": "date"
+            }
+          },
+          "minProperties": 2,
+          "description": "At least one of from and until, so the interval is never empty."
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "rule",
+            "field",
+            "operator",
+            "value"
+          ],
+          "properties": {
+            "rule": {
+              "const": "threshold"
+            },
+            "field": {
+              "type": "string",
+              "minLength": 1,
+              "description": "The payload key the threshold reads, for example a capacity in kWh."
+            },
+            "operator": {
+              "enum": [
+                "gt",
+                "gte",
+                "lt",
+                "lte",
+                "eq"
+              ]
+            },
+            "value": {
+              "type": "number"
+            },
+            "unit": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "rule",
+            "reason"
+          ],
+          "properties": {
+            "rule": {
+              "const": "unresolved"
+            },
+            "reason": {
+              "type": "string",
+              "minLength": 1
+            },
+            "source": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        }
+      ]
+    },
+    "field": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "key",
+        "pointer",
+        "label",
+        "valueType",
+        "cardinality",
+        "granularity",
+        "provenance",
+        "accessTier",
+        "obligation",
+        "legalBasis",
+        "applicability",
+        "requirement"
+      ],
+      "properties": {
+        "key": {
+          "type": "string",
+          "minLength": 1
+        },
+        "pointer": {
+          "type": "string",
+          "pattern": "^/"
+        },
+        "label": {
+          "type": "string"
+        },
+        "semanticUri": {
+          "type": "string"
+        },
+        "valueType": {
+          "$ref": "#/$defs/valueType"
+        },
+        "unit": {
+          "type": "string"
+        },
+        "codeList": {
+          "$ref": "#/$defs/codeList"
+        },
+        "constraints": {
+          "$ref": "#/$defs/constraints"
+        },
+        "cardinality": {
+          "enum": [
+            "one",
+            "many"
+          ]
+        },
+        "granularity": {
+          "enum": [
+            "model",
+            "batch",
+            "item"
+          ]
+        },
+        "provenance": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "capture"
+          ],
+          "properties": {
+            "capture": {
+              "enum": [
+                "form",
+                "brand",
+                "platform",
+                "event",
+                "derived",
+                "deferred"
+              ]
+            },
+            "dynamic": {
+              "type": "boolean"
+            },
+            "prose": {
+              "type": "boolean"
+            },
+            "onLabel": {
+              "type": "boolean"
+            },
+            "needsBms": {
+              "type": "boolean"
+            },
+            "kind": {
+              "enum": [
+                "fact",
+                "declaration",
+                "calculation",
+                "assessment"
+              ],
+              "description": "What the value is: a recorded fact, the maker's declaration, a calculated figure or a third party's assessment."
+            }
+          }
+        },
+        "accessTier": {
+          "enum": [
+            "public",
+            "owner",
+            "legitimate",
+            "authority"
+          ]
+        },
+        "obligation": {
+          "enum": [
+            "required",
+            "recommended",
+            "optional"
+          ]
+        },
+        "legalBasis": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The instrument that asks for the value, or the plain statement that none does. Separate from obligation."
+        },
+        "applicability": {
+          "$ref": "#/$defs/applicabilityRule"
+        },
+        "sourceRefs": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "source"
+            ],
+            "properties": {
+              "source": {
+                "type": "string"
+              },
+              "clause": {
+                "type": "string"
+              },
+              "name": {
+                "type": "string"
+              },
+              "property": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "awaitingAct": {
+          "type": "string"
+        },
+        "supersedes": {
+          "type": "string",
+          "description": "The previous version's key this field replaces."
+        },
+        "group": {
+          "type": "string"
+        },
+        "parts": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/part"
+          }
+        },
+        "note": {
+          "type": "string"
+        },
+        "requirement": {
+          "$ref": "#/$defs/requirement"
+        },
+        "precision": {
+          "enum": [
+            "day",
+            "month",
+            "year"
+          ],
+          "description": "For a date field: the precision the source supplies. A month is never turned into a day."
+        },
+        "scope": {
+          "enum": [
+            "model",
+            "batch",
+            "item",
+            "component"
+          ],
+          "description": "The subject the fact describes when finer than granularity allows, for example a component of an item."
+        },
+        "componentScoped": {
+          "type": "boolean",
+          "description": "True when the value is declared per component, and the payload carries one entry per component with its componentRef."
+        },
+        "overridable": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "at",
+            "policy"
+          ],
+          "description": "Whether a batch or item source may carry a value that takes precedence over the model's for this field, and under which named policy. Absent means a conflicting value at another granularity is a conflict, never an override.",
+          "properties": {
+            "at": {
+              "enum": [
+                "batch",
+                "item"
+              ]
+            },
+            "policy": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        }
+      }
+    },
+    "requirement": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "status",
+        "source"
+      ],
+      "description": "What asks for the value and how settled that is. enacted: an instrument in force names it. guidance: published guidance names it and no instrument settles its form. anticipated: an act not yet adopted or a later application date. needs-review: the primary source could not be confirmed. not-to-be-displayed: guidance says the value is not to be filled or displayed as of the effective date, for the reason stated; a consumer never shows it as required. This is separate from obligation, which is this profile's own requirement, and from legalBasis, which names the instrument in words. none: no instrument or guidance asks for the value; the field is the profile's own addition, and its obligation is the profile's alone.",
+      "properties": {
+        "status": {
+          "enum": [
+            "enacted",
+            "guidance",
+            "anticipated",
+            "needs-review",
+            "not-to-be-displayed",
+            "none"
+          ]
+        },
+        "source": {
+          "type": "string",
+          "minLength": 1
+        },
+        "clause": {
+          "type": "string"
+        },
+        "effectiveDate": {
+          "type": "string",
+          "format": "date"
+        },
+        "note": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}