Request Schema

Overview

How it works

The main risks include accepting ambiguous data, rejecting backward-compatible clients, unsafe coercion, unbounded payloads, and undocumented null behavior. It describes syntactic and structural validity, while business rules may impose additional constraints that cannot be represented fully in the schema.

What matters in practice

A request schema states the valid fields, types, formats, required constraints and allowed combinations an API accepts. Schema validation should happen before side effects and produce stable, field-specific errors. Money fields need exact decimal or integer-unit rules; floating-point rounding can distort payouts. Network and currency identifiers should be validated together, and fields such as callback URLs may need security checks beyond syntax. Version the contract and test unknown fields, nullable values and backwards compatibility. A syntactically valid request still requires authentication, authorization and business-rule checks.

Schema evolution is a common integration hazard. Turning an optional field into a mandatory field can break clients without any change on their side, and treating a string amount as a floating-point number can destroy precision. Define whether unknown fields are rejected or ignored, document required asset-network combinations and publish examples for every error family. Contract tests should cover the exact requests used by production clients before deploying a breaking change.

A JSON schema can reject malformed inputs, but it cannot establish that a wallet belongs to a legitimate payee. Put field-level validation at the API boundary and authorization checks at the domain boundary. Integration documentation should show one valid request, common invalid values and the exact error object clients can expect, enabling developers to handle failures without guesswork.

Related glossary concepts

Response Schema; Schema Validation; OpenAPI Document