How to Define and Validate OpenAPI Request Schemas

JSON syntax validation checks whether a document parses. OpenAPI document validation checks its description structure. Payload validation checks a particular request against a schema. Runtime authorization and business rules still require server implementation.

A schema-valid amount does not prove funds are available or a payment is authorized. Define those failures in the operation's responses and test them in the service.

The following reusable Schema Object belongs under components.schemas.CreatePayment in a complete OpenAPI document. Reference it from requestBody.content.application/json.schema. Mark requestBody.required separately when the body itself is mandatory.

properties defines field constraints, while required names fields that must exist. additionalProperties: false rejects unknown request fields. Decide that policy with consumers because it can reject future fields. This fragment does not constitute a complete importable OpenAPI document.

{
  "type": "object",
  "required": ["amount", "currency"],
  "additionalProperties": false,
  "properties": {
    "amount": { "type": "integer", "minimum": 1 },
    "currency": { "type": "string", "enum": ["EUR", "USD"] }
  }
}

Against this schema, amount: 4900 and currency: EUR satisfy the stated constraints. Zero fails minimum; 1.5 fails integer; an absent currency fails required; GBP fails the enum. Null does not stand in for a missing property.

Keep these expected cases in your payload validation tests. A document validator accepting the schema does not automatically run every example against it. Duplicate JSON keys and numbers beyond JavaScript safe precision require special care with browser JSON tools.

Expected valid:
{"amount":4900,"currency":"EUR"}

Expected invalid: amount below minimum
{"amount":0,"currency":"EUR"}

Expected invalid: missing currency
{"amount":4900}

Expected invalid: extra field
{"amount":4900,"currency":"EUR","debug":true}

A service can report domain validation with 422 and a stable code such as invalid_amount. Document the response schema and examples beside the success response. Do not disclose internal stack traces or rejected secrets in errors.

Use the Payments API creation guide for the complete document, including a reusable Error schema. Validate the specification and use a matching OpenAPI or JSON Schema dialect validator for payload tests. OpenAPI 3.0 and 3.1 schemas are not interchangeable.

API Designer keeps operation schemas close to documentation and requests. Save the design, export OpenAPI JSON and resolve reported validation errors. Inspect warnings and compare the exported schema with your intended constraints.

The free OpenAPI Validator checks a self-contained JSON description locally. It does not send requests or verify business logic. Use backend tests to enforce the actual request contract.