Learn to write clear OpenAPI field descriptions: property descriptions, examples, and schema documentation.
0 / 18 completed
1 / 18
What makes a good OpenAPI property description?
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.
2 / 18
What is the difference between 'description' and 'example' in OpenAPI?
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.
3 / 18
What is 'nullable' vs. 'optional' in OpenAPI schema vocabulary?
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.
4 / 18
What is a 'discriminator' in OpenAPI schema vocabulary?
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.
5 / 18
What are 'readOnly' and 'writeOnly' in OpenAPI schema vocabulary?
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.
6 / 18
Reviewer: 'The `transactionId` field in the `PaymentResponse` schema just says 'Unique identifier'. That's not helpful. Can you add a description explaining it's a UUID and that it should be used for tracking payment requests?
You: (Responding to the code review comment)
Which of the following descriptions would be most appropriate for the `transactionId` field in this OpenAPI schema?
The reviewer's comment highlights the importance of clear and informative descriptions. Simply stating 'Unique identifier' doesn't convey crucial technical details like UUID format or intended usage. Option 2 accurately reflects a positive response acknowledging the need for clarification while providing the requested information. Options 1 and 3 are too vague, and option 4 dismisses the reviewer's feedback completely.
7 / 18
During a code review of a new API endpoint for processing orders, Sarah comments on the `transactionId` field in the `OrderResponse` schema:
'This field just says 'Unique identifier'. It's too vague! We need to clearly state that it's a UUID and explain how we use it internally for tracking order requests. It should also mention potential limitations, like its length.'
Which of the following descriptions would be most appropriate for the `transactionId` field in this OpenAPI schema?
{"schema": {"type": "string","format": "uuid","description": "A Universally Unique Identifier (UUID) used to uniquely identify each order request. This UUID is critical for correlating logs, debugging issues, and tracking the lifecycle of the order.",}}
This question presents a realistic scenario from a code review. The key misconception here is assuming 'Unique identifier' is sufficient. A good OpenAPI description needs to provide context and technical detail. Using the term 'UUID' immediately clarifies the data type and its purpose – which is crucial for developers consuming the API. The provided option clearly explains the UUID's function and importance, aligning with best practices for API documentation.
8 / 18
Reviewer: 'The `transactionId` field in the `PaymentResponse` schema just says 'Unique identifier'. That's not helpful. Can you add a description explaining it's a UUID and that it should be used for tracking payment requests?
You: (Responding to the code review comment)
Which of the following descriptions would be most appropriate for the `transactionId` field in this OpenAPI schema?
The reviewer's comment highlights the importance of clear and informative descriptions. Simply stating 'Unique identifier' doesn't convey crucial technical details like UUID format or intended usage. Option 2 accurately reflects a positive response acknowledging the need for clarification while providing the requested information. Options 1 and 3 are too vague, and option 4 dismisses the reviewer's feedback completely.
9 / 18
During a code review of a new API endpoint for processing orders, Sarah comments on the `transactionId` field in the `OrderResponse` schema:
'This field just says 'Unique identifier'. It's too vague! We need to clearly state that it's a UUID and explain how we use it internally for tracking order requests. It should also mention potential limitations, like its length.'
Which of the following descriptions would be most appropriate for the `transactionId` field in this OpenAPI schema?
{"schema": {"type": "string","format": "uuid","description": "A Universally Unique Identifier (UUID) used to uniquely identify each order request. This UUID is critical for correlating logs, debugging issues, and tracking the lifecycle of the order.",}}
This question presents a realistic scenario from a code review. The key misconception here is assuming 'Unique identifier' is sufficient. A good OpenAPI description needs to provide context and technical detail. Using the term 'UUID' immediately clarifies the data type and its purpose – which is crucial for developers consuming the API. The provided option clearly explains the UUID's function and importance, aligning with best practices for API documentation.
10 / 18
Reviewer: 'The `transactionId` field in the `PaymentResponse` schema just says 'Unique identifier'. That's not helpful. Can you add a description explaining it's a UUID and that it should be used for tracking payment requests?
You: (Responding to the code review comment)
Which of the following descriptions would be most appropriate for the `transactionId` field in this OpenAPI schema?
The reviewer's comment highlights the importance of clear and informative descriptions. Simply stating 'Unique identifier' doesn't convey crucial technical details like UUID format or intended usage. Option 2 accurately reflects a positive response acknowledging the need for clarification while providing the requested information. Options 1 and 3 are too vague, and option 4 dismisses the reviewer's feedback completely.
11 / 18
During a code review of a new API endpoint for processing orders, Sarah comments on the `transactionId` field in the `OrderResponse` schema:
'This field just says 'Unique identifier'. It's too vague! We need to clearly state that it's a UUID and explain how we use it internally for tracking order requests. It should also mention potential limitations, like its length.'
Which of the following descriptions would be most appropriate for the `transactionId` field in this OpenAPI schema?
{"schema": {"type": "string","format": "uuid","description": "A Universally Unique Identifier (UUID) used to uniquely identify each order request. This UUID is critical for correlating logs, debugging issues, and tracking the lifecycle of the order.",}}
This question presents a realistic scenario from a code review. The key misconception here is assuming 'Unique identifier' is sufficient. A good OpenAPI description needs to provide context and technical detail. Using the term 'UUID' immediately clarifies the data type and its purpose – which is crucial for developers consuming the API. The provided option clearly explains the UUID's function and importance, aligning with best practices for API documentation.
12 / 18
Reviewer: 'The `transactionId` field in the `PaymentResponse` schema just says 'Unique identifier'. That's not helpful. Can you add a description explaining it's a UUID and that it should be used for tracking payment requests?
You: (Responding to the code review comment)
Which of the following descriptions would be most appropriate for the `transactionId` field in this OpenAPI schema?
The reviewer's comment highlights the importance of clear and informative descriptions. Simply stating 'Unique identifier' doesn't convey crucial technical details like UUID format or intended usage. Option 2 accurately reflects a positive response acknowledging the need for clarification while providing the requested information. Options 1 and 3 are too vague, and option 4 dismisses the reviewer's feedback completely.
13 / 18
During a code review of a new API endpoint for processing orders, Sarah comments on the `transactionId` field in the `OrderResponse` schema:
'This field just says 'Unique identifier'. It's too vague! We need to clearly state that it's a UUID and explain how we use it internally for tracking order requests. It should also mention potential limitations, like its length.'
Which of the following descriptions would be most appropriate for the `transactionId` field in this OpenAPI schema?
{"schema": {"type": "string","format": "uuid","description": "A Universally Unique Identifier (UUID) used to uniquely identify each order request. This UUID is critical for correlating logs, debugging issues, and tracking the lifecycle of the order.",}}
This question presents a realistic scenario from a code review. The key misconception here is assuming 'Unique identifier' is sufficient. A good OpenAPI description needs to provide context and technical detail. Using the term 'UUID' immediately clarifies the data type and its purpose – which is crucial for developers consuming the API. The provided option clearly explains the UUID's function and importance, aligning with best practices for API documentation.
14 / 18
Mark is reviewing a new API endpoint for user profiles. He sees the field `firstName` in the response schema and wonders if it's necessary to include an example value. What's the best approach according to OpenAPI documentation?
// OpenAPI definition snippet
{
"name": "User",
"properties": {
"firstName": {
"type": "string",
"description": "The user's first name.",
"example": "John"
}
}
}
While a description clarifies the meaning of the `firstName` field, including an example demonstrates exactly what data type and format is expected. Including examples primarily benefits clarity for simpler data types like strings and numbers, making it easier to understand without needing lengthy descriptions. It's important to note that 'example' should *not* be used to enforce specific values; it's merely illustrative.
15 / 18
During a Slack discussion about the `customerID` field in an API response, David asks: 'Does this need a description? It's just a number.'. What is the *most* appropriate response?
David types: 'Does this need a description? It's just a number.'
Even though `customerID` is a number, it's still a field in an API response and represents a critical piece of data. A description clarifies its role as the unique identifier for the customer – this avoids potential confusion and ensures consistent usage across the system. While David's question highlights a common misunderstanding, emphasizing the need for context is key.
16 / 18
You're writing a PR description for a change that adds a `status` field to the `OrderResponse` schema. The status can be one of 'Pending', 'Shipped', or 'Delivered'. What's the *best* way to describe this field in the PR's description?
Your PR description starts: 'Added a new status field…'
The most descriptive option clearly states the possible values for the `status` field. This provides immediate understanding for anyone reading the PR and ensures consistency in how the field is interpreted. While other options touch on aspects of the field's purpose, they lack the specificity needed to fully communicate its constraints.
17 / 18
During a standup meeting, Alex mentions that he's working on an API endpoint for processing payments. He's unsure about the best way to describe the `amount` field in the response schema. His teammate suggests using the term 'currency'. What does this suggest about how to approach describing OpenAPI fields?
Alex asks: 'How should I describe the amount field?'
Specifying the currency associated with the `amount` field is vital. Without this context, developers might incorrectly interpret the value or attempt to use it in calculations without considering the correct currency conversion rates. OpenAPI documentation should always aim to minimize ambiguity, and currency is a key element of financial transactions.
18 / 18
You are designing an API for managing products. You have a field called `productCode` in the response schema. What's the *most* important consideration when writing its description?
{
"name": "Product",
"properties": {
"productCode": {
"type": "string",
"description": "..."
}
}
}
The primary function of a `productCode` is to uniquely identify each product. The description must clearly articulate this role and its relationship to the broader product catalog. Simply stating 'Unique product code' is too generic; it doesn't convey the significance of this identifier within the system.
What will I practice in "OpenAPI Field Descriptions — Writing Vocabulary"?
This is an API Spec Writing exercise set. It walks through 18 scenario-based multiple-choice questions built around real usage of API Spec Writing terminology that IT professionals encounter on the job.
Is this exercise free to use?
Yes. Every exercise on CoderSlingo, including this one, is free to complete with no account, sign-up, or paywall.
How many questions are in this exercise?
This set contains 18 questions. Each one shows immediate feedback and a detailed explanation after you answer, so you learn the correct usage right away rather than waiting for a final score.
Do I need prior experience to complete this exercise?
No prior experience is required. Each question includes a full explanation covering the reasoning behind the correct answer, so the exercise itself teaches the API Spec Writing vocabulary as you go.
Can I retry the exercise if I get questions wrong?
Yes — use the "Try again" button on the results screen to reset your answers and go through all the questions again. There is no limit on attempts.
Is my progress saved?
Your answers and score for the current session are tracked in the browser as you go. No account or login is needed, and there is nothing to install.
What if I don't understand a term used in a question?
Read the explanation shown after you answer each question — it breaks down the correct term in plain English with a real-world example. You can also check the site Glossary for quick definitions.
How is this different from reading a blog article on the topic?
Exercises like this one are interactive drills that test and reinforce specific vocabulary through multiple-choice questions, while blog articles explain concepts in prose. Practising here after reading builds active recall, not just passive recognition.
Where can I find more API Spec Writing exercises?
See the API Spec Writing exercises hub for the full set of related pages, or browse all exercise categories from the main Exercises index.
Can I use this exercise to prepare for a technical interview?
Yes — API Spec Writing vocabulary comes up often in technical discussions and interviews. Pair this exercise with our dedicated Interview Preparation section for role-specific practice.