api-field-descriptions

Patterns for writing clear, consistent API field descriptions includingtypes, constraints, examples, and edge cases.

⭐25stars🔀1forks📁View on GitHub🕐Updated Dec 31, 2025⬇️2downloads

When & Why to Use This Skill

This Claude skill provides a standardized framework for crafting clear, consistent, and professional API field descriptions. It focuses on improving developer experience (DX) by ensuring that request and response schemas include essential details such as data types, constraints, realistic examples, and edge cases, following industry best practices for technical documentation.

Use Cases

  • Standardizing API Documentation: Use predefined patterns to ensure all field descriptions across your REST or GraphQL API follow a consistent format, making them easier for third-party developers to consume.
  • Documenting Request/Response Schemas: Generate precise descriptions for complex data models, including clear indicators for required vs. optional fields, default values, and nullable states.
  • Improving API Usability: Enhance auto-generated documentation (like Swagger or OpenAPI) by replacing vague descriptions with structured information that includes constraints (e.g., max length, enum values) and realistic examples.
  • Technical Writing Quality Control: Use the provided checklist to audit existing API documentation for completeness, ensuring that all edge cases and system-generated fields are properly explained.
namering:api-field-descriptions
description|
trigger|
skip_when|
complementary[writing-api-docs]

API Field Descriptions

Field descriptions are the most-read part of API documentation. Users scan for specific fields and need clear, consistent information.

Field Description Structure

Every field description answers: What is it? (purpose), What type? (data type), Required? (mandatory), Constraints? (limits/validations), Example? (valid data)

Table Format (Preferred)

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| id | uuid | — | The unique identifier of the Account |
| name | string | Yes | The display name of the Account (max 255 chars) |
| status | enum | — | Account status: `ACTIVE`, `INACTIVE`, `BLOCKED` |

Note: Use — for response-only fields (not applicable for requests).

For nested objects: status.code, status.description


Description Patterns by Type

Type Pattern Example
UUID "The unique identifier of the [Entity]" id: uuid — The unique identifier of the Account
String "[Purpose] (constraints)" code: string — The asset code (max 10 chars, uppercase, e.g., "BRL")
String (format) "[Purpose] (format example)" email: string — Email address (e.g., "user@example.com")
Enum "[Purpose]: val1, val2, val3" type: enum — Asset type: \currency`, `crypto`, `commodity``
Boolean "If true, [what happens]. Default: [value]" allowSending: boolean — If \true`, sending permitted. Default: `true``
Integer "[Purpose] (range)" scale: integer — Decimal places (0-18)
Timestamp "Timestamp of [event] (UTC)" createdAt: timestamptz — Timestamp of creation (UTC)
Object (jsonb) "[Purpose] including [fields]" status: jsonb — Status information including code and description
Array "List of [what it contains]" operations: array — List of operations in the transaction

Required vs Optional

In Requests:

  • Yes = Must be provided
  • No = Optional
  • Conditional = Required in specific scenarios (explain in description)

In Responses: Use — (response fields are always returned or null)


Special Field Documentation

Pattern Format
Default values "Results per page. Default: 10"
Nullable fields "Soft deletion timestamp, or null if not deleted"
Deprecated fields "[Deprecated] Use route instead"
Read-only fields "Read-only. Generated by the system"
Relationships "References an Asset code. Must exist in the Ledger"

Writing Good Descriptions

Don't Do
"The name" "The display name of the Account"
"Status info" "Account status: ACTIVE, INACTIVE, BLOCKED"
"A number" "Balance version, incremented with each transaction"
"The code" "The asset code (max 10 chars, uppercase)"
"The timestamp" "Timestamp of creation (UTC)"

Quality Checklist

  • Description explains the field's purpose
  • Data type is accurate
  • Required/optional status is clear
  • Constraints documented (max length, valid values)
  • Default value noted (if optional)
  • Nullable behavior explained (if applicable)
  • Deprecated fields marked
  • Read-only fields indicated
  • Relationships to other entities clear
  • Example values realistic