OpenAPI Field Descriptions — Writing Vocabulary

Good OpenAPI description: 'The order total in the currency specified by the currency_code field. Includes tax but excludes shipping. Precision: 2 decimal places. Example: 49.99 for a $49.99 order.' Poor description: 'Order total.' Good descriptions explain the business meaning, not just the data type — the data type is already visible in the schema.

Description: explains meaning, constraints, behavior. Example: shows a concrete value. Both together: 'description: ISO 8601 timestamp of when the order was placed. Must be in UTC. example: 2024-03-15T14:30:00Z.' Examples are especially valuable for formatted strings (dates, phone numbers, addresses) where the format may not be obvious from the description alone.

Optional: the field may be absent from the JSON object entirely. Nullable: the field is present but its value is null. These are orthogonal: a field can be optional AND nullable, optional AND non-nullable, required AND nullable, or required AND non-nullable. Confusing them leads to incorrect client implementations.

Discriminator: in a polymorphic schema (oneOf: [Cat, Dog, Bird]), the discriminator (e.g., species field) tells clients which subschema to use. Without a discriminator, clients must guess or try each schema. With a discriminator: if species = 'cat', use the Cat schema. Discriminators make polymorphic API responses parseable without guesswork.

readOnly: present in response bodies, ignored/not allowed in request bodies. Examples: id (assigned by server), createdAt (set by server). writeOnly: accepted in request bodies, not returned in responses. Example: password (never expose in API response). These help generate accurate client SDKs and documentation.