March 1, 2026 · 10:28 am
↓ Jump to Comments

Web 7.0 DID Interface Definition Language (DIDIDL) 0.12 — Draft Specification

Status: Draft
Version: 1.0
License: Apache 2.0
Editors: Michael Herman, Chief Digital Officer, Web 7.0 Foundation

1. Abstract

DIDIDL defines a transport-neutral, message-type–centric capability description format for agents using using DIDComm.

DIDIDL enables agents to:

  • Publish typed operations grouped under process capabilities
  • Describe request, response, and error schemas
  • Support machine-readable discovery
  • Enable client generation and validation

DIDIDL does not introduce HTTP routing semantics.

1.1 Key Concepts

  • Discovery DIDComm Message DIDs
    • did:web7:{process-name}:{version}:query-capabilities
    • did:web7:{process-name}:{version}:disclose-capabilities
    • did:web7:{process-name}:{version}:capabilities:{capability-name}:query-capability
    • did:web7:{process-name}:{version}:capabilities:{capability-name}:disclose-capability
  • Process Capability DID
    • did:web7:{process-name}:{version}:capabilities:{capability-name}
  • Process Capability Operation DID
    • did:web7:{process-name}:{version}:operations:{capability-name}:{operation-name}

2. Terminology

TermDefinition
AgentA DIDComm-enabled entity
Process Capability (Capability)A grouping of operations representing a business or functional process
Process Capability Operation (Operation)A DIDComm message type representing a callable function
SchemaA JSON Schema definition conforming to JSON Schema
Process DIDIDL Document (DIDIDL Document)JSON object conforming to this specification

Normative keywords MUST, SHOULD, MAY follow RFC 2119.

3. Canonical DID Patterns

DID TypePatternExample
Process Capability DIDdid:web7:{process-name}:{version}:capabilities:{capability-name}:did:web7:user-onboarding:1.0:capabilities:enrollment
Process Capability Operation DIDdid:web7:{process-name}:{version}:operations:{capability-name}:{operation-name}did:web7:user-onboarding:1.0:operatons:enrollment:verify-email
Discovery Query Process Capabilitiesdid:web7:{process-name}:{version}:query-capabilitiesdid:web7:user-onboarding:1.0:query-capabilities
Discovery Disclose Process Capabilitiesdid:web7:{process-name}:{version}:disclose-capabilitiesdid:web7:user-onboarding:1.0:disclose-capabilities
Discovery Query Process Capability Operationsdid:web7:{process-name}:{version}:capabilties:{capability-name}:query-capabilitydid:web7:user-onboarding:1.0:capabilities:enrollment:query-capability
Discovery Disclose Process Capability Operationsdid:web7:{process-name}:{version}:capabilities:{capability-name}:disclose-capabilitydid:web7:user-onboarding:1.0:capabilities:enrollment:disclose-capability

4. DIDIDL Document Structure

4a. Process Capabilities

{
  "dididl": "1.0",
  "agent": "did:example:agent123",
  "capabilities": [...],
  "schemas": {...}
}

All operations MUST be nested under exactly one process capability.

4b. Process Capability Operations

{
  "id": "did:web7:user-onboarding:1.0:capabilities:enrollment",
  "name": "User Onboarding-Enrollment",
  "version": "1.0",
  "description": "Handles user lifecycle initiation",
  "operations": [
    {
      "type": "did:web7:user-onboarding:1.0:operations:enrollment:create-user",
      "request": "#/schemas/CreateUserRequest",
      "response": "#/schemas/UserDto"
    },
    {
      "type": "did:web7:user-onboarding:1.0:operations:enrollment:verify-email",
      "request": "#/schemas/VerifyEmailRequest",
      "response": "#/schemas/VerifyEmailResponse"
    }
  ]
}

Rules:

  • Process Capability DIDs MUST follow the pattern: did:web7:{process-name}:{version}:capabilities
  • Each operation MUST belong to exactly one capability
  • Operation DIDs are capability-scoped: did:web7:{capability-name}:{version}:{operation-name}

4c. Process Capability Operation

{
  "type": "did:web7:user-api:1.0:create-user",
  "request": "#/schemas/CreateUserRequest",
  "response": "#/schemas/UserDto",
  "errors": ["#/schemas/ValidationError"]
}

Rules:

  • Operation DIDs MUST be unique within the agent
  • Versioning MUST be encoded in the DID
  • Request and response schemas MUST be referenced by JSON pointer

5. Discovery Protocol

5.1 Query Capabilities

Request

{
  "type": "did:web7:user-onboarding:1.0:query-capabilities"
}

Response

{
  "type": "did:web7:user-onboarding:1.0:disclose-capabilities",
  "capabilities": [
    {
      "id": "did:web7:user-onboarding:1.0:capabilities",
      "name": "User Onboarding",
      "version": "1.0",
      "description": "Handles user lifecycle initiation"
    },
    {
      "id": "did:web7:credential-issuance:2.0:capabilities",
      "name": "Credential Issuance",
      "version": "2.0"
    }
  ]
}

5.2 Query a Specific Capability

Request

{
  "type": "did:web7:user-onboarding:1.0:query-capability",
  "id": "did:web7:user-onboarding:1.0:capabilities"
}

Response

{
  "type": "did:web7:user-onboarding:1.0:disclose-capability",
  "capability": {
    "id": "did:web7:user-onboarding:1.0:capabilities",
    "name": "User Onboarding",
    "version": "1.0",
    "operations": [
      {
        "type": "did:web7:user-api:1.0:create-user",
        "request": "#/schemas/CreateUserRequest",
        "response": "#/schemas/UserDto"
      },
      {
        "type": "did:web7:user-api:1.0:verify-email",
        "request": "#/schemas/VerifyEmailRequest",
        "response": "#/schemas/VerifyEmailResponse"
      }
    ],
    "schemas": {...}
  }
}

6. Normative Requirements

  1. Each operation MUST appear in exactly one process capability.
  2. Process Capability DIDs MUST be unique within the agent.
  3. Operation DIDs are capability-scoped and MUST be unique.
  4. Union of all process capabilities MUST form a disjoint partition of operations.
  5. Schemas included in capability disclosure MUST only include referenced schemas.
  6. DIDComm authentication MUST protect all DIDIDL exchanges.
  7. Version changes that introduce breaking schema modifications MUST increment the major version in the DID.

7. Example Complete DIDIDL Document

{
  "dididl": "1.0",
  "agent": "did:example:agent123",
  "capabilities": [
    {
      "id": "did:web7:user-onboarding:1.0:capabilities",
      "name": "User Onboarding",
      "version": "1.0",
      "operations": [
        {
          "type": "did:web7:user-api:1.0:create-user",
          "request": "#/schemas/CreateUserRequest",
          "response": "#/schemas/UserDto"
        },
        {
          "type": "did:web7:user-api:1.0:verify-email",
          "request": "#/schemas/VerifyEmailRequest",
          "response": "#/schemas/VerifyEmailResponse"
        }
      ]
    }
  ],
  "schemas": {
    "CreateUserRequest": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "email": { "type": "string" }
      },
      "required": ["email"]
    },
    "VerifyEmailRequest": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "token": { "type": "string" }
      },
      "required": ["token"]
    },
    "VerifyEmailResponse": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "success": { "type": "boolean" }
      },
      "required": ["success"]
    },
    "UserDto": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "email": { "type": "string" }
      },
      "required": ["id", "email"]
    }
  }
}

Leave a comment

Filed under Uncategorized

Tagged as , , , ,

Leave a comment