Skip to content
api-field-descriptions logo

API Field Descriptions

api-field-descriptions

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

SKILL.md

Full skill instructions

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

TypePatternExample
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., "[email protected]")
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

PatternFormat
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'tDo
"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

More Other skills

Delegate independent tasks to specialized agents working concurrently with isolated context.

295.4K 206.3K
View

Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.

179.7K 100.1K
View

Toolkit for styling artifacts with a theme. These artifacts can be slides, docs, reportings, HTML landing pages, etc. There are 10 pre-set themes with colors/fonts that you can apply to any artifact that has been creating, or can generate a new theme on-the-fly.

179.7K 89.5K
View

A set of resources to help me write all kinds of internal communications, using the formats that my company likes to use. Claude should use this skill whenever asked to write some sort of internal communications (status reports, leadership updates, 3P updates, company newsletters, FAQs, incident reports, project updates, etc.).

179.7K 76.1K
View

Fundamental design principles for writing maintainable, testable Python code.

40.2K 21.9K
View

Modern responsive layouts using container queries, fluid typography, CSS Grid, and mobile-first strategies.

40.2K 20K
View

Generate Playwright tests from scenarios using interactive browser exploration and validation.

39.7K 18.2K
View

Modern React state management with Redux Toolkit, Zustand, Jotai, and React Query for every state category.

40.2K 14.7K
View

GDPR-compliant data handling with consent management, data subject rights, and privacy controls.

40.2K 14.3K
View

Python error handling patterns including input validation, exception hierarchies, and partial failure handling. Use when implementing validation logic, designing exception strategies, handling batch processing failures, or building robust APIs.

40.2K 13.5K
View

Detailed multi-file refactor planning with safety checks and rollback guidance.

39.7K 13K
View