When downloading a JSON Schema from the Payment Rules service, you will receive a document containing structured properties and definitions. This page outlines the important features of these schemas and what they mean for your application.

Properties and Required Fields

The core of the schema structure is built on properties. These dictate the shape of the data expected.

• properties: The list of available data points (like creditor_name, creditor_postal_address).
• required: An array detailing which of the properties must be provided for the payload to be deemed valid.

Properties

Each property in the schema defines a specific data field with its own validation rules and structure.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:com:swift:payment-preparation:us:es:eur:p2p:a2a:2026-03-13:en",
  "title": "Payment Preparation Schema (ES)",
  "type": "object",
  "x-version-date-time": "2026-03-13T17:26:00.000+01:00",
  "x-owner": "Swift",
  "properties": {
    "creditor_name": {},
    "creditor_postal_address": {},
    "creditor_account_and_agent": {}
  }
}

Each property is associated with a specific type that defines the expected data structure format:

• string: The most common type, representing text data (e.g., names, addresses, account numbers).
• object: Represents a nested structure containing its own nested schema properties (e.g., creditor_postal_address containing town_name and country).
• array: Used for lists of items. It typically includes an items keyword to define the exact expected type of items within the array (e.g., address_line as an array of strings).
• boolean: Standard true or false values.
• integer / number: Numeric amounts or numeric identifiers.

{
  "string": "text data",
  "object": {
    "nested_field": "value"
  },
  "array": ["item1", "item2"],
  "boolean": true,
  "integer": 123,
  "number": 123.45
}

Required Properties

When a property is listed in the required array, it means that field must be present in the JSON payload for the validation to pass. If it's missing, the entire payload will be considered invalid.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:com:swift:payment-preparation:us:es:eur:p2p:a2a:2026-03-13:en",
  "title": "Payment Preparation Schema (ES)",
  "type": "object",
  "x-version-date-time": "2026-03-13T17:26:00.000+01:00",
  "x-owner": "Swift",
  "properties": {
    "creditor_name": {},
    "creditor_postal_address": {},
    "creditor_account_and_agent": {},
  },
  "required": [
    "creditor_name",
    "creditor_postal_address",
    "creditor_account_and_agent"
  ]
}

Validation Rules

To prevent data entry errors before submission, schemas contain explicit constraints on specific properties:

• minLength / maxLength: Specifies the character string limits. Especially useful for text inputs such as creditor_name or town_name.

"creditor_name": {
  "type": "string",
  "minLength": 1,
  "maxLength": 140
}

• pattern: A regular expression defining the shape of the required data (for instance, ensuring a 9-digit US ABA routing number ^[0-9]{9}$).

"clearing_member_identification": {
  "type": "string",
  "pattern": "^[0-9]{9}$"
}

Custom Swift Extensions

Swift provides additional extended fields using the x- prefix to help you build localized and guided frontends.

• x-Note: Provides detailed rules or constraints that a human user needs to be aware of.

"creditor_name": {
  "type": "string",
  "x-Note": "Must be the full name of the beneficiary as it appears on their bank account."
}

• x-UIErrorMessage: A robust feature providing ready-to-use user error messages in local languages mappings. It specifies exact messages for violations of required, pattern, minLength, and maxLength.

"town_name": {
  "type": "string",
  "minLength": 1,
  "x-UIErrorMessage": {
    "minLength": "Town name is required and cannot be empty."
  }
}

Conditionals (oneOf)

Some fields allow multiple formats. For example, to identify a beneficiary bank, either an account number with a clearing code or an account number with a BIC might be accepted. The schema uses the oneOf array to declare these variations.

The oneOf Structure

"creditor_account_and_agent": {
  "type": "object",
  "oneOf": [
    {
      "properties": {
        "other_identification": {
          "title": "Beneficiary Account Number",
          "pattern": "^[0-9]{8,17}$"
        },
        "clearing_member_identification": {
          "title": "Beneficiary Bank ABA Routing Number",
          "pattern": "^[0-9]{9}$"
        }
      },
      "required": ["other_identification", "clearing_member_identification"]
    },
    {
      "properties": {
        "bicfi": {
          "title": "Beneficiary Bank BIC"
        },
        "other_identification": {
          "title": "Beneficiary Account Number"
        }
      },
      "required": ["other_identification", "bicfi"]
    }
  ]
}

When building a frontend or backend validator, your code must ensure that exactly one of the object structures defined inside oneOf is satisfied.

Conditional Validations (if / then)

In addition to oneOf, Swift schemas use if/then conditional logic to express inter-dependencies between fields. This mechanism dictates that if a specific condition is met, certain rules or required fields must then be applied.

The if / then Structure

Here is an example structure demonstrating how an if block evaluates a property, and a corresponding then block applies additional constraints if the evaluation is true:

{
  "if": {
    "properties": {
      "payment_routing_method": {
        "const": "DOMESTIC"
      }
    }
  },
  "then": {
    "required": ["clearing_member_identification"]
  }
}

When building your validations, your application must dynamically re-evaluate the applicable validation rules whenever a dependent field changes.