smoa/docs/schemas/credential-authority.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://smoa.dev/schemas/credential-authority.schema.json",
  "title": "Issuing authority and jurisdiction (multi-government)",
  "description": "Reusable context for credentials issued under different national governments, federated states, ministries, armed services, agencies, and subdivisions. Use inside credential sync payload JSON alongside format-specific fields.",
  "$defs": {
    "LocalizedString": {
      "type": "object",
      "required": ["language", "value"],
      "properties": {
        "language": {
          "type": "string",
          "pattern": "^[a-z]{2}(-[A-Za-z0-9]{2,8})?$",
          "description": "BCP 47 language tag (e.g. en, en-US, fr-CA)."
        },
        "value": {
          "type": "string",
          "description": "Human-readable text in that language."
        }
      },
      "additionalProperties": false
    },
    "Jurisdiction": {
      "type": "object",
      "description": "Legal or administrative territory for the issuance act.",
      "properties": {
        "countryCode": {
          "type": "string",
          "minLength": 2,
          "maxLength": 3,
          "pattern": "^([A-Z]{2}|[A-Z]{3})$",
          "description": "ISO 3166-1 alpha-2 (preferred for APIs) or alpha-3."
        },
        "subdivisionCode": {
          "type": "string",
          "description": "ISO 3166-2 code (e.g. US-CA), national province/state code, or regional scheme."
        },
        "localityCode": {
          "type": "string",
          "description": "Municipality, county, district, indigenous territory, or other local identifier."
        },
        "supranationalBody": {
          "type": "string",
          "description": "When issuance is under EU, UN agency code, or other supranational framework."
        }
      },
      "additionalProperties": true
    },
    "GovernmentBody": {
      "type": "object",
      "description": "Organizational hierarchy under a jurisdiction; not all fields apply to every country.",
      "properties": {
        "level": {
          "type": "string",
          "enum": [
            "supranational",
            "national",
            "federal_union_member",
            "state_provincial",
            "regional",
            "local",
            "territorial",
            "tribal_indigenous",
            "international_organization",
            "other"
          ],
          "description": "Rough classification of the issuing government's level."
        },
        "branchOrPower": {
          "type": "string",
          "description": "Executive, legislative, judicial, or blended; label is jurisdiction-specific."
        },
        "ministryOrDepartment": {
          "type": "string",
          "description": "Cabinet ministry, federal department, or top-level civil organ."
        },
        "agencyCode": {
          "type": "string",
          "description": "Short stable code for the issuing agency within the tenant registry."
        },
        "agencyOfficialName": {
          "type": "string",
          "description": "Primary legal or registered name of the agency."
        },
        "serviceBranch": {
          "type": "string",
          "description": "Armed force, gendarmerie, coast guard, or national guard branch when applicable."
        },
        "organizationalUnit": {
          "type": "string",
          "description": "Subordinate command, directorate, regional office, station, or detachment."
        },
        "displayNames": {
          "type": "array",
          "description": "Localized names for the issuing body for presentation on device.",
          "items": { "$ref": "#/$defs/LocalizedString" }
        }
      },
      "additionalProperties": true
    },
    "IssuingAuthorityContext": {
      "type": "object",
      "description": "Who issued the credential in a multi-tenant, multi-state deployment.",
      "properties": {
        "tenantId": {
          "type": "string",
          "description": "Tenant / program partition (UUID, slug, or national registry id)."
        },
        "trustDomain": {
          "type": "string",
          "description": "Optional trust boundary (e.g. piv_pki, nfc_access) aligned with issuance architecture."
        },
        "jurisdiction": { "$ref": "#/$defs/Jurisdiction" },
        "government": { "$ref": "#/$defs/GovernmentBody" },
        "credentialRegistryRef": {
          "type": "object",
          "description": "Optional pointer to an external credential registry (e.g. Complete Credential).",
          "properties": {
            "credentialId": { "type": "string" },
            "subjectId": { "type": "string", "format": "uuid" },
            "registryUri": { "type": "string", "format": "uri" }
          },
          "additionalProperties": true
        }
      },
      "additionalProperties": true
    }
  }
}