@openvtc/trust-tasks 0.26.17 → 0.26.18

package/src/vtc/directory/fields/define/0.1/payload.ts

@@ -0,0 +1,847 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/vtc/directory/fields/define/0.1/payload.schema.json
+ */
+
+import type { Audience, ClaimSelector, EnumOption, Ext, FieldConstraints, FieldDefinition, FieldDescription, FieldInput, FieldKey, FieldLabel, FieldSource, FieldState, FieldType } from "../../../../../_shared/components.js";
+
+
+/**
+ * An administrator adds a field to the community's directory schema: its type, who writes it, its ceiling and its default visibility. The outer document members are owned by the framework — SPEC §6.3.
+ */
+export interface VTCDirectoryFieldsDefinePayload {
+  field: FieldInput;
+  /**
+   * Why, recorded with the change and shown to anyone who must approve it.
+   */
+  reason?: string;
+  ext?: Ext;
+}
+/**
+ * The success response to a vtc/directory/fields/define/0.1 request. Carried in a Trust Task document whose type is https://trusttasks.org/spec/vtc/directory/fields/define/0.1#response.
+ */
+export interface VTCDirectoryFieldsDefineResponsePayload {
+  field: FieldDefinition;
+  ext?: Ext;
+}
+
+/** Shared definitions this specification references, re-exported under the names it used to declare them with. */
+export type { Audience, ClaimSelector, EnumOption, Ext, FieldConstraints, FieldDefinition, FieldDescription, FieldInput, FieldKey, FieldLabel, FieldSource, FieldState, FieldType };
+
+/** Trust Task type URI. */
+export const TYPE_URI = "https://trusttasks.org/spec/vtc/directory/fields/define/0.1" as const;
+
+/** Stable alias for this specification's request payload shape. */
+export type Payload = VTCDirectoryFieldsDefinePayload;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/vtc/directory/fields/define/0.1#response" as const;
+
+/** Stable alias for this specification's success-response payload shape. */
+export type Response = VTCDirectoryFieldsDefineResponsePayload;
+
+/**
+ * This specification's payload schema, as a value.
+ *
+ * SPEC.md §7.2 item 2 is performed against this. It is shipped as data
+ * rather than only as a `.json` file because TypeScript types are erased
+ * at runtime: without a schema a consumer has nothing to validate, and
+ * every REQUIRED payload member is optional in practice. Cross-file
+ * `$ref`s are already inlined, so it needs no resolver.
+ */
+export const PAYLOAD_SCHEMA = {
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://trusttasks.org/spec/vtc/directory/fields/define/0.1",
+  "title": "VTC Directory — Fields — Define — payload",
+  "description": "An administrator adds a field to the community's directory schema: its type, who writes it, its ceiling and its default visibility. The outer document members are owned by the framework — SPEC §6.3.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "field"
+  ],
+  "properties": {
+    "field": {
+      "$ref": "#/$defs/FieldInput"
+    },
+    "reason": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1024,
+      "description": "Why, recorded with the change and shown to anyone who must approve it."
+    },
+    "ext": {
+      "$ref": "#/$defs/Ext"
+    }
+  },
+  "$defs": {
+    "Response": {
+      "$anchor": "response",
+      "title": "VTC Directory — Fields — Define — response payload",
+      "description": "The success response to a vtc/directory/fields/define/0.1 request. Carried in a Trust Task document whose type is https://trusttasks.org/spec/vtc/directory/fields/define/0.1#response.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "field"
+      ],
+      "properties": {
+        "field": {
+          "$ref": "#/$defs/FieldDefinition"
+        },
+        "ext": {
+          "$ref": "#/$defs/Ext"
+        }
+      }
+    },
+    "Ext": {
+      "title": "Ext",
+      "description": "Vendor-namespaced extension object per SPEC.md §4.5.1. Each immediate key MUST be a reverse-DNS namespace; structure under each namespace is opaque to the framework.",
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": true,
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9-]*(\\.[a-z0-9-]+)+$"
+      }
+    },
+    "FieldDefinition": {
+      "title": "FieldDefinition",
+      "description": "One field of the community's directory schema, as the community holds it. The audience order `admins` < `groups`/`connections` < `members` < `public` applies to `ceiling` and `defaultVisibility`; `defaultVisibility` is never wider than `ceiling`.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "key",
+        "label",
+        "type",
+        "source",
+        "base",
+        "ceiling",
+        "defaultVisibility",
+        "required",
+        "searchable",
+        "facet",
+        "order",
+        "state"
+      ],
+      "properties": {
+        "key": {
+          "$ref": "#/$defs/FieldKey"
+        },
+        "label": {
+          "$ref": "#/$defs/FieldLabel"
+        },
+        "description": {
+          "$ref": "#/$defs/FieldDescription"
+        },
+        "type": {
+          "$ref": "#/$defs/FieldType"
+        },
+        "constraints": {
+          "$ref": "#/$defs/FieldConstraints"
+        },
+        "source": {
+          "$ref": "#/$defs/FieldSource"
+        },
+        "base": {
+          "type": "boolean",
+          "description": "`true` for a base field, present in every community; `false` for a field this community defined."
+        },
+        "jsContactPath": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "description": "Where the field lands when an entry is exported as a JSContact Card (RFC 9553), e.g. `name.full`, `nicknames`, `speakToAs.pronouns`. Absent: a vendor-specific property named by the key."
+        },
+        "required": {
+          "type": "boolean"
+        },
+        "ceiling": {
+          "$ref": "#/$defs/Audience"
+        },
+        "defaultVisibility": {
+          "$ref": "#/$defs/Audience"
+        },
+        "searchable": {
+          "type": "boolean"
+        },
+        "facet": {
+          "type": "boolean"
+        },
+        "order": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 10000
+        },
+        "state": {
+          "$ref": "#/$defs/FieldState"
+        },
+        "retiredAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the field was retired. Present only on a retired field."
+        },
+        "purgeAfter": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the values of a retired field are purged. Present only on a retired field."
+        },
+        "updatedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "ext": {
+          "$ref": "#/$defs/Ext",
+          "description": "Ecosystem-defined extension members per SPEC.md §4.5.1. An extension member MUST NOT widen a ceiling."
+        }
+      }
+    },
+    "FieldState": {
+      "title": "FieldState",
+      "description": "`active`: in use. `disabled`: a base field the community has switched off; hidden from every projection and re-enablable. `retired`: a community field withdrawn for good; hidden at once, its values purged after the community's retention period, and its key never reused.",
+      "type": "string",
+      "enum": [
+        "active",
+        "disabled",
+        "retired"
+      ]
+    },
+    "FieldSource": {
+      "title": "FieldSource",
+      "description": "Who writes the value. `member`: self-asserted, through vtc/directory/card/update. `admin`: asserted by the community through vtc/directory/card/assert; the member reads it and cannot change it. `credential`: a claim the member discloses from a credential through vtc/directory/card/present, badged with its issuer. `derived`: a base field read from the community's own records (`role`, `joinedAt`, `did`, `personhood`) and never stored on a card. Each source is written only through its own path.",
+      "type": "string",
+      "enum": [
+        "member",
+        "admin",
+        "credential",
+        "derived"
+      ]
+    },
+    "FieldConstraints": {
+      "title": "FieldConstraints",
+      "description": "Per-type constraints. A member that does not apply to the field's type is refused by the community with `valueInvalid` when the definition is written.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "maxLength": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 2000
+        },
+        "minLength": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 2000
+        },
+        "pattern": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256,
+          "description": "ECMA-262 regular expression a text value MUST match."
+        },
+        "options": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 128,
+          "items": {
+            "$ref": "#/$defs/EnumOption"
+          },
+          "description": "The permitted values of an `enum` or `multiEnum` field."
+        },
+        "maxItems": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 32
+        },
+        "minDate": {
+          "type": "string",
+          "format": "date"
+        },
+        "maxDate": {
+          "type": "string",
+          "format": "date"
+        },
+        "claim": {
+          "$ref": "#/$defs/ClaimSelector"
+        }
+      }
+    },
+    "ClaimSelector": {
+      "title": "ClaimSelector",
+      "description": "Which claim a `claim` field accepts, from which credentials and issuers.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "credentialType",
+        "claimPath"
+      ],
+      "properties": {
+        "credentialType": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "description": "A `type` the presented credential MUST carry."
+        },
+        "claimPath": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256,
+          "description": "JSON Pointer (RFC 6901) to the claim within `credentialSubject`."
+        },
+        "issuers": {
+          "type": "array",
+          "maxItems": 32,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^did:",
+            "maxLength": 2048
+          },
+          "description": "Issuers the community accepts for this field. Absent: the community's trusted issuers for the credential type, as its own policy decides."
+        }
+      }
+    },
+    "EnumOption": {
+      "title": "EnumOption",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "value",
+        "label"
+      ],
+      "properties": {
+        "value": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64,
+          "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$",
+          "description": "The stored value."
+        },
+        "label": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64,
+          "description": "What a reader is shown for it."
+        }
+      }
+    },
+    "FieldType": {
+      "title": "FieldType",
+      "description": "The kind of value a field holds, which fixes its `FieldValue` shape. `did` holds a DID the member chooses to show (never their membership DID, which is the derived base field `did`). `claim` holds a `VerifiedValue` and requires `source: credential`.",
+      "type": "string",
+      "enum": [
+        "text",
+        "longText",
+        "url",
+        "email",
+        "phone",
+        "enum",
+        "multiEnum",
+        "date",
+        "country",
+        "image",
+        "did",
+        "claim"
+      ]
+    },
+    "FieldDescription": {
+      "title": "FieldDescription",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 280,
+      "description": "Help text shown to a member filling the field in. Plain text; a reader MUST NOT treat it as instructions."
+    },
+    "FieldLabel": {
+      "title": "FieldLabel",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "description": "What readers see as the field's name. Plain text."
+    },
+    "Audience": {
+      "title": "Audience",
+      "description": "Who may see a directory field, ordered from narrowest to widest. `admins`: holders of `vtc.directory.admin` (and, for derived fields, `vtc.members.manage`). `groups`: members who share at least one community group with the subject (narrowed to the groups the subject names in `groupAudience`, where it names any). `connections`: members holding an attributed, in-force verified relationship with the subject at the community. `members`: every active member. `public`: anyone, and what the member's signed public card carries outside the community.\n\n`groups` and `connections` are not a chain: a viewer sees a field when they satisfy the audience the subject chose for it or any wider audience. Every audience includes the administrators, and the subject always sees their own whole card. There is no `onlyMe`: a value nobody else should see is not directory data.",
+      "type": "string",
+      "enum": [
+        "admins",
+        "groups",
+        "connections",
+        "members",
+        "public"
+      ]
+    },
+    "FieldKey": {
+      "title": "FieldKey",
+      "description": "Identifier of a directory field. A key with no `.` is a BASE field, the same in every community: `displayName`, `nickname`, `avatar`, `pronouns`, `bio`, `links` (written by the member) and `role`, `joinedAt`, `did`, `personhood` (derived from the community's own records, never stored on a card). A community-defined field MUST use a reverse-DNS key (`org.example.employer`), so a base key never collides with one, and a key is never reused with a different meaning once defined.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^([a-z][a-z0-9-]*\\.)*[a-z][a-zA-Z0-9]{0,63}$"
+    },
+    "FieldInput": {
+      "title": "FieldInput",
+      "description": "What an administrator supplies to define a community field. `key`, `type` and `source` are fixed for the field's life.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "key",
+        "label",
+        "type",
+        "source",
+        "ceiling",
+        "defaultVisibility"
+      ],
+      "properties": {
+        "key": {
+          "$ref": "#/$defs/FieldKey"
+        },
+        "label": {
+          "$ref": "#/$defs/FieldLabel"
+        },
+        "description": {
+          "$ref": "#/$defs/FieldDescription"
+        },
+        "type": {
+          "$ref": "#/$defs/FieldType"
+        },
+        "constraints": {
+          "$ref": "#/$defs/FieldConstraints"
+        },
+        "source": {
+          "type": "string",
+          "enum": [
+            "member",
+            "admin",
+            "credential"
+          ],
+          "description": "As `FieldSource`, less `derived`, which only base fields carry."
+        },
+        "required": {
+          "type": "boolean",
+          "description": "Whether a card must hold a value for its entry to be listed. Never a condition of membership. Absent: false."
+        },
+        "ceiling": {
+          "$ref": "#/$defs/Audience"
+        },
+        "defaultVisibility": {
+          "$ref": "#/$defs/Audience",
+          "description": "The audience a card gives the field until its member chooses. MUST NOT be wider than `ceiling`."
+        },
+        "searchable": {
+          "type": "boolean",
+          "description": "Whether a member's search may match the field, within what the searcher may see. Absent: false."
+        },
+        "facet": {
+          "type": "boolean",
+          "description": "Whether the field may be filtered on and counted. Only `enum`, `multiEnum` and `country` fields may be facets. Absent: false."
+        },
+        "order": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 10000,
+          "description": "Display order, ascending."
+        }
+      }
+    }
+  }
+} as const;
+
+/** As {@link PAYLOAD_SCHEMA}, for the success-response variant. */
+export const RESPONSE_PAYLOAD_SCHEMA = {
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$ref": "#/$defs/Response",
+  "$defs": {
+    "Response": {
+      "$anchor": "response",
+      "title": "VTC Directory — Fields — Define — response payload",
+      "description": "The success response to a vtc/directory/fields/define/0.1 request. Carried in a Trust Task document whose type is https://trusttasks.org/spec/vtc/directory/fields/define/0.1#response.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "field"
+      ],
+      "properties": {
+        "field": {
+          "$ref": "#/$defs/FieldDefinition"
+        },
+        "ext": {
+          "$ref": "#/$defs/Ext"
+        }
+      }
+    },
+    "Ext": {
+      "title": "Ext",
+      "description": "Vendor-namespaced extension object per SPEC.md §4.5.1. Each immediate key MUST be a reverse-DNS namespace; structure under each namespace is opaque to the framework.",
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": true,
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9-]*(\\.[a-z0-9-]+)+$"
+      }
+    },
+    "FieldDefinition": {
+      "title": "FieldDefinition",
+      "description": "One field of the community's directory schema, as the community holds it. The audience order `admins` < `groups`/`connections` < `members` < `public` applies to `ceiling` and `defaultVisibility`; `defaultVisibility` is never wider than `ceiling`.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "key",
+        "label",
+        "type",
+        "source",
+        "base",
+        "ceiling",
+        "defaultVisibility",
+        "required",
+        "searchable",
+        "facet",
+        "order",
+        "state"
+      ],
+      "properties": {
+        "key": {
+          "$ref": "#/$defs/FieldKey"
+        },
+        "label": {
+          "$ref": "#/$defs/FieldLabel"
+        },
+        "description": {
+          "$ref": "#/$defs/FieldDescription"
+        },
+        "type": {
+          "$ref": "#/$defs/FieldType"
+        },
+        "constraints": {
+          "$ref": "#/$defs/FieldConstraints"
+        },
+        "source": {
+          "$ref": "#/$defs/FieldSource"
+        },
+        "base": {
+          "type": "boolean",
+          "description": "`true` for a base field, present in every community; `false` for a field this community defined."
+        },
+        "jsContactPath": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "description": "Where the field lands when an entry is exported as a JSContact Card (RFC 9553), e.g. `name.full`, `nicknames`, `speakToAs.pronouns`. Absent: a vendor-specific property named by the key."
+        },
+        "required": {
+          "type": "boolean"
+        },
+        "ceiling": {
+          "$ref": "#/$defs/Audience"
+        },
+        "defaultVisibility": {
+          "$ref": "#/$defs/Audience"
+        },
+        "searchable": {
+          "type": "boolean"
+        },
+        "facet": {
+          "type": "boolean"
+        },
+        "order": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 10000
+        },
+        "state": {
+          "$ref": "#/$defs/FieldState"
+        },
+        "retiredAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the field was retired. Present only on a retired field."
+        },
+        "purgeAfter": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the values of a retired field are purged. Present only on a retired field."
+        },
+        "updatedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "ext": {
+          "$ref": "#/$defs/Ext",
+          "description": "Ecosystem-defined extension members per SPEC.md §4.5.1. An extension member MUST NOT widen a ceiling."
+        }
+      }
+    },
+    "FieldState": {
+      "title": "FieldState",
+      "description": "`active`: in use. `disabled`: a base field the community has switched off; hidden from every projection and re-enablable. `retired`: a community field withdrawn for good; hidden at once, its values purged after the community's retention period, and its key never reused.",
+      "type": "string",
+      "enum": [
+        "active",
+        "disabled",
+        "retired"
+      ]
+    },
+    "FieldSource": {
+      "title": "FieldSource",
+      "description": "Who writes the value. `member`: self-asserted, through vtc/directory/card/update. `admin`: asserted by the community through vtc/directory/card/assert; the member reads it and cannot change it. `credential`: a claim the member discloses from a credential through vtc/directory/card/present, badged with its issuer. `derived`: a base field read from the community's own records (`role`, `joinedAt`, `did`, `personhood`) and never stored on a card. Each source is written only through its own path.",
+      "type": "string",
+      "enum": [
+        "member",
+        "admin",
+        "credential",
+        "derived"
+      ]
+    },
+    "FieldConstraints": {
+      "title": "FieldConstraints",
+      "description": "Per-type constraints. A member that does not apply to the field's type is refused by the community with `valueInvalid` when the definition is written.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "maxLength": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 2000
+        },
+        "minLength": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 2000
+        },
+        "pattern": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256,
+          "description": "ECMA-262 regular expression a text value MUST match."
+        },
+        "options": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 128,
+          "items": {
+            "$ref": "#/$defs/EnumOption"
+          },
+          "description": "The permitted values of an `enum` or `multiEnum` field."
+        },
+        "maxItems": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 32
+        },
+        "minDate": {
+          "type": "string",
+          "format": "date"
+        },
+        "maxDate": {
+          "type": "string",
+          "format": "date"
+        },
+        "claim": {
+          "$ref": "#/$defs/ClaimSelector"
+        }
+      }
+    },
+    "ClaimSelector": {
+      "title": "ClaimSelector",
+      "description": "Which claim a `claim` field accepts, from which credentials and issuers.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "credentialType",
+        "claimPath"
+      ],
+      "properties": {
+        "credentialType": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "description": "A `type` the presented credential MUST carry."
+        },
+        "claimPath": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256,
+          "description": "JSON Pointer (RFC 6901) to the claim within `credentialSubject`."
+        },
+        "issuers": {
+          "type": "array",
+          "maxItems": 32,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^did:",
+            "maxLength": 2048
+          },
+          "description": "Issuers the community accepts for this field. Absent: the community's trusted issuers for the credential type, as its own policy decides."
+        }
+      }
+    },
+    "EnumOption": {
+      "title": "EnumOption",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "value",
+        "label"
+      ],
+      "properties": {
+        "value": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64,
+          "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$",
+          "description": "The stored value."
+        },
+        "label": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64,
+          "description": "What a reader is shown for it."
+        }
+      }
+    },
+    "FieldType": {
+      "title": "FieldType",
+      "description": "The kind of value a field holds, which fixes its `FieldValue` shape. `did` holds a DID the member chooses to show (never their membership DID, which is the derived base field `did`). `claim` holds a `VerifiedValue` and requires `source: credential`.",
+      "type": "string",
+      "enum": [
+        "text",
+        "longText",
+        "url",
+        "email",
+        "phone",
+        "enum",
+        "multiEnum",
+        "date",
+        "country",
+        "image",
+        "did",
+        "claim"
+      ]
+    },
+    "FieldDescription": {
+      "title": "FieldDescription",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 280,
+      "description": "Help text shown to a member filling the field in. Plain text; a reader MUST NOT treat it as instructions."
+    },
+    "FieldLabel": {
+      "title": "FieldLabel",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "description": "What readers see as the field's name. Plain text."
+    },
+    "Audience": {
+      "title": "Audience",
+      "description": "Who may see a directory field, ordered from narrowest to widest. `admins`: holders of `vtc.directory.admin` (and, for derived fields, `vtc.members.manage`). `groups`: members who share at least one community group with the subject (narrowed to the groups the subject names in `groupAudience`, where it names any). `connections`: members holding an attributed, in-force verified relationship with the subject at the community. `members`: every active member. `public`: anyone, and what the member's signed public card carries outside the community.\n\n`groups` and `connections` are not a chain: a viewer sees a field when they satisfy the audience the subject chose for it or any wider audience. Every audience includes the administrators, and the subject always sees their own whole card. There is no `onlyMe`: a value nobody else should see is not directory data.",
+      "type": "string",
+      "enum": [
+        "admins",
+        "groups",
+        "connections",
+        "members",
+        "public"
+      ]
+    },
+    "FieldKey": {
+      "title": "FieldKey",
+      "description": "Identifier of a directory field. A key with no `.` is a BASE field, the same in every community: `displayName`, `nickname`, `avatar`, `pronouns`, `bio`, `links` (written by the member) and `role`, `joinedAt`, `did`, `personhood` (derived from the community's own records, never stored on a card). A community-defined field MUST use a reverse-DNS key (`org.example.employer`), so a base key never collides with one, and a key is never reused with a different meaning once defined.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^([a-z][a-z0-9-]*\\.)*[a-z][a-zA-Z0-9]{0,63}$"
+    },
+    "FieldInput": {
+      "title": "FieldInput",
+      "description": "What an administrator supplies to define a community field. `key`, `type` and `source` are fixed for the field's life.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "key",
+        "label",
+        "type",
+        "source",
+        "ceiling",
+        "defaultVisibility"
+      ],
+      "properties": {
+        "key": {
+          "$ref": "#/$defs/FieldKey"
+        },
+        "label": {
+          "$ref": "#/$defs/FieldLabel"
+        },
+        "description": {
+          "$ref": "#/$defs/FieldDescription"
+        },
+        "type": {
+          "$ref": "#/$defs/FieldType"
+        },
+        "constraints": {
+          "$ref": "#/$defs/FieldConstraints"
+        },
+        "source": {
+          "type": "string",
+          "enum": [
+            "member",
+            "admin",
+            "credential"
+          ],
+          "description": "As `FieldSource`, less `derived`, which only base fields carry."
+        },
+        "required": {
+          "type": "boolean",
+          "description": "Whether a card must hold a value for its entry to be listed. Never a condition of membership. Absent: false."
+        },
+        "ceiling": {
+          "$ref": "#/$defs/Audience"
+        },
+        "defaultVisibility": {
+          "$ref": "#/$defs/Audience",
+          "description": "The audience a card gives the field until its member chooses. MUST NOT be wider than `ceiling`."
+        },
+        "searchable": {
+          "type": "boolean",
+          "description": "Whether a member's search may match the field, within what the searcher may see. Absent: false."
+        },
+        "facet": {
+          "type": "boolean",
+          "description": "Whether the field may be filtered on and counted. Only `enum`, `multiEnum` and `country` fields may be facets. Absent: false."
+        },
+        "order": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 10000,
+          "description": "Display order, ascending."
+        }
+      }
+    }
+  }
+} as const;
+
+/**
+ * SPEC.md §7.2 policy for the request variant, from this specification's
+ * front matter. Pass to `consumeInbound` — items 5b, 7 and 8 are
+ * per-specification and cannot be derived from the document alone, and
+ * item 2 needs the schema this carries.
+ */
+export const SPEC = {
+  typeUri: TYPE_URI,
+  isBearer: false,
+  isProofRequired: true,
+  isRecipientRequired: true,
+  isIssuedAtRequired: true,
+  payloadSchema: PAYLOAD_SCHEMA,
+} as const;
+
+/**
+ * SPEC.md §7.2 policy for the success-response variant. `isRecipientRequired`
+ * tracks the *issuer* party's requirement because a response swaps the
+ * parties (§7.3 item 5).
+ */
+export const RESPONSE_SPEC = {
+  typeUri: RESPONSE_TYPE_URI,
+  isBearer: false,
+  isProofRequired: true,
+  isRecipientRequired: true,
+  isIssuedAtRequired: true,
+  payloadSchema: RESPONSE_PAYLOAD_SCHEMA,
+} as const;