trusted-issuer-registry/trusted-issuer.schema.json

Registry of trusted credential issuers

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Trusted Issuer Registry Entry",
  "type": "object",
  "required": ["issuer_id", "entity_type", "entity_metadata", "display", "certificates", "signature"],
  "properties": {
    "issuer_id": {
      "type": "string",
      "description": "DID or unique identifier for the issuer"
    },
    "entity_type": {
      "type": "string",
      "enum": [
        "government",
        "educational_institution",
        "commercial",
        "non_profit",
        "international_body",
        "federated_network",
        "other"
      ],
      "description": "The high-level category of the entity acting as the issuer"
    },
    "entity_metadata": {
      "type": "object",
      "description": "Metadata specific to the entity_type",
      "properties": {
        "country": {
          "type": "string",
          "description": "ISO 3166-1 alpha-2 country code (e.g., 'US', 'DE')"
        },
        "region": {
          "type": "string",
          "description": "State/province/region if relevant"
        },
        "government_level": {
          "type": "string",
          "enum": ["national", "state", "local", "other"],
          "description": "Applicable for entity_type=government"
        },
        "official_name": {
          "type": "string",
          "description": "Formal name of the government agency"
        },
        "institution_name": {
          "type": "string",
          "description": "Name of the educational institution"
        },
        "institution_type": {
          "type": "string",
          "enum": ["university", "college", "school", "training_provider", "other"],
          "description": "Applicable for entity_type=educational_institution"
        },
        "accreditation_body": {
          "type": "string",
          "description": "Name or ID of the accrediting authority"
        },
        "public_registry_url": {
          "type": "string",
          "format": "uri",
          "description": "URL to an official public registry or verification page for the entity"
        }
      },
      "additionalProperties": true
    },
    "display": {
      "type": "object",
      "required": ["name"],
      "properties": {
        "name": { "type": "string" },
        "logo": { "type": "string", "format": "uri" },
        "description": { "type": "string" }
      },
      "additionalProperties": false
    },
    "trust_lists": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": ["uv", "aamva_dts"]
      },
      "uniqueItems": true,
      "description": "The trust lists under which this issuer is recognized (e.g., uv, aamva_dts)"
    },
    "certificates": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["data", "format", "trust_lists"],
        "properties": {
          "data": {
            "type": "string",
            "description": "PEM-encoded X.509 certificate used for document signing"
          },
          "format": {
            "type": "string",
            "enum": ["pem"],
            "description": "Format of the certificate (currently only PEM is supported)"
          },
          "trust_lists": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": ["uv", "aamva_dts"]
            },
            "uniqueItems": true,
            "description": "The trust lists under which this certificate is recognized (e.g., uv, aamva_dts)"
          }
        },
        "additionalProperties": false
      },
      "minItems": 1,
      "description": "Array of certificates issued with the same subject key identifier with the most recent first. It is expected that only one certificate per subject is present, so if only updating the expiration date, the old certificate should be removed when adding the new one."
    },
    "signature": {
      "type": "string",
      "description": "Signature over the canonicalized JSON, excluding this field"
    }
  },
  "additionalProperties": false,
  "allOf": [
    {
      "if": {
        "properties": {
          "issuer_id": {
            "type": "string",
            "pattern": "^x509_aki:"
          }
        }
      },
      "then": {
        "required": ["certificates"]
      }
    },
    {
      "if": {
        "properties": { "entity_type": { "const": "government" } }
      },
      "then": {
        "properties": {
          "entity_metadata": {
            "type": "object",
            "required": ["country", "official_name", "government_level"]
          }
        }
      }
    },
    {
      "if": {
        "properties": { "entity_type": { "const": "educational_institution" } }
      },
      "then": {
        "properties": {
          "entity_metadata": {
            "type": "object",
            "required": ["country", "institution_name", "institution_type"]
          }
        }
      }
    }
  ]
}