A data model is a structured description of the data an API accepts or returns: its properties, required fields, allowed values, and relationships between representations. In practice, it acts as a boundary between external input and application state. A strong model rejects data that does not fit the intended domain instead of allowing malformed or hostile values to reach databases and business logic. section 5.8 section 6.4.1
Weak models can cause security and reliability failures. Consuming an unvalidated third-party status may permit an injection string to reach an update query. Reusing one permissive schema for different book types can store incompatible fields and later break calculations. Reusing an output model for payment input can also expose server-managed identifiers and statuses to modification. section 5.8 section 6.4.1 section 6.5
Design data models defensively:
- Mark essential properties as required and constrain finite values with enumerations, such as print or ebook, or wizard, witch, or muggle. section 5.8 section 6.4.1
- Separate models for different representations when their properties differ. A shared base can hold common fields, while composed models add pages or byte_size. section 6.4.1
- Use distinct input and output models when responses contain server-side properties such as payment identifiers or statuses; reject unspecified input properties. section 6.5
- Log validation failures and return an error that API consumers can understand, whether validation produces a 500 response or a handled 400 response. section 5.8
Validating a third-party status
A validation model permits only wizard, witch, or muggle. If an external response contains an injection string instead, validation fails before the character record is updated. A payment model follows the same principle: accept amount and currency in the request, but keep id and status in the response model. section 5.8 section 6.5
Listing 6.8 Using composition to handle shared model properties
# file: ch06/6_4_composition.yaml
paths:
/books:
post:
[...]
components:
schemas:
BaseBook:
type: object
required:
- author
- title
properties:
title:
type: string
author:
type: string
Ebook:
allOf:
- $ref: #/components/schemas/BaseBook
- type: object
properties:
byte_size:
type: integer
PrintedBook:
allOf:
- $ref: #/components/schemas/BaseBook
- type: object
properties:
pages:
type: integer
Compare a shared base model with composed Ebook and PrintedBook models to see how common and type-specific properties can be separated. section 6.4.1
