PRT001 - PartyRole Acceptance Gradient¶

Description¶

Validation info PRT001. Surfaces the acceptance gradient between the Pydantic-permissive 20-value PartyRoleEnum and the upstream JSON Schema's strict 6-value closed enum on $defs.PartyRole.properties.role. Fires when a payload uses one of the 14 wider values that the schema rejects.

The rule is informational by default — Phase 9 of the CIRPASS-2 migration kept the wider enum to preserve back-compat with v0.6 fixtures and information fidelity through the CIRPASS reverse shim (compat/cirpass_1_3_to_untp_0_7.py). Use ValidationEngine(strict_role_enum=True) to upgrade PRT001 from info to error when you want schema-strict enforcement.

Category¶

Party-Role Errors (acceptance gradient)

Severity¶

info (default) · error (when strict_role_enum=True)

Schema-strict 6 (accepted by JSON Schema validation)¶

owner, producer, manufacturer, processor, remanufacturer, recycler.

Pydantic-permissive 14 (accepted by `PartyRoleEnum`, rejected by schema)¶

operator, serviceProvider, inspector, certifier, logisticsProvider, carrier, consignor, consignee, importer, exporter, distributor, retailer, brandOwner, regulator.

Common Causes¶

A v0.6 fixture used a fine-grained role taxonomy that the v0.7 schema collapsed to the strict 6.
The CIRPASS reverse shim emitted a rich-mapping target (e.g. importer) that doesn't fit the schema's closed-6.
A pilot extension adopted the wider taxonomy informally.

How to Fix¶

Three options:

Accept the gap (default). The Pydantic model is permissive; the advisory rule is info-severity. Layer 1 schema validation is the authoritative check.
Remap to the schema-strict 6 using the suggested counterpart in the violation message (sourced from SUGGESTED_STRICT_REMAP in validators.rules.v0_7.party_role):

Text Only

importer        → manufacturer
distributor     → manufacturer
retailer        → owner
logisticsProvider → manufacturer
operator        → manufacturer
serviceProvider → processor
inspector       → processor
certifier       → processor
regulator       → processor
carrier         → manufacturer
consignor       → manufacturer
consignee       → owner
exporter        → manufacturer
brandOwner      → manufacturer

Opt into strict mode with ValidationEngine(strict_role_enum=True). PRT001 then fires as error and the validation result becomes valid=False.

Example¶

JSON

{
  "credentialSubject": {
    "relatedParty": [
      {
        "role": "importer",
        "party": {
          "id": "did:web:importer.example.com",
          "name": "Importer Inc."
        }
      }
    ]
  }
}

This fires PRT001 because "importer" is in the wider 20 but not in the strict 6. Suggested remap: "manufacturer".