---

name: api-field-descriptions description: | Patterns for writing clear, consistent API field descriptions including types, constraints, examples, and edge cases.

trigger: |

• Writing API field documentation
• Documenting request/response schemas
• Creating data model documentation

skip_when: |

• Writing conceptual docs → use writing-functional-docs
• Full API endpoint docs → use writing-api-docs

related: 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