Sobre los Esquemas

---

La base de datos del Ledger proporciona múltiples tipos de registros con esquemas estrictos (integrados) para todos los campos raíz, excepto el campo custom, que puede contener cualquier valor. En distintos escenarios, los usuarios del ledger pueden necesitar extender esos esquemas para adaptarlos a sus casos de uso.

Qué es un Esquema

Un schema (esquema), en el contexto del ledger, es simplemente otro registro que puede crearse utilizando la API. El registro del esquema define un conjunto de reglas y restricciones que se utilizarán para validar el registro al cual se aplica ese esquema. Todos los schemas tienen una propiedad record, que hace referencia al tipo de registro en el que se utilizará ese esquema. Esa propiedad puede ser uno de los siguientes: symbol, signer, wallet, intent, effect, bridge o circle.

Cómo se estructuran los esquemas

El único formato de esquema soportado actualmente es json-schema. JSON Schema es un lenguaje declarativo que permite especificar distintas reglas, tipos y restricciones para validar un JSON de entrada. Puedes leer más al respecto en su página oficial. Ten en cuenta que el ledger utiliza la especificación Draft-07 de JSON Schema para mejorar el rendimiento.

• Ejemplo de esquema con este Draft:

  const schema = {
    definitions: {
      IssueClaim: {
        type: "object",
        required: ["action", "target", "symbol", "amount"],
        properties: {
          action: {
            type: "string",
            const: "issue",
          },
          target: {
            type: "string",
          },
          symbol: {
            type: "string",
          },
          amount: {
            type: "integer",
          },
        },
      },
      TransferClaim: {
        type: "object",
        required: ["action", "source", "target", "symbol", "amount"],
        properties: {
          action: {
            type: "string",
            const: "transfer",
          },
          source: {
            type: "string",
          },
          target: {
            type: "string",
          },
          symbol: {
            type: "string",
          },
          amount: {
            type: "integer",
          },
        },
      },
      DestroyClaim: {
        type: "object",
        required: ["action", "source", "symbol", "amount"],
        properties: {
          action: {
            type: "string",
            const: "destroy",
          },
          source: {
            type: "string",
          },
          symbol: {
            type: "string",
          },
          amount: {
            type: "integer",
          },
        },
      },
    },
    type: "object",
    required: ["data"],
    properties: {
      data: {
        type: "object",
        required: ["handle", "claims"],
        properties: {
          handle: {
            type: "string",
          },
          claims: {
            type: "array",
            items: {
              type: "object",
              discriminator: { propertyName: "action" },
              oneOf: [
                {
                  $ref: "#/definitions/IssueClaim",
                },
                {
                  $ref: "#/definitions/TransferClaim",
                },
                {
                  $ref: "#/definitions/DestroyClaim",
                },
              ],
            },
          },
        },
      },
    },
  };

  • Ejemplo de datos que pueden ser validados contra el esquema anterior:

  const intent = {
    data: {
      // If no handle is provided, it will return error
      // handle: 'x12345',
      claims: [
        // Valid transfer claim
        {
          action: "transfer",
          source: "acc1",
          target: "acc2",
          symbol: "usd",
          amount: 10,
        },
        // Valid issue claim
        {
          action: "issue",
          target: "acc2",
          symbol: "usd",
          amount: 10,
        },
        // Valid destroy claim
        {
          action: "destroy",
          source: "acc1",
          symbol: "usd",
          amount: 10,
        },
        // missing symbol
        {
          action: "transfer",
          source: "acc1",
          target: "acc2",
          amount: 10,
        },
        // invalid action
        {
          action: "fake",
          source: "acc1",
          target: "acc2",
          amount: 10,
        },
        // missing amount
        {
          action: "issue",
          target: "acc1",
          symbol: "usd",
        },
        // missing symbol
        {
          action: "destroy",
          source: "acc1",
          amount: 10,
        },
      ],
    },
  };

Cuándo se validan los esquemas

Los esquemas se validan en el momento en que se intenta crear o actualizar un nuevo registro. La propiedad <record>.data se valida contra el esquema especificado. Si la validación falla, se lanza un error y la operación no se completa.

---

Historial de cambios

1.0.0•01 de jun de 2025

• Agregado• Versión inicial