Add serviceUrl field to Agent specification as DIDComm endpoint fallback

- Add serviceUrl to Agent attributes in TAIP-5 as optional DIDComm endpoint
- Update TAIP-15 Connect message to clarify serviceUrl security requirements
- Enhance TypeScript Agent interface with proper serviceUrl documentation
- Update messages.md Agent data structure with serviceUrl field reference
- Add DIDComm endpoint resolution guidance in agents.md
- Update party and transaction documentation with schema.org enhancements
- Specify security requirements: HTTPS only, DID document endpoints prioritized
- Target use case: self-hosted and decentralized agents without reliable DID hosting

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: pelle

TAIPs/taip-15.md

@@ -51,7 +51,7 @@ A message sent by an agent requesting connection to another agent:
   - `@id` - REQUIRED string DID of the requesting agent. If the `agent` object is included, the `@id` MUST match the `from` field of the surrounding DIDComm message
   - `name` - OPTIONAL string human-readable name of the agent
   - `type` - OPTIONAL string type of agent (e.g. "ServiceAgent", "WalletAgent")
-  - `serviceUrl` - OPTIONAL string URL for the agent's DIDComm endpoint
+  - `serviceUrl` - OPTIONAL string URL for the agent's DIDComm endpoint. This field SHOULD only be used as a fallback when no DIDComm service endpoint is resolvable from the agent's DID document. This is particularly useful for self-hosted and decentralized agents that may not have reliable DID document hosting. For security purposes, this field SHOULD be ignored if a valid DIDComm service endpoint is already listed in the DID document
 - `principal` - REQUIRED [TAIP-6] Party object representing the party the agent acts on behalf of:
   - `@id` - REQUIRED string DID or IRI of the principal party
   - Additional attributes MAY be included as defined in [TAIP-6], such as country code, merchant category code, or other party metadata
@@ -273,6 +273,11 @@ sequenceDiagram
 - Authorization MUST be performed through secure, authenticated channels
 - Authorization URLs MUST use HTTPS and include CSRF protection
 - Connection identifiers should be unique and unpredictable
+- When using `serviceUrl` in the agent object:
+  - The URL MUST use HTTPS for security
+  - Agents MUST prioritize DIDComm service endpoints from the DID document over the `serviceUrl` field
+  - The `serviceUrl` SHOULD only be used when no valid DIDComm service endpoint is resolvable from the DID document
+  - Agents SHOULD validate that the `serviceUrl` actually belongs to the DID holder through appropriate verification mechanisms
 
 ## Rationale
 

TAIPs/taip-5.md

