JSON Schema describes and can validate JSON or YAML data. It works independently, but OpenAPI uses it to define the data carried by HTTP operations. A schema can specify what data is allowed and annotate it with descriptions that help people understand it. section 7.1.1 section 7.0
Start describing data as you design it. Define a complete resource model under `components.schemas`, then use its properties or derived models for operation inputs and outputs. This replaces separate data-model tables with schemas in the OpenAPI document. section 7.1.3 section 7.4
A product model and path parameter
A product can be an object with an identifier and an array of search keywords. The object's `required` list identifies mandatory properties; the array's `items` schema describes each element. A path parameter can have its own inline schema. ```yaml components: schemas: Product: type: object required: [productReference] properties: productReference: type: integer description: Unique identifier keywords: type: array items: type: string paths: /products/{productReference}: parameters: - name: productReference in: path required: true schema: type: integer ``` Keep the parameter's type consistent with the resource property it identifies. section 7.4.3 section 7.4.5 section 7.6.1 section 7.8
Put an inline schema in an operation's parameter or response-header `schema` property when the data is local to that use. Reference a reusable schema with `$ref` when request or response bodies share a model; this avoids duplication and unwanted differences. A `Location` response header, for example, can use an ad hoc `type: string` schema. section 7.6.1 section 7.6.3 section 7.8
Add precision when it serves a purpose. Keywords can express number ranges, array sizes, string patterns, enumerations, and defaults for documentation, code generation, testing, or mocking. For a 500 error, `const` and `pattern` can constrain expected error fields and help prevent sensitive details from appearing—provided the implementation follows the contract. section 19.3 section 12.10.5
Check the tools before relying on advanced features: OpenAPI 3.0 and 3.1 use different JSON Schema versions, and tool support may vary. An API gateway can validate requests against schemas, but doing so before the implementation handles them may prevent more exhaustive, user-friendly errors. Model the essential data first; add finer constraints in a later pass if needed. section 7.2 section 19.1.5 section 19.3



