Skip to content

Commit fdf3d38

Browse files
pelleclaude
pelle
and
claude
committed
Add JSON Schema definitions for all TAP message types
This commit introduces comprehensive JSON Schema definitions for the Transaction Authorization Protocol (TAP), providing: - `/schemas/common/` - Base type definitions (CAIP types, DID types, ISO types) - `/schemas/data-structures/` - Reusable structures (Party, Agent, Policy, Invoice) - `/schemas/messages/` - All 16 TAP message type schemas - JSON Schema draft 2020-12 compliance - Resolvable URLs via GitHub Pages (https://taips.tap.rsvp/schemas/) - Validation script for test vectors - Complete type coverage for all TAP messages - Fixed Cancel interface to include required 'by' field - Removed obsolete Complete message type (replaced by Authorize in protocol) - Transaction: Transfer, Payment - Authorization: Authorize, Settle, Reject, Cancel, Revert - Agent Management: UpdateAgent, UpdateParty, AddAgents, ReplaceAgent, RemoveAgent - Relationships: ConfirmRelationship, UpdatePolicies - Connection: Connect, AuthorizationRequired, Out-of-Band Invitation These schemas enable automated validation, improved tooling support, and serve as authoritative references for TAP implementations. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 3f37531 commit fdf3d38

33 files changed

Lines changed: 2167 additions & 86 deletions

‎packages/typescript/src/tap.ts‎

Lines changed: 7 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -691,6 +691,12 @@ export interface Cancel extends TapMessageObject<"Cancel"> {
691691
* Human readable explanation
692692
*/
693693
reason?: string;
694+
695+
/**
696+
* DID of the agent initiating cancellation
697+
* Identifies who is cancelling the transaction
698+
*/
699+
by: DID;
694700
}
695701

696702
/**
@@ -1158,16 +1164,6 @@ export interface AuthorizationRequiredMessage
11581164
type: "https://tap.rsvp/schema/1.0#AuthorizationRequired";
11591165
}
11601166

1161-
/**
1162-
* Complete Message Wrapper
1163-
* DIDComm envelope for a Complete message.
1164-
*
1165-
* @see {@link https://github.com/TransactionAuthorizationProtocol/TAIPs/blob/main/TAIPs/taip-14.md | TAIP-14: Payments}
1166-
*/
1167-
export interface CompleteMessage extends DIDCommReply<Complete> {
1168-
type: "https://tap.rsvp/schema/1.0#Complete";
1169-
}
1170-
11711167
/**
11721168
* TAP Message
11731169
* Union type of all possible TAP messages.
@@ -1192,7 +1188,6 @@ export type TAPMessage =
11921188
| ConfirmRelationshipMessage
11931189
| UpdatePoliciesMessage
11941190
| ConnectMessage
1195-
| AuthorizationRequiredMessage
1196-
| CompleteMessage;
1191+
| AuthorizationRequiredMessage;
11971192

11981193
// All types and interfaces are now exported directly in their declarations

‎schemas/README.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# TAP JSON Schemas
2+
3+
This directory contains JSON Schema definitions for all Transaction Authorization Protocol (TAP) message types and data structures.
4+
5+
## Overview
6+
7+
The schemas are organized into three main categories:
8+
9+
- **`/common`** - Base type definitions (CAIP types, DID types, base structures)
10+
- **`/data-structures`** - Reusable data structures (Party, Agent, Policy, etc.)
11+
- **`/messages`** - Message type schemas for all TAP messages
12+
13+
All schemas are publicly accessible via GitHub Pages at:
14+
- Base URL: `https://taips.tap.rsvp/schemas/`
15+
- Example: `https://taips.tap.rsvp/schemas/messages/transfer.json`
16+
17+
## Schema Standards
18+
19+
All schemas follow:
20+
- JSON Schema draft 2020-12
21+
- Use `$id` for unique identification
22+
- Include detailed descriptions
23+
- Reference common definitions to avoid duplication
24+
25+
## Message Types
26+
27+
The following TAP message types have schemas defined:
28+
29+
### Transaction Messages
30+
- `transfer.json` - Initiates a virtual asset transfer
31+
- `payment.json` - Payment request with optional invoice
32+
33+
### Authorization Flow
34+
- `authorize.json` - Authorization request/response
35+
- `settle.json` - Settlement confirmation
36+
- `reject.json` - Transaction rejection
37+
- `cancel.json` - Transaction cancellation
38+
- `revert.json` - Transaction reversal request
39+
40+
### Agent Management
41+
- `update-agent.json` - Update agent details
42+
- `update-party.json` - Update party information
43+
- `add-agents.json` - Add new agents
44+
- `replace-agent.json` - Replace existing agent
45+
- `remove-agent.json` - Remove agent from transaction
46+
47+
### Relationship & Policy
48+
- `confirm-relationship.json` - Confirm party-agent relationship
49+
- `update-policies.json` - Update agent policies
50+
51+
### Connection Management
52+
- `connect.json` - Establish TAP connection
53+
- `authorization-required.json` - Request authorization
54+
- `out-of-band-invitation.json` - Out-of-band connection invitation
55+
56+
## Validation
57+
58+
To validate test vectors against schemas:
59+
60+
```bash
61+
# Install dependencies
62+
npm install
63+
64+
# Run validation
65+
npm run validate
66+
```
67+
68+
The validation script will:
69+
1. Load all schemas
70+
2. Validate test vectors from `/test-vectors`
71+
3. Report validation results
72+
73+
## Usage Example
74+
75+
```javascript
76+
const Ajv = require('ajv');
77+
const addFormats = require('ajv-formats');
78+
const transferSchema = require('./messages/transfer.json');
79+
80+
const ajv = new Ajv();
81+
addFormats(ajv);
82+
83+
const validate = ajv.compile(transferSchema);
84+
const valid = validate(transferMessage);
85+
86+
if (!valid) {
87+
console.log(validate.errors);
88+
}
89+
```
90+
91+
## Schema Development
92+
93+
When creating or modifying schemas:
94+
95+
1. Follow the existing pattern and structure
96+
2. Use `$ref` to reference common definitions
97+
3. Include comprehensive descriptions
98+
4. Test against relevant test vectors
99+
5. Ensure TypeScript types match the schema
100+
101+
## References
102+
103+
- [JSON Schema Specification](https://json-schema.org/)
104+
- [TAP Documentation](https://github.com/TransactionAuthorizationProtocol/TAIPs)
105+
- [CAIP Standards](https://github.com/ChainAgnostic/CAIPs)

‎schemas/common/base-types.json‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://taips.tap.rsvp/schemas/common/base-types.json",
4+
"title": "TAP Base Types",
5+
"description": "Common base type definitions used across TAP message schemas",
6+
"$defs": {
7+
"uuid": {
8+
"type": "string",
9+
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
10+
"description": "UUID v4 format"
11+
},
12+
"did": {
13+
"type": "string",
14+
"pattern": "^did:[a-z0-9]+:[a-zA-Z0-9._%-]*[a-zA-Z0-9._%-]$",
15+
"description": "Decentralized Identifier (DID) format"
16+
},
17+
"iri": {
18+
"type": "string",
19+
"format": "iri",
20+
"description": "Internationalized Resource Identifier"
21+
},
22+
"iso8601DateTime": {
23+
"type": "string",
24+
"format": "date-time",
25+
"description": "ISO 8601 date-time format"
26+
},
27+
"iso4217CurrencyCode": {
28+
"type": "string",
29+
"pattern": "^[A-Z]{3}$",
30+
"description": "ISO 4217 3-letter currency code"
31+
},
32+
"amount": {
33+
"type": "string",
34+
"pattern": "^[0-9]+(\\.[0-9]+)?$",
35+
"description": "Decimal amount as string to preserve precision"
36+
},
37+
"lei": {
38+
"type": "string",
39+
"pattern": "^[A-Z0-9]{20}$",
40+
"description": "Legal Entity Identifier (LEI) - 20 alphanumeric characters"
41+
},
42+
"base64": {
43+
"type": "string",
44+
"contentEncoding": "base64",
45+
"description": "Base64 encoded data"
46+
},
47+
"email": {
48+
"type": "string",
49+
"format": "email",
50+
"description": "Email address"
51+
},
52+
"phone": {
53+
"type": "string",
54+
"pattern": "^\\+?[1-9]\\d{1,14}$",
55+
"description": "E.164 phone number format"
56+
},
57+
"url": {
58+
"type": "string",
59+
"format": "uri",
60+
"description": "URL format"
61+
},
62+
"jsonLdContext": {
63+
"oneOf": [
64+
{
65+
"type": "string",
66+
"format": "uri"
67+
},
68+
{
69+
"type": "array",
70+
"items": {
71+
"oneOf": [
72+
{
73+
"type": "string",
74+
"format": "uri"
75+
},
76+
{
77+
"type": "object"
78+
}
79+
]
80+
}
81+
},
82+
{
83+
"type": "object"
84+
}
85+
],
86+
"description": "JSON-LD context definition"
87+
},
88+
"locale": {
89+
"type": "string",
90+
"pattern": "^[a-z]{2}(-[A-Z]{2})?$",
91+
"description": "Language locale code (e.g., 'en', 'en-US')"
92+
},
93+
"base64Binary": {
94+
"type": "object",
95+
"required": ["type", "value"],
96+
"properties": {
97+
"type": {
98+
"const": "https://didcomm.org/codecs/1.0/base64"
99+
},
100+
"value": {
101+
"$ref": "#/$defs/base64"
102+
}
103+
}
104+
}
105+
}
106+
}

‎schemas/common/caip-types.json‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://taips.tap.rsvp/schemas/common/caip-types.json",
4+
"title": "CAIP Type Definitions",
5+
"description": "Chain Agnostic Improvement Proposal (CAIP) type definitions",
6+
"$defs": {
7+
"caip2": {
8+
"type": "string",
9+
"pattern": "^[-a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,32}$",
10+
"description": "CAIP-2 blockchain ID (e.g., 'eip155:1' for Ethereum mainnet)",
11+
"examples": ["eip155:1", "bip122:000000000019d6689c085ae165831e93", "cosmos:cosmoshub-4"]
12+
},
13+
"caip10": {
14+
"type": "string",
15+
"pattern": "^[-a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,32}:[a-zA-Z0-9]{1,64}$",
16+
"description": "CAIP-10 account ID (blockchain_id:address)",
17+
"examples": [
18+
"eip155:1:0x0000000000000000000000000000000000000000",
19+
"bip122:000000000019d6689c085ae165831e93:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
20+
]
21+
},
22+
"caip19": {
23+
"type": "string",
24+
"pattern": "^[-a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,32}/[-a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,64}$",
25+
"description": "CAIP-19 asset type (blockchain_id/asset_namespace:asset_reference)",
26+
"examples": [
27+
"eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
28+
"eip155:1/erc721:0x06012c8cf97BEaD5deAe237070F9587f8E7A266d",
29+
"bip122:000000000019d6689c085ae165831e93/slip44:0"
30+
]
31+
},
32+
"caip220": {
33+
"type": "string",
34+
"pattern": "^[-a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,32}:[a-zA-Z0-9]{1,64}@[-a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,32}/[-a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,64}$",
35+
"description": "CAIP-220 asset ID (account_id@asset_type)",
36+
"examples": [
37+
"eip155:1:0x0000000000000000000000000000000000000000@eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
38+
]
39+
}
40+
}
41+
}

0 commit comments

Comments
 (0)