An inline schema defines a data model directly inside the OpenAPI element that uses it, rather than pointing to a reusable schema. It is placed under a schema property and can describe parameters, query values, headers, request bodies, or responses. section 7.6 section 7.7.1
For a path parameter, copy the relevant property model into the parameter’s schema. A product lookup can define productReference inline as a required integer under /products/{productReference}. The same technique applies to query parameters and other parameter locations. section 7.6.1
Inline parameter schema
paths: /products/{productReference}: parameters: - name: productReference in: path required: true schema: type: integer
Inline definitions are useful when describing the immediate API element, but copying models can create duplication and unwanted variations. A reusable schema under components.schemas, referenced with $ref, centralizes a model used by multiple operations. Choose reuse when consistency matters; keep the first design focused on describing the API rather than optimizing every model. section 7.7.1 section 7.7.4
The two approaches can also be combined. For a product search response, define an inline array schema and reference ProductSummary for each item. Likewise, a reusable Product schema can contain an inline property model or reference SupplierSummary. section 7.7.4
