JSON Schema

CPN uses JSON Schema to define and validate the structure of JSON data used to pass travel rule, beneficiary account, and RFI data. A JSON Schema is a blueprint for the compliance data that OFIs must provide. CPN uses the Draft 2020-12 version of the JSON Schema standard.

Using JSON Schema to define the structure of this data has the following benefits:

• Clarity: the schema defines every requirement programmatically, including required fields, data types, formats, and structures. This eliminates guesswork.
• Client-side validation: OFIs can validate their response against the schema before making the API call, providing instant feedback for developers and preventing common integration errors.
• Rich data structures: schemas support complex requirements like nested address objects and conditional logic.

When you call the payment requirements endpoint, the API returns schemas for the travel rule and beneficiary account data. The following are key parts of the schemas to understand when reading them:

• properties: defines the fields you can provide in your JSON response
• required: contains a list of field names that must be present in the response
• $defs and $ref: usable complex objects (defined in $defs and referenced using the $ref directive)

JSON Schema allows you to validate your response before sending it to the API. CPN expects that OFIs perform client-side validation against the provided schema before submitting a response to CPN. Doing so provides a first line of defense to reduce API errors and failed payments.

Common libraries for JSON Schema validation are:

• Java: networknt/json-schema-validator
• Python: jsonschema
• Node.js: ajv

JSON Schema validates structure and format only. You are still responsible for ensuring the data is contextually correct. The schema ensures that you send the data in the correct shape; you ensure the data is accurate. For example, you can validate CNPJ and CPF numbers using their check digits.