Update schema
PUT/schemas/{id}●Submit a new version of a schema.
The request must include the current record hash in data.parent
to prevent conflicts from concurrent updates. If the parent hash
does not match the record's current hash, the request is rejected
with a 422 error.
Broadcasts the schema-updated signal. Use
effects to subscribe.
Usage Examples
curl -X PUT "http://localhost:3000/v2/schemas/<HANDLE>" \ -H "x-ledger: <YOUR LEDGER HANDLE>" \ -H "Content-Type: application/json" \ -d '{ "luid": "$sch.-01xK8yZAB9kZ1DE0", "hash": "516c47da85975e3a5546b0e0e83eba284c46310a7d79e99949a67cd679e14795", "data": { "handle": "bank-wallet", "parent": "4eefc033339bc5d1cee0f45156ac4d4854393985228429a913dcaae48040301c", "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" }, "country": { "type": "string", "description": "Country of the wallet holder" } } } } }, "record": "wallet" }, "meta": { "proofs": [ { "method": "ed25519-v2", "digest": "9c872c8e4a174ebefad8d083531a17102354bdcfc88cd3d7552a9ae738385070", "public": "AN6XpZ7T8FDCkjbSpIVE2cioQ7hajp8DBTOioz/TSZ8=", "result": "3NZHwxhQSPbZGHMKcHFuaIVrSOvPQCmBpnncA0m+FMUA9nKuOEXlijZ14N6BjPeleaoCYX5LlXcZmDlmBp6TBg==", "custom": { "moment": "2025-04-05T14:30:00.200Z" } } ] } }'{
"luid": "$sch.-01xK8yZAB9kZ1DE0",
"hash": "516c47da85975e3a5546b0e0e83eba284c46310a7d79e99949a67cd679e14795",
"data": {
"handle": "bank-wallet",
"parent": "4eefc033339bc5d1cee0f45156ac4d4854393985228429a913dcaae48040301c",
"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"
},
"country": {
"type": "string",
"description": "Country of the wallet holder"
}
}
}
}
},
"record": "wallet"
},
"meta": {
"status": "created",
"moment": "2025-04-05T14:30:00.220Z",
"owners": [
"AN6XpZ7T8FDCkjbSpIVE2cioQ7hajp8DBTOioz/TSZ8="
],
"proofs": [
{
"signer": "ach-admin",
"method": "ed25519-v2",
"digest": "9c872c8e4a174ebefad8d083531a17102354bdcfc88cd3d7552a9ae738385070",
"public": "AN6XpZ7T8FDCkjbSpIVE2cioQ7hajp8DBTOioz/TSZ8=",
"result": "3NZHwxhQSPbZGHMKcHFuaIVrSOvPQCmBpnncA0m+FMUA9nKuOEXlijZ14N6BjPeleaoCYX5LlXcZmDlmBp6TBg==",
"custom": {
"moment": "2025-04-05T14:30:00.200Z"
}
},
{
"signer": "system",
"method": "ed25519-v2",
"digest": "1d6d2220e44273441288eede49d592c65358caf35e5f56fc7bc38478163c56d2",
"public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
"result": "rdQdQwX1Agea6sqKhK/9l5RHEb+zJZjZNT3JAQT+cQ+ADHd1vuiIYwiIVdJAoxOmeIcoPiE8sy/MHTgKlJhrCQ==",
"custom": {
"luid": "$sch.-01xK8yZAB9kZ1DE0",
"moment": "2025-04-05T14:30:00.220Z"
}
}
]
}
}{
"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": "d6c59a6df7165fa4a75159799ca5f5e26e544cbb8769eced3d35d8021f6f7935",
"data": {
"reason": "record.not-found",
"detail": "Signer not found"
},
"meta": {
"proofs": [
{
"signer": "system",
"method": "ed25519-v2",
"digest": "78cf86f34aefcf9da6ed4167a38aac0a2739f68f7bafb1d3e033c01ed1b6cdf1",
"public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
"result": "9Ledk+/iAAtj+uLjGe2afq4kID7n8UQD6UpRpLBCujxFjxddq0uZ2tnYRTAXmYdHDkbF0uXqtNM9qO3xhEtpAA==",
"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"
}
}
]
}
}Path Parameters
id*|
The unique identifier of the record - it is luid or handle (address).
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
application/json
Get schema GET
Previous Page
Add schema proof POST
Appends a signed proof to the record. The proof must be signed against the record's current hash. Use proofs to change status, update labels, or record custom data — see [About Proofs](/ledger/structuring-data/about-proofs) for details. Returns the updated record with the new proof in `meta.proofs`. Broadcasts the `schema-proofs-added` signal. Use [effects](/ledger/reference/api/effect) to subscribe.