api-field-descriptions

# 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