OrganizationDomainVerification schema

Generated from the canonical schema schemas/organization-domain-verification.schema.json by scripts/generate-schema-docs.mjs — do not edit this page by hand.

An immutable, auditable verification event on an OrganizationDomain: who proved what, how, and when. Method-specific provenance (for EMAIL, the exact verifying address; for DNS, the challenge evidence) is retained privately and never appears in public API responses or UI — it exists so a legitimate organization-control dispute or recovery request can be resolved by disclosure to an independently verified representative of the organization.

Schema version: 1.0.0 · $id: https://tokensforprogress.org/schemas/organization-domain-verification.schema.json

Fields

id

Type: string · Required: yes · Mutable: no · Pattern: ^odv_[0-9a-z]{10,32}$

Stable opaque identifier.

Example: "odv_01jf91bb2prf0"

organization_domain_id

Type: string · Required: yes · Mutable: no · Pattern: ^dom_[0-9a-z]{10,32}$

The OrganizationDomain relationship this event verified.

Example: "dom_01jf91aa1anth"

verified_by_user_id

Type: string · Required: yes · Mutable: no · Pattern: ^usr_[0-9a-z]{10,32}$

The User who performed the verification. Verification proves what it proves — it never implies this person was internally authorized by the institution.

Example: "usr_01jf8xw3tempo"

method

Type: EMAIL | DNS · Required: yes · Mutable: no

EMAIL: demonstrated access to a mailbox at the domain via a single-use magic link. DNS: demonstrated control of the domain via a TXT-record challenge. DNS outranks EMAIL.

Example: "EMAIL"

verified_at

Type: string · Required: yes · Mutable: no

RFC 3339 UTC timestamp of successful verification.

Example: "2026-08-31T18:00:00Z"

revoked_at

Type: string \| null · Required: no · Mutable: yes

RFC 3339 UTC timestamp if this verification was later revoked or superseded, else null.

Example: null

JSON Schema source

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://tokensforprogress.org/schemas/organization-domain-verification.schema.json",
  "title": "OrganizationDomainVerification",
  "description": "An immutable, auditable verification event on an OrganizationDomain: who proved what, how, and when. Method-specific provenance (for EMAIL, the exact verifying address; for DNS, the challenge evidence) is retained privately and never appears in public API responses or UI — it exists so a legitimate organization-control dispute or recovery request can be resolved by disclosure to an independently verified representative of the organization.",
  "x-tfp-version": "1.0.0",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "organization_domain_id",
    "verified_by_user_id",
    "method",
    "verified_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^odv_[0-9a-z]{10,32}$",
      "x-mutable": false,
      "description": "Stable opaque identifier.",
      "examples": [
        "odv_01jf91bb2prf0"
      ]
    },
    "organization_domain_id": {
      "type": "string",
      "pattern": "^dom_[0-9a-z]{10,32}$",
      "x-mutable": false,
      "description": "The OrganizationDomain relationship this event verified.",
      "examples": [
        "dom_01jf91aa1anth"
      ]
    },
    "verified_by_user_id": {
      "type": "string",
      "pattern": "^usr_[0-9a-z]{10,32}$",
      "x-mutable": false,
      "description": "The User who performed the verification. Verification proves what it proves — it never implies this person was internally authorized by the institution.",
      "examples": [
        "usr_01jf8xw3tempo"
      ]
    },
    "method": {
      "type": "string",
      "enum": [
        "EMAIL",
        "DNS"
      ],
      "x-mutable": false,
      "description": "EMAIL: demonstrated access to a mailbox at the domain via a single-use magic link. DNS: demonstrated control of the domain via a TXT-record challenge. DNS outranks EMAIL.",
      "examples": [
        "EMAIL"
      ]
    },
    "verified_at": {
      "type": "string",
      "format": "date-time",
      "x-mutable": false,
      "description": "RFC 3339 UTC timestamp of successful verification.",
      "examples": [
        "2026-08-31T18:00:00Z"
      ]
    },
    "revoked_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "x-mutable": true,
      "description": "RFC 3339 UTC timestamp if this verification was later revoked or superseded, else null.",
      "examples": [
        null
      ]
    }
  }
}