A data model is a structured description of the data an API operation accepts or returns. It identifies properties, names, types, required status, and organization in objects or arrays. Modeling turns coarse-grained data such as “Product information” into usable request and response structures. section 1.6.2 section 5.0
Design starts with a complete theoretical resource model containing the business concept’s possible properties, including its identifier. Operation-specific inputs and outputs then derive from that model, preserving consistency while selecting only what each context requires. section 5.1.3 section 5.3
Common model forms support distinct HTTP operation needs:
- Complete models contain all business-concept properties and can support create, read, search, or update outputs. section 5.4.1
- Summarized models retain identifiers and meaningful main properties for list or search results. section 5.4.1
- Minimal models contain only the resource identifier; identifier models represent the identifier value used in path parameters. section 5.4.1
- Creation models contain consumer-managed creation data, replacement models usually support PUT, and modification models usually make creation properties optional for PATCH. section 5.4.2
Product resource and operations
A complete Product model might contain productReference as an integer, category as a string, price as a float, and optional keywords as an array of strings. A create request derives ProductCreation by excluding the server-generated productReference. A search response can use ProductSummary, while GET /products/{productReference} uses an integer identifier path parameter. section 5.0 section 5.4.1 section 5.4.2
Keep models useful without exposing implementation details or copying one consumer’s interface. Include data consumers need, such as product dimensions or description, but avoid internal database fields and UI-specific groupings. Embedded resources should use an identifier, summary, or complete model according to whether consumers need their details routinely. section 5.5.3 section 8.7.3
Avoid embedding large lists that require filtering or pagination. For example, thousands of bank transactions belong in separate resource models and operations, while a small set of current balances may remain embedded in a Bank Account model. section 8.7.2
Figure 5.7 We use theoretical resource models to design inputs and outputs. We ensure that data meets consumer needs without exposing inner workings; we especially check input sources for gaps in capabilities.
Use the model-derivation flow to connect a complete resource model with operation inputs and outputs while checking consumer needs and capability gaps. section 5.1.3
Describe models with JSON Schema in OpenAPI rather than maintaining spreadsheet or prose-only definitions. Place reusable resource schemas under components.schemas and reference them with $ref; place operation-specific schemas in request and response schema properties. JSON Schema models use portable types such as objects, arrays, strings, numbers, integers, and Booleans. section 7.0 section 7.8
Validate each model for user-friendliness, interoperability, and consistency. Reuse suitable local, domain, or global standards, but reject standards that do not meet consumer needs. Returning sufficiently informative data can prevent consumers from making one read request per list item. section 8.9.1 section 9.5.2