@@ -85,6 +85,7 @@ The following are the attributes of an object in the `agents` array:
 - `description` - OPTIONAL a string containing a description of the agent (based on [schema.org/Organization](https://schema.org/Organization))
 - `email` - OPTIONAL a string containing the agent's contact email address (based on [schema.org/Organization](https://schema.org/Organization))
 - `telephone` - OPTIONAL a string containing the agent's contact telephone number (based on [schema.org/Organization](https://schema.org/Organization))
+- `serviceUrl` - OPTIONAL a string URL for the agent's DIDComm endpoint. This field SHOULD only be used as a fallback when no DIDComm service endpoint is resolvable from the agent's DID document. Particularly useful for self-hosted and decentralized agents. For security purposes, this field SHOULD be ignored if a valid DIDComm service endpoint is already listed in the DID document
 
 When using schema.org types in the `@type` field, implementations can leverage the rich vocabulary and tooling available for schema.org, enabling better interoperability with web standards and search engines.
 
@@ -134,6 +135,15 @@ There are three primary ways of interacting with agents:
 - End-user-controlled software, such as self-hosted wallets, can receive [TAIP-2 DIDComm Messages][TAIP-2] in an interactive User Interface using [DIDComm Out of Band][DIDCommOOB]
 - Decentralized Protocol agents, such as DeFi protocols that can only communicate through blockchain transactions, possibly through an implementation of [CAIP-74]
 
+### DIDComm Endpoint Resolution
+
+TAP agents resolve DIDComm endpoints using the following priority order:
+
+1. **DID Document Service Endpoints**: Primary method using the agent's DID document service section
+2. **Fallback Service URL**: Optional `serviceUrl` field in agent metadata when DID document endpoints are unavailable
+
+The `serviceUrl` field is particularly useful for self-hosted and decentralized agents that may not have reliable DID document hosting infrastructure. For security purposes, agents MUST prioritize DID document service endpoints over the fallback `serviceUrl` when both are available, and SHOULD validate that the `serviceUrl` actually belongs to the DID holder through appropriate verification mechanisms.
+
 ### Identifying Agents
 
 DID Methods, implement different ways of creating and modifying Decentralized Identifiers. The recommendation is to use the following two DID Methods:
@@ -640,6 +650,16 @@ As an example a message from `did:web:originator.vasp` proves that someone allow
 
 As such internal and external trust tools need to be handled. This is out of scope of this proposal.
 
+### Service URL Security
+
+When using the optional `serviceUrl` field for DIDComm endpoint fallback:
+
+- Agents MUST prioritize DID document service endpoints over `serviceUrl` when both are available
+- The `serviceUrl` MUST use HTTPS for secure communication
+- Agents SHOULD validate that the `serviceUrl` actually belongs to the DID holder through appropriate verification mechanisms
+- The `serviceUrl` SHOULD only be used when no valid DIDComm service endpoint is resolvable from the DID document
+- Implementations SHOULD log when fallback URLs are used for security monitoring purposes
+
 ## Privacy Considerations
 <!--Please add an explicit list of intra-actor assumptions and known risk factors if applicable. Any normative definition of an interface requires these to be implementable; assumptions and risks should be at both individual interaction/use-case scale and systemically, should the interface specified gain ecosystem-namespace adoption. -->
 

agents.md

@@ -136,6 +136,19 @@ TAP agents can support multiple DID methods to enable flexible identity scenario
 
 Additional DID methods can be supported based on specific implementation needs.
 
+## Agent Metadata
+
+TAP agents can include rich metadata based on schema.org/Organization standards to provide better identification and discovery:
+
+- **Name**: Human-readable name of the agent organization
+- **URL**: Website address of the agent
+- **Logo**: URL to the agent's logo image for visual identification
+- **Description**: Textual description of the agent's services and capabilities
+- **Contact Information**: Email and telephone contact details
+- **Type Information**: JSON-LD type identifiers (typically "https://schema.org/Organization")
+
+This metadata enhances the user experience by providing clear identification of service providers while maintaining compatibility with existing implementations.
+
 ## Agent-to-Agent Communication
 
 Agents communicate with each other using the DIDComm v2 messaging protocol, which provides:
@@ -145,6 +158,15 @@ Agents communicate with each other using the DIDComm v2 messaging protocol, whic
 - **Asynchronous Messaging**: Messages can be sent and processed asynchronously
 - **Transport Flexibility**: Support for HTTPS, WebSockets, and other transport methods
 
+### DIDComm Endpoint Resolution
+
+TAP agents resolve DIDComm endpoints in the following priority order:
+
+1. **DID Document Service Endpoints**: Primary method using the agent's DID document
+2. **Fallback Service URL**: Optional `serviceUrl` field in agent metadata when DID document endpoints are unavailable
+
+The `serviceUrl` field is particularly useful for self-hosted and decentralized agents that may not have reliable DID document hosting. For security purposes, agents should prioritize DID document endpoints over the fallback service URL when both are available.
+
 ## Implementation Considerations
 
 When designing TAP agents:
@@ -157,4 +179,6 @@ When designing TAP agents:
 
 ## Technical Integration
 
-For technical details on agent data structures and message formats, see the [full message reference](/messages/#participant-management-messages).
+Agents can be enhanced with schema.org attributes to provide richer organizational metadata while maintaining backward compatibility. The schema.org vocabulary enables better integration with web standards and enhances user experience through clearer service provider identification.
+
+For technical details on agent data structures, message formats, and the complete list of supported schema.org attributes, see the [full message reference](/messages/#participant-management-messages).

messages.md

@@ -1399,20 +1399,17 @@ Represents a participant in a transaction (originator or beneficiary).
 | Attribute | Type | Required | Status | Description |
 |-----------|------|----------|---------|-------------|
 | @id | string | Yes | Review ([TAIP-6]) | DID or IRI of the party |
-| lei:leiCode | string | No | Draft ([TAIP-11]) | LEI code for legal entities. Must be a 20-character alpha-numeric string conforming to ISO 17442 |
-| name | string | No | Review ([TAIP-6]) | Human-readable name |
+| @type | string | No | Review ([TAIP-6]) | JSON-LD type identifier. Most commonly "https://schema.org/Organization" for institutional parties or "https://schema.org/Person" for individual parties |
+| leiCode | string | No | Draft ([TAIP-11]) | LEI code for legal entities. Must be a 20-character alpha-numeric string conforming to ISO 17442 |
+| name | string | No | Review ([TAIP-6]) | Human-readable name (based on schema.org/Organization or schema.org/Person) |
 | nameHash | string | No | Draft ([TAIP-12]) | SHA-256 hash of the normalized name (uppercase, no whitespace) |
 | mcc | string | No | Review ([TAIP-14]) | Merchant Category Code (ISO 18245) that identifies the type of business (e.g., "5411" for grocery stores) |
+| url | string | No | Review ([TAIP-6]) | URL pointing to the party's website (based on schema.org/Organization) |
+| logo | string | No | Review ([TAIP-6]) | URL pointing to the party's logo image (based on schema.org/Organization) |
+| description | string | No | Review ([TAIP-6]) | Description of the party (based on schema.org/Organization) |
+| email | string | No | Review ([TAIP-6]) | Contact email address (based on schema.org/Organization or schema.org/Person) |
+| telephone | string | No | Review ([TAIP-6]) | Contact telephone number (based on schema.org/Organization or schema.org/Person) |
 
-When including an LEI, the Party MUST include the appropriate JSON-LD context:
-
-```json
-{
-  "@context": { "lei": "https://schema.org/leiCode" },
-  "@id": "did:web:example.vasp.com",
-  "lei:leiCode": "5493001KJTIIGC8Y1R12"
-}
-```
 
 If a customer (originator or beneficiary) is a legal entity and has an LEI, that LEI SHOULD be included in their Party. For institutions (VASPs), if they have an LEI, they MUST include it in their Party.
 
@@ -1475,6 +1472,9 @@ Each line item in the `lineItems` array contains:
 |-----------|------|----------|---------|-------------|
 | id | string | Yes | Review ([TAIP-16]) | Unique identifier for the line item within the invoice |
 | description | string | Yes | Review ([TAIP-16]) | Description of the item or service |
+| name | string | No | Review ([TAIP-16]) | Product name (based on schema.org/Product). If not provided, description serves as the display name |
+| image | string | No | Review ([TAIP-16]) | URL to an image of the product (based on schema.org/Product) |
+| url | string | No | Review ([TAIP-16]) | URL to the product page (based on schema.org/Product) |
 | quantity | number | Yes | Review ([TAIP-16]) | Quantity of the item |
 | unitCode | string | No | Review ([TAIP-16]) | Unit of measure code (e.g., "EA" for each, "KGM" for kilogram) |
 | unitPrice | number | Yes | Review ([TAIP-16]) | Price per unit |
@@ -1535,8 +1535,16 @@ Represents a service involved in executing transactions.
 | Attribute | Type | Required | Status | Description |
 |-----------|------|----------|---------|-------------|
 | @id | string | Yes | Review ([TAIP-5]) | DID of the agent |
+| @type | string | No | Review ([TAIP-5]) | JSON-LD type identifier. Most commonly "https://schema.org/Organization" for institutional agents |
 | role | string | No | Review ([TAIP-5]) | Role of the agent (e.g., "SettlementAddress", "SourceAddress", "CustodialService") |
 | for | string or array of strings | No | Review ([TAIP-5]) | Reference to the Party or Parties this agent represents. Can be either a single DID string or an array of DID strings when the agent acts on behalf of multiple entities simultaneously |
+| name | string | No | Review ([TAIP-5]) | Name of the agent organization (based on schema.org/Organization) |
+| url | string | No | Review ([TAIP-5]) | URL pointing to the agent's website (based on schema.org/Organization) |
+| logo | string | No | Review ([TAIP-5]) | URL pointing to the agent's logo image (based on schema.org/Organization) |
+| description | string | No | Review ([TAIP-5]) | Description of the agent (based on schema.org/Organization) |
+| email | string | No | Review ([TAIP-5]) | Contact email address (based on schema.org/Organization) |
+| telephone | string | No | Review ([TAIP-5]) | Contact telephone number (based on schema.org/Organization) |
+| serviceUrl | string | No | Review ([TAIP-15]) | Optional DIDComm service endpoint URL. Should only be used as a fallback when no DIDComm service endpoint is resolvable from the agent's DID document. Particularly useful for self-hosted and decentralized agents |
 
 **Note:** Both `role` and `for` parameters are optional to support flexible agent configurations. The `role` parameter may be omitted when the agent's function is implicit from context or when using generic service agents. The `for` parameter may be omitted for standalone agents or when the relationship is established through other means.
 

packages/typescript/src/tap.ts

@@ -423,7 +423,13 @@ export interface Agent extends Partial<Organization> {
   policies?: Policies[];
 
   /**
-   * URL for requesting input by agent from a party.
+   * Optional DIDComm service endpoint URL
+   * This field SHOULD only be used as a fallback when no DIDComm service endpoint
+   * is resolvable from the agent's DID document. Particularly useful for self-hosted
+   * and decentralized agents. For security purposes, this field SHOULD be ignored
+   * if a valid DIDComm service endpoint is already listed in the DID document.
+   * 
+   * @example "https://agent.example.com/didcomm"
    */
   serviceUrl?: IRI;
 }

parties.md

@@ -38,11 +38,18 @@ Each party in TAP is identified through:
 
 Parties in TAP may have various attributes that describe their characteristics:
 
-1. **Name**: Human-readable identifier for the party
+1. **Name**: Human-readable identifier for the party (based on schema.org/Organization or schema.org/Person)
 2. **Legal Entity Identifier (LEI)**: For institutional parties, a globally recognized identifier
 3. **Merchant Category Code (MCC)**: Optional ISO 18245 code for merchant parties that identifies their business type (e.g., "5411" for grocery stores, "5812" for restaurants)
-4. **Contact Information**: Methods for reaching the party outside of the TAP protocol
-5. **Regulatory Status**: Information about regulatory compliance and licensing
+4. **Contact Information**: Methods for reaching the party outside of the TAP protocol, including:
+   - **URL**: Website address (based on schema.org/Organization)
+   - **Email**: Contact email address (based on schema.org/Organization or schema.org/Person) 
+   - **Telephone**: Contact phone number (based on schema.org/Organization or schema.org/Person)
+5. **Branding Information**: Visual identity elements:
+   - **Logo**: URL to the party's logo image (based on schema.org/Organization)
+   - **Description**: Textual description of the party (based on schema.org/Organization)
+6. **Type Information**: JSON-LD type identifiers (e.g., "https://schema.org/Organization" for institutions, "https://schema.org/Person" for individuals)
+7. **Regulatory Status**: Information about regulatory compliance and licensing
 
 ## Party Management Messages
 
@@ -78,4 +85,6 @@ When designing party support in TAP:
 
 ## Technical Integration
 
-For technical details on party data structures and message formats, see the [full message reference](/messages/#data-elements).
+Parties can be enhanced with schema.org attributes to provide richer metadata while maintaining compatibility with existing implementations. The schema.org vocabulary enables better interoperability with web standards and search engines.
+
+For technical details on party data structures, message formats, and the complete list of supported schema.org attributes, see the [full message reference](/messages/#data-elements).

transactions.md

@@ -44,6 +44,7 @@ The **Payment** message type extends TAP to support merchant payment scenarios w
 - **Customer Experience Focus**: Designed for consumer-friendly payment flows with clear merchant identification
 - **Merchant Classification**: Supports ISO 18245 Merchant Category Codes (MCC) for business type identification (e.g., restaurants, grocery stores)
 - **Flexible Settlement**: Supports flexible asset selection through the `supportedAssets` field, allowing customers to choose their preferred payment method
+- **Fallback Settlement Options**: Includes `fallbackSettlementAddresses` field supporting both blockchain (CAIP-10) and traditional payment systems (RFC 8905 PayTo URIs) for redundancy
 - **Invoice Support**: Includes comprehensive invoice functionality as defined in [TAIP-16](/TAIPs/taip-16.md), supporting detailed line items, tax information, and payment terms
 - **Policy Support**: Can include policy requirements (e.g., RequirePresentation) for customer information needed for the transaction