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 providedNo = OptionalConditional = 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
1---2name: api-field-descriptions3description: Patterns for writing clear, consistent API field descriptions including types, constraints, examples, and edge cases.4---5
6# API Field Descriptions
7
8Field descriptions are the most-read part of API documentation. Users scan for specific fields and need clear, consistent information.
9
10## Field Description Structure
11
12Every field description answers: **What is it?** (purpose), **What type?** (data type), **Required?** (mandatory), **Constraints?** (limits/validations), **Example?** (valid data)
13
14## Table Format (Preferred)
15
16```markdown
17| Field | Type | Required | Description |
18|-------|------|----------|-------------|
19| id | uuid | — | The unique identifier of the Account |
20| name | string | Yes | The display name of the Account (max 255 chars) |
21| status | enum | — | Account status: `ACTIVE`, `INACTIVE`, `BLOCKED` |
22```
23
24**Note:** Use `—` for response-only fields (not applicable for requests).
25
26For nested objects: `status.code`, `status.description`
27
28---
29
30## Description Patterns by Type
31
32| Type | Pattern | Example |
33|------|---------|---------|
34| UUID | "The unique identifier of the [Entity]" | `id: uuid — The unique identifier of the Account` |
35| String | "[Purpose] (constraints)" | `code: string — The asset code (max 10 chars, uppercase, e.g., "BRL")` |
36| String (format) | "[Purpose] (format example)" | `email: string — Email address (e.g., "user@example.com")` |
37| Enum | "[Purpose]: `val1`, `val2`, `val3`" | `type: enum — Asset type: \`currency\`, \`crypto\`, \`commodity\`` |
38| Boolean | "If `true`, [what happens]. Default: `[value]`" | `allowSending: boolean — If \`true\`, sending permitted. Default: \`true\`` |
39| Integer | "[Purpose] (range)" | `scale: integer — Decimal places (0-18)` |
40| Timestamp | "Timestamp of [event] (UTC)" | `createdAt: timestamptz — Timestamp of creation (UTC)` |
41| Object (jsonb) | "[Purpose] including [fields]" | `status: jsonb — Status information including code and description` |
42| Array | "List of [what it contains]" | `operations: array — List of operations in the transaction` |
43
44---
45
46## Required vs Optional
47
48**In Requests:**
49- `Yes` = Must be provided
50- `No` = Optional
51- `Conditional` = Required in specific scenarios (explain in description)
52
53**In Responses:** Use `—` (response fields are always returned or null)
54
55---
56
57## Special Field Documentation
58
59| Pattern | Format |
60|---------|--------|
61| Default values | "Results per page. Default: 10" |
62| Nullable fields | "Soft deletion timestamp, or `null` if not deleted" |
63| Deprecated fields | "**[Deprecated]** Use `route` instead" |
64| Read-only fields | "**Read-only.** Generated by the system" |
65| Relationships | "References an Asset code. Must exist in the Ledger" |
66
67---
68
69## Writing Good Descriptions
70
71| Don't | Do |
72|-------|-----|
73| "The name" | "The display name of the Account" |
74| "Status info" | "Account status: `ACTIVE`, `INACTIVE`, `BLOCKED`" |
75| "A number" | "Balance version, incremented with each transaction" |
76| "The code" | "The asset code (max 10 chars, uppercase)" |
77| "The timestamp" | "Timestamp of creation (UTC)" |
78
79---
80
81## Quality Checklist
82
83- [ ] Description explains the field's purpose
84- [ ] Data type is accurate
85- [ ] Required/optional status is clear
86- [ ] Constraints documented (max length, valid values)
87- [ ] Default value noted (if optional)
88- [ ] Nullable behavior explained (if applicable)
89- [ ] Deprecated fields marked
90- [ ] Read-only fields indicated
91- [ ] Relationships to other entities clear
92- [ ] Example values realistic
majiayu000