Schemas and Reuse
7. What is the components object, and how does $ref work?
components holds reusable definitions, and $ref points to them by URI. Reusable types include schemas, responses, parameters, examples, requestBodies, headers, securitySchemes, links, callbacks and pathItems. Version 3.2 adds mediaTypes.
A reference such as $ref: "#/components/schemas/User" is a JSON Pointer within the same document. It can also point to another file or URL.
In 3.1, a Reference Object may carry its own summary and description, which override the target's. Inside schemas, $ref follows JSON Schema rules and can sit next to other keywords.
8. How do oneOf, anyOf and allOf differ?
oneOf requires the data to match exactly one subschema, anyOf at least one, and allOf all of them.
oneOf: mutually exclusive shapes, such as a card payment or a bank payment.
anyOf: overlapping options, such as a contact that may have an email, a phone or both.
allOf: composition, such as a Dog that is a Pet plus its own fields.
A common oneOf bug is two subschemas that both accept the same object, for example because neither sets additionalProperties: false or a distinguishing required field. The data then matches both and fails validation.
9. What does the discriminator do?
The discriminator names a property whose value tells tools which subschema applies. It speeds up validation and helps code generators produce the right class.
Payment:
oneOf:
- $ref: "#/components/schemas/CardPayment"
- $ref: "#/components/schemas/BankPayment"
discriminator:
propertyName: method
mapping:
card: "#/components/schemas/CardPayment"
bank: "#/components/schemas/BankPayment"
It is a hint, not a validation rule: the oneOf still does the validating. OpenAPI 3.2 made propertyName optional and added defaultMapping, which picks a schema when the property is missing or has an unknown value.
10. How do you describe a file upload in OpenAPI 3.1?
Use multipart/form-data for a file sent with other fields, and describe the file with contentMediaType. For a raw binary body, a media type with no schema is enough.
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
orderId:
type: integer
invoice:
type: string
contentMediaType: application/pdf
This replaces 3.0's type: string, format: binary. For base64 text inside JSON, use contentEncoding: base64 rather than 3.0's format: byte.
11. What is the difference between format and pattern?
pattern is a regular expression the string must match; format names a known kind of value, such as date-time, email or uuid.
Under JSON Schema 2020-12, which OpenAPI 3.1 uses, format is an annotation by default. Many validators do not enforce it unless configured to.
So if a value must be checked, add a pattern, a maxLength or both, or turn on format assertion in your validator and test that it works.
A common surprise. A schema with format: email can pass invalid emails in a 3.1 validator that treats format as an annotation. Write a failing test for the rule you depend on before trusting it.
12. How do readOnly and writeOnly work?
readOnly: true marks a property that appears in responses but should not be sent in requests, such as id or createdAt. writeOnly: true marks one that is sent but never returned, such as password.
They let one schema serve both directions. In 3.1 they are JSON Schema annotations, not hard rules, and the 3.1.1 spec says a server MAY ignore a readOnly field in a request or treat it as an error.
A field that is both required and readOnly is required in a GET response, and the server can ignore it in a PUT. Tools handle this differently, so teams with strict clients often use separate request and response schemas.