---
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)

```markdown
| 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