@openvtc/trust-tasks 0.21.16 → 0.22.1

package/src/vtc/auth/recognise/0.2/payload.ts

@@ -8,7 +8,7 @@ import type { Ext } from "../../../../_shared/components.js";
 
 export interface VTCAuthRecognisePayload {
   /**
-   * A holder-signed W3C Verifiable Presentation embedding the foreign membership and endorsement credentials in `verifiableCredential`.
+   * A holder-signed W3C Verifiable Presentation embedding the foreign membership credential (`MembershipCredential`) and role credential (a Verifiable Authority Credential, `AuthorityCredential`, conferring `role:<name>` at the foreign community's DID) in `verifiableCredential`.
    *
    * The holder proof MUST use `proofPurpose: authentication`, MUST commit to the single-use `nonce` issued by `vtc/auth/recognise/challenge`, and MUST name the recognising community's DID as `domain`. A consumer MUST verify the holder proof, verify each embedded credential's issuer proof, and refuse unless the presentation's holder is the credentials' subject.
    */
@@ -71,7 +71,7 @@ export const PAYLOAD_SCHEMA = {
   "properties": {
     "presentation": {
       "type": "object",
-      "description": "A holder-signed W3C Verifiable Presentation embedding the foreign membership and endorsement credentials in `verifiableCredential`.\n\nThe holder proof MUST use `proofPurpose: authentication`, MUST commit to the single-use `nonce` issued by `vtc/auth/recognise/challenge`, and MUST name the recognising community's DID as `domain`. A consumer MUST verify the holder proof, verify each embedded credential's issuer proof, and refuse unless the presentation's holder is the credentials' subject."
+      "description": "A holder-signed W3C Verifiable Presentation embedding the foreign membership credential (`MembershipCredential`) and role credential (a Verifiable Authority Credential, `AuthorityCredential`, conferring `role:<name>` at the foreign community's DID) in `verifiableCredential`.\n\nThe holder proof MUST use `proofPurpose: authentication`, MUST commit to the single-use `nonce` issued by `vtc/auth/recognise/challenge`, and MUST name the recognising community's DID as `domain`. A consumer MUST verify the holder proof, verify each embedded credential's issuer proof, and refuse unless the presentation's holder is the credentials' subject."
     },
     "ext": {
       "$ref": "#/$defs/Ext"

package/src/vtc/community/profile/show/0.1/payload.ts

@@ -181,7 +181,7 @@ export const PAYLOAD_SCHEMA = {
             "type": "string",
             "minLength": 1
           },
-          "description": "DIDs of the identity-verification providers whose credentials this community accepts as personhood evidence. A community that vets its own members in person lists its own community DID here — it is acting as its own IDVP, which §IDVC permits. An empty list means no list has been published, not that everything is accepted."
+          "description": "DIDs of the identity-verification providers whose credentials this community accepts as personhood evidence. A community that vets its own members in person lists its own community DID here — it is acting as its own IDVP, which §IDVC permits — and issues the evidence as an `IdentityVerificationCredential` (a plain W3C VC, not a DTGCredential) through vtc/endorsements/issue. An empty list means no list has been published, not that everything is accepted."
         },
         "governanceFrameworkUrl": {
           "type": [
@@ -328,7 +328,7 @@ export const RESPONSE_PAYLOAD_SCHEMA = {
             "type": "string",
             "minLength": 1
           },
-          "description": "DIDs of the identity-verification providers whose credentials this community accepts as personhood evidence. A community that vets its own members in person lists its own community DID here — it is acting as its own IDVP, which §IDVC permits. An empty list means no list has been published, not that everything is accepted."
+          "description": "DIDs of the identity-verification providers whose credentials this community accepts as personhood evidence. A community that vets its own members in person lists its own community DID here — it is acting as its own IDVP, which §IDVC permits — and issues the evidence as an `IdentityVerificationCredential` (a plain W3C VC, not a DTGCredential) through vtc/endorsements/issue. An empty list means no list has been published, not that everything is accepted."
         },
         "governanceFrameworkUrl": {
           "type": [

package/src/vtc/community/profile/update/0.1/payload.ts

@@ -257,7 +257,7 @@ export const PAYLOAD_SCHEMA = {
             "type": "string",
             "minLength": 1
           },
-          "description": "DIDs of the identity-verification providers whose credentials this community accepts as personhood evidence. A community that vets its own members in person lists its own community DID here — it is acting as its own IDVP, which §IDVC permits. An empty list means no list has been published, not that everything is accepted."
+          "description": "DIDs of the identity-verification providers whose credentials this community accepts as personhood evidence. A community that vets its own members in person lists its own community DID here — it is acting as its own IDVP, which §IDVC permits — and issues the evidence as an `IdentityVerificationCredential` (a plain W3C VC, not a DTGCredential) through vtc/endorsements/issue. An empty list means no list has been published, not that everything is accepted."
         },
         "governanceFrameworkUrl": {
           "type": [
@@ -411,7 +411,7 @@ export const RESPONSE_PAYLOAD_SCHEMA = {
             "type": "string",
             "minLength": 1
           },
-          "description": "DIDs of the identity-verification providers whose credentials this community accepts as personhood evidence. A community that vets its own members in person lists its own community DID here — it is acting as its own IDVP, which §IDVC permits. An empty list means no list has been published, not that everything is accepted."
+          "description": "DIDs of the identity-verification providers whose credentials this community accepts as personhood evidence. A community that vets its own members in person lists its own community DID here — it is acting as its own IDVP, which §IDVC permits — and issues the evidence as an `IdentityVerificationCredential` (a plain W3C VC, not a DTGCredential) through vtc/endorsements/issue. An empty list means no list has been published, not that everything is accepted."
         },
         "governanceFrameworkUrl": {
           "type": [

package/src/vtc/config/export/0.1/payload.ts

@@ -214,7 +214,7 @@ export const PAYLOAD_SCHEMA = {
             "type": "string",
             "minLength": 1
           },
-          "description": "DIDs of the identity-verification providers whose credentials this community accepts as personhood evidence. A community that vets its own members in person lists its own community DID here — it is acting as its own IDVP, which §IDVC permits. An empty list means no list has been published, not that everything is accepted."
+          "description": "DIDs of the identity-verification providers whose credentials this community accepts as personhood evidence. A community that vets its own members in person lists its own community DID here — it is acting as its own IDVP, which §IDVC permits — and issues the evidence as an `IdentityVerificationCredential` (a plain W3C VC, not a DTGCredential) through vtc/endorsements/issue. An empty list means no list has been published, not that everything is accepted."
         },
         "governanceFrameworkUrl": {
           "type": [
@@ -390,7 +390,7 @@ export const RESPONSE_PAYLOAD_SCHEMA = {
             "type": "string",
             "minLength": 1
           },
-          "description": "DIDs of the identity-verification providers whose credentials this community accepts as personhood evidence. A community that vets its own members in person lists its own community DID here — it is acting as its own IDVP, which §IDVC permits. An empty list means no list has been published, not that everything is accepted."
+          "description": "DIDs of the identity-verification providers whose credentials this community accepts as personhood evidence. A community that vets its own members in person lists its own community DID here — it is acting as its own IDVP, which §IDVC permits — and issues the evidence as an `IdentityVerificationCredential` (a plain W3C VC, not a DTGCredential) through vtc/endorsements/issue. An empty list means no list has been published, not that everything is accepted."
         },
         "governanceFrameworkUrl": {
           "type": [

package/src/vtc/config/import/0.1/payload.ts

@@ -333,7 +333,7 @@ export const PAYLOAD_SCHEMA = {
             "type": "string",
             "minLength": 1
           },
-          "description": "DIDs of the identity-verification providers whose credentials this community accepts as personhood evidence. A community that vets its own members in person lists its own community DID here — it is acting as its own IDVP, which §IDVC permits. An empty list means no list has been published, not that everything is accepted."
+          "description": "DIDs of the identity-verification providers whose credentials this community accepts as personhood evidence. A community that vets its own members in person lists its own community DID here — it is acting as its own IDVP, which §IDVC permits — and issues the evidence as an `IdentityVerificationCredential` (a plain W3C VC, not a DTGCredential) through vtc/endorsements/issue. An empty list means no list has been published, not that everything is accepted."
         },
         "governanceFrameworkUrl": {
           "type": [
@@ -592,7 +592,7 @@ export const RESPONSE_PAYLOAD_SCHEMA = {
             "type": "string",
             "minLength": 1
           },
-          "description": "DIDs of the identity-verification providers whose credentials this community accepts as personhood evidence. A community that vets its own members in person lists its own community DID here — it is acting as its own IDVP, which §IDVC permits. An empty list means no list has been published, not that everything is accepted."
+          "description": "DIDs of the identity-verification providers whose credentials this community accepts as personhood evidence. A community that vets its own members in person lists its own community DID here — it is acting as its own IDVP, which §IDVC permits — and issues the evidence as an `IdentityVerificationCredential` (a plain W3C VC, not a DTGCredential) through vtc/endorsements/issue. An empty list means no list has been published, not that everything is accepted."
         },
         "governanceFrameworkUrl": {
           "type": [

package/src/vtc/endorsement-types/list/0.1/payload.ts

@@ -110,7 +110,7 @@ export const PAYLOAD_SCHEMA = {
           "type": "string",
           "minLength": 1,
           "maxLength": 512,
-          "description": "The endorsement type's URI. Community-scoped; workspace-reserved URIs (e.g. CommunityRole) are refused at registration."
+          "description": "The predicate IRI the community accepts, compared as an exact string. Always an absolute IRI: a DTG VSC predicate registry IRI (e.g. `https://registry.trustoverip.org/dtg/vsc/vetted/1`) or a community-namespace IRI defined in the registry's predicate definition format. The four core predicates — endorses/1, witnessed/1, vetted/1 and presented/1 under `https://registry.trustoverip.org/dtg/vsc/` — are seeded when the community starts. The reserved values `IdentityVerificationCredential` and `role:vetter`, which name the other kinds of record vtc/endorsements/* keeps, are never registered."
         },
         "description": {
           "type": "string",
@@ -118,7 +118,7 @@ export const PAYLOAD_SCHEMA = {
         },
         "claimSchema": {
           "type": "object",
-          "description": "Optional JSON Schema the endorsement's claims must satisfy (opaque here)."
+          "description": "Optional JSON Schema a statement's `credentialSubject.object.value` must satisfy (opaque here) — for a registry predicate, the object schema its profile publishes."
         },
         "createdAt": {
           "type": "string",
@@ -187,7 +187,7 @@ export const RESPONSE_PAYLOAD_SCHEMA = {
           "type": "string",
           "minLength": 1,
           "maxLength": 512,
-          "description": "The endorsement type's URI. Community-scoped; workspace-reserved URIs (e.g. CommunityRole) are refused at registration."
+          "description": "The predicate IRI the community accepts, compared as an exact string. Always an absolute IRI: a DTG VSC predicate registry IRI (e.g. `https://registry.trustoverip.org/dtg/vsc/vetted/1`) or a community-namespace IRI defined in the registry's predicate definition format. The four core predicates — endorses/1, witnessed/1, vetted/1 and presented/1 under `https://registry.trustoverip.org/dtg/vsc/` — are seeded when the community starts. The reserved values `IdentityVerificationCredential` and `role:vetter`, which name the other kinds of record vtc/endorsements/* keeps, are never registered."
         },
         "description": {
           "type": "string",
@@ -195,7 +195,7 @@ export const RESPONSE_PAYLOAD_SCHEMA = {
         },
         "claimSchema": {
           "type": "object",
-          "description": "Optional JSON Schema the endorsement's claims must satisfy (opaque here)."
+          "description": "Optional JSON Schema a statement's `credentialSubject.object.value` must satisfy (opaque here) — for a registry predicate, the object schema its profile publishes."
         },
         "createdAt": {
           "type": "string",

package/src/vtc/endorsement-types/register/0.1/payload.ts

@@ -7,10 +7,13 @@ import type { EndorsementType, Ext } from "../../../../_shared/components.js";
 
 
 export interface VTCEndorsementTypesRegisterPayload {
+  /**
+   * The predicate IRI to accept, an absolute IRI: a DTG VSC predicate registry IRI or a community-namespace IRI. The reserved values `IdentityVerificationCredential` and `role:vetter` are refused with `reserved`, and a value that is not an absolute IRI with `invalidUri`.
+   */
   typeUri: string;
   description?: string;
   /**
-   * Optional JSON Schema the endorsement's claims must satisfy (opaque here).
+   * Optional JSON Schema a statement's `credentialSubject.object.value` must satisfy (opaque here).
    */
   claimSchema?: {};
   ext?: Ext;
@@ -57,7 +60,8 @@ export const PAYLOAD_SCHEMA = {
     "typeUri": {
       "type": "string",
       "minLength": 1,
-      "maxLength": 512
+      "maxLength": 512,
+      "description": "The predicate IRI to accept, an absolute IRI: a DTG VSC predicate registry IRI or a community-namespace IRI. The reserved values `IdentityVerificationCredential` and `role:vetter` are refused with `reserved`, and a value that is not an absolute IRI with `invalidUri`."
     },
     "description": {
       "type": "string",
@@ -65,7 +69,7 @@ export const PAYLOAD_SCHEMA = {
     },
     "claimSchema": {
       "type": "object",
-      "description": "Optional JSON Schema the endorsement's claims must satisfy (opaque here)."
+      "description": "Optional JSON Schema a statement's `credentialSubject.object.value` must satisfy (opaque here)."
     },
     "ext": {
       "$ref": "#/$defs/Ext"
@@ -112,7 +116,7 @@ export const PAYLOAD_SCHEMA = {
           "type": "string",
           "minLength": 1,
           "maxLength": 512,
-          "description": "The endorsement type's URI. Community-scoped; workspace-reserved URIs (e.g. CommunityRole) are refused at registration."
+          "description": "The predicate IRI the community accepts, compared as an exact string. Always an absolute IRI: a DTG VSC predicate registry IRI (e.g. `https://registry.trustoverip.org/dtg/vsc/vetted/1`) or a community-namespace IRI defined in the registry's predicate definition format. The four core predicates — endorses/1, witnessed/1, vetted/1 and presented/1 under `https://registry.trustoverip.org/dtg/vsc/` — are seeded when the community starts. The reserved values `IdentityVerificationCredential` and `role:vetter`, which name the other kinds of record vtc/endorsements/* keeps, are never registered."
         },
         "description": {
           "type": "string",
@@ -120,7 +124,7 @@ export const PAYLOAD_SCHEMA = {
         },
         "claimSchema": {
           "type": "object",
-          "description": "Optional JSON Schema the endorsement's claims must satisfy (opaque here)."
+          "description": "Optional JSON Schema a statement's `credentialSubject.object.value` must satisfy (opaque here) — for a registry predicate, the object schema its profile publishes."
         },
         "createdAt": {
           "type": "string",
@@ -180,7 +184,7 @@ export const RESPONSE_PAYLOAD_SCHEMA = {
           "type": "string",
           "minLength": 1,
           "maxLength": 512,
-          "description": "The endorsement type's URI. Community-scoped; workspace-reserved URIs (e.g. CommunityRole) are refused at registration."
+          "description": "The predicate IRI the community accepts, compared as an exact string. Always an absolute IRI: a DTG VSC predicate registry IRI (e.g. `https://registry.trustoverip.org/dtg/vsc/vetted/1`) or a community-namespace IRI defined in the registry's predicate definition format. The four core predicates — endorses/1, witnessed/1, vetted/1 and presented/1 under `https://registry.trustoverip.org/dtg/vsc/` — are seeded when the community starts. The reserved values `IdentityVerificationCredential` and `role:vetter`, which name the other kinds of record vtc/endorsements/* keeps, are never registered."
         },
         "description": {
           "type": "string",
@@ -188,7 +192,7 @@ export const RESPONSE_PAYLOAD_SCHEMA = {
         },
         "claimSchema": {
           "type": "object",
-          "description": "Optional JSON Schema the endorsement's claims must satisfy (opaque here)."
+          "description": "Optional JSON Schema a statement's `credentialSubject.object.value` must satisfy (opaque here) — for a registry predicate, the object schema its profile publishes."
         },
         "createdAt": {
           "type": "string",

package/src/vtc/endorsements/issue/0.1/payload.ts

@@ -8,15 +8,15 @@ import type { CredentialId, CredentialReference, Endorsement, Ext } from "../../
 
 export interface VTCEndorsementsIssuePayload {
   /**
-   * DID of the endorsement's subject (becomes credentialSubject.id).
+   * DID of the statement's subject (becomes credentialSubject.id).
    */
   subjectDid: string;
   /**
-   * A type already registered via vtc/endorsement-types/register; unregistered types are refused.
+   * The predicate IRI the statement carries as `credentialSubject.predicate` — `https://registry.trustoverip.org/dtg/vsc/endorses/1` for a favourable claim with community-defined content, or another predicate the community registered. It MUST already be registered via vtc/endorsement-types/register; unregistered predicates are refused. The one non-IRI value accepted is the reserved `IdentityVerificationCredential`, which mints the community's identity-verification credential instead of a statement.
    */
   typeUri: string;
   /**
-   * The claim body to attest. Capped at 8 KiB serialised, and validated against the type's claimSchema when it declares one.
+   * The claim body to attest, issued as the statement's `credentialSubject.object.value` — or, for `IdentityVerificationCredential`, as members of `credentialSubject` beside `id`, in which case it MUST NOT itself carry `id`. Capped at 8 KiB serialised, and validated against the registered predicate's claimSchema when it declares one.
    */
   claim: {};
   /**
@@ -28,7 +28,7 @@ export interface VTCEndorsementsIssuePayload {
 export interface VTCEndorsementsIssueResponsePayload {
   endorsement: Endorsement;
   /**
-   * The signed VEC just minted. Present only here: handing back the credential is the point of an issue call, and the issuer is the only party that can. Reads carry `endorsement.issued` — the reference — instead.
+   * The signed credential just minted. For `IdentityVerificationCredential`, a plain W3C VC — `@context` [credentials/v2] only, `type` [VerifiableCredential, IdentityVerificationCredential], not a DTGCredential — issued by the community to `subjectDid` with a revocation `credentialStatus`. Otherwise a DTG Verifiable Statement Credential (`StatementCredential`) issued by the community with `issuerScope` public, `credentialSubject.predicate` = `typeUri` and `credentialSubject.object.value` = `claim`. Present only here: handing back the credential is the point of an issue call, and the issuer is the only party that can. Reads carry `endorsement.issued` — the reference — instead.
    */
   credential: {};
   ext?: Ext;
@@ -73,18 +73,18 @@ export const PAYLOAD_SCHEMA = {
     "subjectDid": {
       "type": "string",
       "pattern": "^did:",
-      "description": "DID of the endorsement's subject (becomes credentialSubject.id)."
+      "description": "DID of the statement's subject (becomes credentialSubject.id)."
     },
     "typeUri": {
       "type": "string",
       "minLength": 1,
       "maxLength": 512,
-      "description": "A type already registered via vtc/endorsement-types/register; unregistered types are refused."
+      "description": "The predicate IRI the statement carries as `credentialSubject.predicate` — `https://registry.trustoverip.org/dtg/vsc/endorses/1` for a favourable claim with community-defined content, or another predicate the community registered. It MUST already be registered via vtc/endorsement-types/register; unregistered predicates are refused. The one non-IRI value accepted is the reserved `IdentityVerificationCredential`, which mints the community's identity-verification credential instead of a statement."
     },
     "claim": {
       "type": "object",
       "minProperties": 1,
-      "description": "The claim body to attest. Capped at 8 KiB serialised, and validated against the type's claimSchema when it declares one."
+      "description": "The claim body to attest, issued as the statement's `credentialSubject.object.value` — or, for `IdentityVerificationCredential`, as members of `credentialSubject` beside `id`, in which case it MUST NOT itself carry `id`. Capped at 8 KiB serialised, and validated against the registered predicate's claimSchema when it declares one."
     },
     "validitySeconds": {
       "type": "integer",
@@ -111,7 +111,7 @@ export const PAYLOAD_SCHEMA = {
         },
         "credential": {
           "type": "object",
-          "description": "The signed VEC just minted. Present only here: handing back the credential is the point of an issue call, and the issuer is the only party that can. Reads carry `endorsement.issued` — the reference — instead."
+          "description": "The signed credential just minted. For `IdentityVerificationCredential`, a plain W3C VC — `@context` [credentials/v2] only, `type` [VerifiableCredential, IdentityVerificationCredential], not a DTGCredential — issued by the community to `subjectDid` with a revocation `credentialStatus`. Otherwise a DTG Verifiable Statement Credential (`StatementCredential`) issued by the community with `issuerScope` public, `credentialSubject.predicate` = `typeUri` and `credentialSubject.object.value` = `claim`. Present only here: handing back the credential is the point of an issue call, and the issuer is the only party that can. Reads carry `endorsement.issued` — the reference — instead."
         },
         "ext": {
           "$ref": "#/$defs/Ext"
@@ -144,31 +144,31 @@ export const PAYLOAD_SCHEMA = {
         "endorsementId": {
           "type": "string",
           "minLength": 1,
-          "description": "Community-scoped identifier for this endorsement row."
+          "description": "Community-scoped identifier for this row. The name is legacy; it identifies a statement, and vtc/endorsements/revoke also takes the `endorsementId` of a role credential issued by vtc/vetting/vetters/grant."
         },
         "typeUri": {
           "type": "string",
           "minLength": 1,
           "maxLength": 512,
-          "description": "The registered endorsement type this VEC asserts; see vtc/endorsement-types/*."
+          "description": "What the row records. A registered predicate IRI: a statement (StatementCredential) whose `credentialSubject.predicate` it is — see vtc/endorsement-types/*. `role:vetter`: a vetter role credential (Verifiable Authority Credential) issued by vtc/vetting/vetters/grant. `IdentityVerificationCredential`: the community's identity-verification credential, a plain W3C VC (not a DTGCredential). The two reserved values are not IRIs, so they never collide with a registered predicate."
         },
         "subjectDid": {
           "type": "string",
           "pattern": "^did:",
-          "description": "DID of the endorsement's subject (becomes credentialSubject.id)."
+          "description": "DID of the statement's subject (becomes credentialSubject.id)."
         },
         "claim": {
           "type": "object",
-          "description": "The attested claim body, validated against the endorsement type's claimSchema when it declares one."
+          "description": "The attested claim body — the statement's `credentialSubject.object.value` — validated against the registered predicate's claimSchema when it declares one."
         },
         "issued": {
           "$ref": "#/$defs/CredentialReference",
-          "description": "A pointer to the issued VEC — its identifier and lifetime, not its bytes. `endorsements/issue` additionally returns the credential itself, because that is the one call whose caller has no other way to receive it."
+          "description": "A pointer to the issued statement credential — its identifier and lifetime, not its bytes. `endorsements/issue` additionally returns the credential itself, because that is the one call whose caller has no other way to receive it."
         },
         "statusListIndex": {
           "type": "integer",
           "minimum": 0,
-          "description": "The endorsement's slot on the community's shared Revocation status list. Published, so a foreign verifier can check revocation without contacting this community."
+          "description": "The statement's slot on the community's shared Revocation status list, referenced by its `credentialStatus`. Published, so a foreign verifier can check revocation without contacting this community."
         },
         "revokedAt": {
           "type": [
@@ -176,7 +176,7 @@ export const PAYLOAD_SCHEMA = {
             "null"
           ],
           "format": "date-time",
-          "description": "When the endorsement was revoked, or null while live."
+          "description": "When the statement was revoked, or null while live."
         }
       }
     },
@@ -238,7 +238,7 @@ export const RESPONSE_PAYLOAD_SCHEMA = {
         },
         "credential": {
           "type": "object",
-          "description": "The signed VEC just minted. Present only here: handing back the credential is the point of an issue call, and the issuer is the only party that can. Reads carry `endorsement.issued` — the reference — instead."
+          "description": "The signed credential just minted. For `IdentityVerificationCredential`, a plain W3C VC — `@context` [credentials/v2] only, `type` [VerifiableCredential, IdentityVerificationCredential], not a DTGCredential — issued by the community to `subjectDid` with a revocation `credentialStatus`. Otherwise a DTG Verifiable Statement Credential (`StatementCredential`) issued by the community with `issuerScope` public, `credentialSubject.predicate` = `typeUri` and `credentialSubject.object.value` = `claim`. Present only here: handing back the credential is the point of an issue call, and the issuer is the only party that can. Reads carry `endorsement.issued` — the reference — instead."
         },
         "ext": {
           "$ref": "#/$defs/Ext"
@@ -271,31 +271,31 @@ export const RESPONSE_PAYLOAD_SCHEMA = {
         "endorsementId": {
           "type": "string",
           "minLength": 1,
-          "description": "Community-scoped identifier for this endorsement row."
+          "description": "Community-scoped identifier for this row. The name is legacy; it identifies a statement, and vtc/endorsements/revoke also takes the `endorsementId` of a role credential issued by vtc/vetting/vetters/grant."
         },
         "typeUri": {
           "type": "string",
           "minLength": 1,
           "maxLength": 512,
-          "description": "The registered endorsement type this VEC asserts; see vtc/endorsement-types/*."
+          "description": "What the row records. A registered predicate IRI: a statement (StatementCredential) whose `credentialSubject.predicate` it is — see vtc/endorsement-types/*. `role:vetter`: a vetter role credential (Verifiable Authority Credential) issued by vtc/vetting/vetters/grant. `IdentityVerificationCredential`: the community's identity-verification credential, a plain W3C VC (not a DTGCredential). The two reserved values are not IRIs, so they never collide with a registered predicate."
         },
         "subjectDid": {
           "type": "string",
           "pattern": "^did:",
-          "description": "DID of the endorsement's subject (becomes credentialSubject.id)."
+          "description": "DID of the statement's subject (becomes credentialSubject.id)."
         },
         "claim": {
           "type": "object",
-          "description": "The attested claim body, validated against the endorsement type's claimSchema when it declares one."
+          "description": "The attested claim body — the statement's `credentialSubject.object.value` — validated against the registered predicate's claimSchema when it declares one."
         },
         "issued": {
           "$ref": "#/$defs/CredentialReference",
-          "description": "A pointer to the issued VEC — its identifier and lifetime, not its bytes. `endorsements/issue` additionally returns the credential itself, because that is the one call whose caller has no other way to receive it."
+          "description": "A pointer to the issued statement credential — its identifier and lifetime, not its bytes. `endorsements/issue` additionally returns the credential itself, because that is the one call whose caller has no other way to receive it."
         },
         "statusListIndex": {
           "type": "integer",
           "minimum": 0,
-          "description": "The endorsement's slot on the community's shared Revocation status list. Published, so a foreign verifier can check revocation without contacting this community."
+          "description": "The statement's slot on the community's shared Revocation status list, referenced by its `credentialStatus`. Published, so a foreign verifier can check revocation without contacting this community."
         },
         "revokedAt": {
           "type": [
@@ -303,7 +303,7 @@ export const RESPONSE_PAYLOAD_SCHEMA = {
             "null"
           ],
           "format": "date-time",
-          "description": "When the endorsement was revoked, or null while live."
+          "description": "When the statement was revoked, or null while live."
         }
       }
     },

package/src/vtc/endorsements/list/0.1/payload.ts

@@ -8,7 +8,7 @@ import type { CredentialId, CredentialReference, Endorsement, Ext } from "../../
 
 export interface VTCEndorsementsListPayload {
   /**
-   * Filter to endorsements of this registered type.
+   * Filter to rows of this kind: a registered predicate IRI (statements whose `credentialSubject.predicate` it is), `IdentityVerificationCredential`, or `role:vetter`.
    */
   typeUri?: string;
   /**
@@ -77,7 +77,7 @@ export const PAYLOAD_SCHEMA = {
       "type": "string",
       "minLength": 1,
       "maxLength": 512,
-      "description": "Filter to endorsements of this registered type."
+      "description": "Filter to rows of this kind: a registered predicate IRI (statements whose `credentialSubject.predicate` it is), `IdentityVerificationCredential`, or `role:vetter`."
     },
     "subjectDid": {
       "type": "string",
@@ -163,31 +163,31 @@ export const PAYLOAD_SCHEMA = {
         "endorsementId": {
           "type": "string",
           "minLength": 1,
-          "description": "Community-scoped identifier for this endorsement row."
+          "description": "Community-scoped identifier for this row. The name is legacy; it identifies a statement, and vtc/endorsements/revoke also takes the `endorsementId` of a role credential issued by vtc/vetting/vetters/grant."
         },
         "typeUri": {
           "type": "string",
           "minLength": 1,
           "maxLength": 512,
-          "description": "The registered endorsement type this VEC asserts; see vtc/endorsement-types/*."
+          "description": "What the row records. A registered predicate IRI: a statement (StatementCredential) whose `credentialSubject.predicate` it is — see vtc/endorsement-types/*. `role:vetter`: a vetter role credential (Verifiable Authority Credential) issued by vtc/vetting/vetters/grant. `IdentityVerificationCredential`: the community's identity-verification credential, a plain W3C VC (not a DTGCredential). The two reserved values are not IRIs, so they never collide with a registered predicate."
         },
         "subjectDid": {
           "type": "string",
           "pattern": "^did:",
-          "description": "DID of the endorsement's subject (becomes credentialSubject.id)."
+          "description": "DID of the statement's subject (becomes credentialSubject.id)."
         },
         "claim": {
           "type": "object",
-          "description": "The attested claim body, validated against the endorsement type's claimSchema when it declares one."
+          "description": "The attested claim body — the statement's `credentialSubject.object.value` — validated against the registered predicate's claimSchema when it declares one."
         },
         "issued": {
           "$ref": "#/$defs/CredentialReference",
-          "description": "A pointer to the issued VEC — its identifier and lifetime, not its bytes. `endorsements/issue` additionally returns the credential itself, because that is the one call whose caller has no other way to receive it."
+          "description": "A pointer to the issued statement credential — its identifier and lifetime, not its bytes. `endorsements/issue` additionally returns the credential itself, because that is the one call whose caller has no other way to receive it."
         },
         "statusListIndex": {
           "type": "integer",
           "minimum": 0,
-          "description": "The endorsement's slot on the community's shared Revocation status list. Published, so a foreign verifier can check revocation without contacting this community."
+          "description": "The statement's slot on the community's shared Revocation status list, referenced by its `credentialStatus`. Published, so a foreign verifier can check revocation without contacting this community."
         },
         "revokedAt": {
           "type": [
@@ -195,7 +195,7 @@ export const PAYLOAD_SCHEMA = {
             "null"
           ],
           "format": "date-time",
-          "description": "When the endorsement was revoked, or null while live."
+          "description": "When the statement was revoked, or null while live."
         }
       }
     },
@@ -302,31 +302,31 @@ export const RESPONSE_PAYLOAD_SCHEMA = {
         "endorsementId": {
           "type": "string",
           "minLength": 1,
-          "description": "Community-scoped identifier for this endorsement row."
+          "description": "Community-scoped identifier for this row. The name is legacy; it identifies a statement, and vtc/endorsements/revoke also takes the `endorsementId` of a role credential issued by vtc/vetting/vetters/grant."
         },
         "typeUri": {
           "type": "string",
           "minLength": 1,
           "maxLength": 512,
-          "description": "The registered endorsement type this VEC asserts; see vtc/endorsement-types/*."
+          "description": "What the row records. A registered predicate IRI: a statement (StatementCredential) whose `credentialSubject.predicate` it is — see vtc/endorsement-types/*. `role:vetter`: a vetter role credential (Verifiable Authority Credential) issued by vtc/vetting/vetters/grant. `IdentityVerificationCredential`: the community's identity-verification credential, a plain W3C VC (not a DTGCredential). The two reserved values are not IRIs, so they never collide with a registered predicate."
         },
         "subjectDid": {
           "type": "string",
           "pattern": "^did:",
-          "description": "DID of the endorsement's subject (becomes credentialSubject.id)."
+          "description": "DID of the statement's subject (becomes credentialSubject.id)."
         },
         "claim": {
           "type": "object",
-          "description": "The attested claim body, validated against the endorsement type's claimSchema when it declares one."
+          "description": "The attested claim body — the statement's `credentialSubject.object.value` — validated against the registered predicate's claimSchema when it declares one."
         },
         "issued": {
           "$ref": "#/$defs/CredentialReference",
-          "description": "A pointer to the issued VEC — its identifier and lifetime, not its bytes. `endorsements/issue` additionally returns the credential itself, because that is the one call whose caller has no other way to receive it."
+          "description": "A pointer to the issued statement credential — its identifier and lifetime, not its bytes. `endorsements/issue` additionally returns the credential itself, because that is the one call whose caller has no other way to receive it."
         },
         "statusListIndex": {
           "type": "integer",
           "minimum": 0,
-          "description": "The endorsement's slot on the community's shared Revocation status list. Published, so a foreign verifier can check revocation without contacting this community."
+          "description": "The statement's slot on the community's shared Revocation status list, referenced by its `credentialStatus`. Published, so a foreign verifier can check revocation without contacting this community."
         },
         "revokedAt": {
           "type": [
@@ -334,7 +334,7 @@ export const RESPONSE_PAYLOAD_SCHEMA = {
             "null"
           ],
           "format": "date-time",
-          "description": "When the endorsement was revoked, or null while live."
+          "description": "When the statement was revoked, or null while live."
         }
       }
     },

package/src/vtc/endorsements/revoke/0.1/payload.ts

@@ -17,7 +17,7 @@ export interface VTCEndorsementsRevokePayload {
 export interface VTCEndorsementsRevokeResponsePayload {
   endorsementId: string;
   /**
-   * The registry-wide revocation receipt for the underlying VEC.
+   * The registry-wide revocation receipt for the underlying credential — the statement credential, the identity-verification credential, or a vetter role credential (VAC).
    */
   revocation: RevocationReceipt;
   /**
@@ -92,7 +92,7 @@ export const PAYLOAD_SCHEMA = {
         },
         "revocation": {
           "$ref": "#/$defs/RevocationReceipt",
-          "description": "The registry-wide revocation receipt for the underlying VEC."
+          "description": "The registry-wide revocation receipt for the underlying credential — the statement credential, the identity-verification credential, or a vetter role credential (VAC)."
         },
         "statusListIndex": {
           "type": "integer",
@@ -167,7 +167,7 @@ export const RESPONSE_PAYLOAD_SCHEMA = {
         },
         "revocation": {
           "$ref": "#/$defs/RevocationReceipt",
-          "description": "The registry-wide revocation receipt for the underlying VEC."
+          "description": "The registry-wide revocation receipt for the underlying credential — the statement credential, the identity-verification credential, or a vetter role credential (VAC)."
         },
         "statusListIndex": {
           "type": "integer",