A required flag marks whether a property must be present in an operation’s data. It answers two practical questions: what consumers must provide and what the implementation always returns. Because required data affects validation, testing, and user experience, the decision should reflect both domain essentials and operation context. section 5.2.4 section 5.3.1
Apply the flag separately at each model level and operation boundary:
- In a product model, productReference, name, and price are essential; description and keywords may be absent. section 5.2.4
- Nested objects need their own decisions: a required supplier object does not make every supplier property required; supplierCode can be required while description remains optional. section 5.2.4
- For a read operation, required properties are returned for every resource, while nonrequired properties may be omitted. section 5.3.1
- For creation, required properties are values the consumer must provide; server-managed properties such as productReference and dateAdded are excluded from the creation input. section 5.3.3
Product catalog
A GET /products/{productReference} response always includes name and price, but may omit description. A POST /products request requires name while allowing description; the server generates productReference and dateAdded. In JSON Schema, the product model expresses these property requirements, while an OpenAPI response header such as Location is marked required when it is always returned. section 5.3.1 section 5.3.3 section 7.4 section 6.8.3
Figure 5.10 The operation output is the Product resource model; required properties are always returned. The productReference path parameter is based on the productReference property.
Use the operation model to connect the productReference path parameter with the product resource and see which output properties are always returned. section 5.3.1
