English for Writing a JSON Schema with Clear Field Descriptions

A JSON Schema is only as useful as its descriptions. The schema itself enforces structure, but the English inside "description" fields is what actually tells another developer — or an API consumer reading generated docs — what a field means, when to use it, and what happens if they get it wrong. This guide covers the phrasing conventions for writing schema descriptions that hold up.

Key Vocabulary

Field description — the human-readable explanation attached to a schema property, typically surfaced directly in generated API documentation. “The description isn’t just ‘the user’s ID’ — it specifies ‘the internal UUID assigned at account creation, distinct from the public-facing username.’”

Constraint — a rule limiting valid values for a field, such as a minimum, maximum, pattern, or enum, which should be explained in English, not left implicit in the schema alone. “The description states the constraint explicitly: ‘Must be between 1 and 100 inclusive; values outside this range return a 400 error,’ rather than leaving the reader to infer it from the minimum/maximum keywords alone.”

Default value — the value used when a field is omitted, which should always be stated explicitly rather than assumed obvious. “Description: ‘Number of results per page. Defaults to 20 if omitted. Maximum allowed is 100.’”

Nullable vs. optional — a distinction between a field that can be entirely absent (optional) and one that must be present but can hold a null value (nullable); conflating the two in a description causes real bugs. “This field is nullable, not optional — it must always be present in the response, but its value will be null until the user completes onboarding.”

Example value — a concrete sample value included in the schema, used to remove ambiguity that prose alone often can’t fully resolve. “Rather than just describing the date format in words, we included an example: \"2026-07-02T14:30:00Z\", which resolves any ambiguity about timezone handling immediately.”

Common Phrases

• “This field represents [what it means], not [common misunderstanding].”
• “Defaults to [value] if omitted.”
• “Must be [constraint]; values outside this range return [specific error].”
• “This field is nullable — always present, but may be null until [condition].”
• “See the example value for the expected format.”

Example Sentences

Writing a description that removes a likely ambiguity: ""description”: “The total price in the smallest currency unit (e.g., cents for USD), not the decimal amount. For example, $12.50 is represented as 1250.""

Documenting a constraint with its consequence, not just its rule: ""description”: “Page size for paginated results. Must be between 1 and 100. Requests with a page size above 100 are not rejected — they are silently capped at 100, so check the ‘pageSize’ field in the response to confirm what was actually used.""

Distinguishing nullable from optional explicitly, because the schema syntax alone doesn’t make this clear: ""description”: “The user’s verified email address. This field is always present in the response object, but will be null until the user completes email verification — do not treat a missing key as equivalent to this being empty.""

Writing a description for a field whose name alone is ambiguous: ""description”: “‘status’ refers to the shipment’s current state (e.g., ‘in_transit’, ‘delivered’), not the API request’s HTTP status. See the ‘ShipmentStatus’ enum for the full list of valid values.""

Professional Tips

• Write descriptions that address the most likely misunderstanding, not just a restatement of the field name — “the total price in cents, not dollars” is far more useful than “the price.”
• Always state the default value explicitly in the description, even if it’s also encoded in a "default" keyword — not every schema consumer or tool surfaces that keyword clearly.
• Explicitly distinguish nullable from optional when a field could be confused for either — this distinction causes real production bugs when consumers assume the wrong one.
• Pair constraints with their consequence, not just the rule — “capped at 100” tells a developer what actually happens, while “must be ≤ 100” alone doesn’t say what happens if they send 150.
• Include a concrete example value for any field where format is ambiguous (dates, currency, encoded IDs) — prose descriptions of format are often misread, but an example rarely is.

Practice Exercise

1. Write a field description for a hypothetical “amount” field that clarifies its unit and format.
2. Write a description distinguishing a nullable field from an optional one.
3. Write a description for a constrained field that states both the rule and what happens if it’s violated.