Create schema
POST/schemas●Define a new validation schema to enforce rules on ledger records.
Once the first schema for a resource type is created, all new records of that type must reference a valid schema. Existing records remain valid until updated, at which point they must conform to a valid schema.
Schemas use JSON Schema format and support standard features
including type constraints, required fields, oneOf/anyOf
composition, $ref references, and enum values.
Broadcasts the schema-created signal. Use
effects to subscribe.
Usage Examples
curl -X POST "http://localhost:3000/v2/schemas" \ -H "x-ledger: <YOUR LEDGER HANDLE>" \ -H "Content-Type: application/json" \ -d '{ "hash": "4eefc033339bc5d1cee0f45156ac4d4854393985228429a913dcaae48040301c", "data": { "handle": "bank-wallet", "format": "json-schema", "schema": { "type": "object", "title": "Bank Wallet", "required": [ "handle" ], "properties": { "handle": { "type": "string", "pattern": "^[a-z0-9.-]+$" }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name for the wallet" }, "description": { "type": "string", "description": "Purpose or details of the wallet" } } } } }, "record": "wallet" }, "meta": { "proofs": [ { "method": "ed25519-v2", "digest": "e04f4fdfd1f77d0b0bed97474f85d5bd8c8190546f7ca2bb20861b261832521c", "public": "AN6XpZ7T8FDCkjbSpIVE2cioQ7hajp8DBTOioz/TSZ8=", "result": "TAO9iluaI5QanY5xyQmTJQDajleny9gU8oyJtIAOob9UARbqmx+IgZ1fpeYlphikcluRfgMQy2BsPWB3WGFGDA==", "custom": { "moment": "2025-04-05T14:30:00.000Z", "status": "created" } } ] } }'{
"luid": "$sch.-01xK8yZAB9kZ1DE0",
"hash": "4eefc033339bc5d1cee0f45156ac4d4854393985228429a913dcaae48040301c",
"data": {
"handle": "bank-wallet",
"format": "json-schema",
"schema": {
"type": "object",
"title": "Bank Wallet",
"required": [
"handle"
],
"properties": {
"handle": {
"type": "string",
"pattern": "^[a-z0-9.-]+$"
},
"custom": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Display name for the wallet"
},
"description": {
"type": "string",
"description": "Purpose or details of the wallet"
}
}
}
}
},
"record": "wallet"
},
"meta": {
"status": "created",
"moment": "2025-04-05T14:30:00.050Z",
"owners": [
"AN6XpZ7T8FDCkjbSpIVE2cioQ7hajp8DBTOioz/TSZ8="
],
"proofs": [
{
"signer": "ach-admin",
"method": "ed25519-v2",
"digest": "e04f4fdfd1f77d0b0bed97474f85d5bd8c8190546f7ca2bb20861b261832521c",
"public": "AN6XpZ7T8FDCkjbSpIVE2cioQ7hajp8DBTOioz/TSZ8=",
"result": "TAO9iluaI5QanY5xyQmTJQDajleny9gU8oyJtIAOob9UARbqmx+IgZ1fpeYlphikcluRfgMQy2BsPWB3WGFGDA==",
"custom": {
"moment": "2025-04-05T14:30:00.000Z",
"status": "created"
}
},
{
"signer": "system",
"method": "ed25519-v2",
"digest": "e81ed089c8edba16e21c216035a9c44e3dd6f82d960fde0015e5ce83dd803d1d",
"public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
"result": "zRUUQuJo+gooqucUYWDlgoo2uTn9l6Dt7ucM+0XpVDwy/Uiu0hDVxmCWOQLoS+kcJCbMa6QuxLVK6B/9+6u4Bg==",
"custom": {
"luid": "$sch.-01xK8yZAB9kZ1DE0",
"moment": "2025-04-05T14:30:00.050Z",
"status": "created"
}
}
]
}
}{
"hash": "b7eb7ccf5ffc126951e13e29a8dcfdaf95db859715d4edfc2d16f59a79d4cd58",
"data": {
"reason": "auth.unauthorized",
"detail": "Invalid token."
},
"meta": {
"proofs": [
{
"signer": "system",
"method": "ed25519-v2",
"digest": "3acece870c4118bfe4223118e4d2f3cfd5b8947a7093785b66d49aa57fa2890a",
"public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
"result": "gnK63DqqWDY/UXvnZHixDKPKS6tfeGHgdARylnPiJLwQGyYxuD97TYbSg2wrzsf/bDrHwQYZaf8Gu5ryYP0UAA==",
"custom": {
"moment": "2025-04-05T14:30:00.000Z"
}
}
]
}
}{
"hash": "9ec02726b50650add8acfd124c6defeb978a9ac252a5de888f9493ddc701e927",
"data": {
"reason": "auth.forbidden",
"detail": "Request is not authorized"
},
"meta": {
"proofs": [
{
"signer": "system",
"method": "ed25519-v2",
"digest": "4f8cbdc38d73348de0c31805c783c84a0fecc6be736d7e187004ba68cd00e675",
"public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
"result": "P3hRnveehtuobb4AIO56XBmiduvmYJbpdmOHltG/IifBEH7QSWdv/0pqled4SO9x1Ne3oXuWxJy40DzMvx1MBA==",
"custom": {
"moment": "2025-04-05T14:30:00.000Z"
}
}
]
}
}{
"hash": "dc973d46dd35baa27b0ec5a107e2ee3a8cc57116d086dd868dd0f044a8de7d92",
"data": {
"reason": "record.duplicated",
"detail": "Ledger with handle instant-payments already exists."
},
"meta": {
"proofs": [
{
"signer": "system",
"method": "ed25519-v2",
"digest": "3e1317cc165d132f95ec2f6374890063c162d905d86b33270f97416f8441a872",
"public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
"result": "b+0gSDCUzjEKlZQ/c40yqNpZoyQxCFsbV1Ut5/0zM2wM46xmHMBj3qeo3/GDaFD4NgSNm2G8n1f9c9rfvkl3BA==",
"custom": {
"moment": "2025-04-05T14:30:00.000Z"
}
}
]
}
}{
"hash": "1c084e8dcfb9bb84bc8ea96e9e137b149a34b2bbd85f8e60b4263f5aba980476",
"data": {
"custom": {
"errors": [
{
"instancePath": "/handle",
"schemaPath": "#/properties/handle/pattern",
"keyword": "pattern",
"params": {
"pattern": "^[a-zA-Z0-9_\\-+.]+$"
},
"message": "must match pattern \"^[a-zA-Z0-9_\\-+.]+$\""
}
]
},
"reason": "record.schema-invalid",
"detail": "Schema validator error: data.handle must match pattern \"^[a-zA-Z0-9_\\-+.]+$\""
},
"meta": {
"proofs": [
{
"signer": "system",
"method": "ed25519-v2",
"digest": "7a5febb431719b6f43d7e88e79211308e16ac651b71b339276373fdb4e7c3760",
"public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
"result": "2/1zYw4AaIzsIHfOIC6V/CHw6owbjYHt48cwmFOig0ibeT0IbojLmj1RCRi8W00ka0udPa9WsacWDd7ObMY8CA==",
"custom": {
"moment": "2025-04-05T14:30:00.000Z"
}
}
]
}
}{
"hash": "93a5f4d97a42c2df97f827c58ff7768d02568c15aca931e22b81fa3160ba0df3",
"data": {
"reason": "api.unexpected-error",
"detail": "An unexpected error occurred"
},
"meta": {
"proofs": [
{
"signer": "system",
"method": "ed25519-v2",
"digest": "efaf5360143b586917d9636779ad6e08571c5b06909a20dd0f5eba4bf3be7eae",
"public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
"result": "hERh6Aecj59iR+Fb25OQsHJScOi4t8EiffKSfjlMQdjHMccTnfDlgZFdaJzXzUtpSwy/NHq0l+7ydh3HSWCoAg==",
"custom": {
"moment": "2025-04-05T14:30:00.000Z"
}
}
]
}
}Header Parameters
x-ledger?|
The unique identifier of ledger in context for multi tenant requests.
Request Body
application/json
Schema body
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
Schema
Define validation rules and structure for ledger records.
List schemas GET
Use this endpoint to review validation rules defined for a resource type, or find schemas by record type. Supported filters: - `data.record` — target resource type - `data.schema` — schema identifier - `meta.status` — record status - `meta.labels` — record labels - `meta.domain` — domain scope - `data.custom.<field>` — any custom field (may be slower on large datasets)