7.5 KiB
7.5 KiB
name, description, trigger, skip_when, related
| name | description | trigger | skip_when | related | |||
|---|---|---|---|---|---|---|---|
| api-field-descriptions | Patterns for writing clear, consistent API field descriptions including types, constraints, examples, and edge cases. | - Writing API field documentation - Documenting request/response schemas - Creating data model documentation | - Writing conceptual docs → use writing-functional-docs - Full API endpoint docs → use 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 should answer:
- What is it? – The field's purpose
- What type? – Data type and format
- Required? – Is it mandatory?
- Constraints? – Limits, validations, formats
- Example? – What does valid data look like?
Basic Field Description Format
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).
Nested Object Format
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| status | object | — | Account status information |
| status.code | string | — | Status code: `ACTIVE`, `INACTIVE`, `BLOCKED` |
| status.description | string | — | Optional human-readable description |
Description Patterns by Type
UUID Fields
| id | uuid | — | The unique identifier of the Account |
| organizationId | uuid | Yes | The unique identifier of the Organization |
Pattern: "The unique identifier of the [Entity]"
String Fields
Simple string:
| name | string | Yes | The display name of the Account |
String with constraints:
| code | string | Yes | The asset code (max 10 chars, uppercase, e.g., "BRL") |
| alias | string | No | A user-friendly identifier (must start with @) |
String with format:
| email | string | Yes | Email address (e.g., "user@example.com") |
| phone | string | No | Phone number in E.164 format (e.g., "+5511999999999") |
Enum Fields
| type | enum | Yes | Asset type: `currency`, `crypto`, `commodity`, `others` |
| status | enum | — | Transaction status: `pending`, `completed`, `reversed` |
Pattern: "[Field purpose]: value1, value2, value3"
Always list all valid values in backticks.
Boolean Fields
| allowSending | boolean | No | If `true`, sending transactions is permitted. Default: `true` |
| allowReceiving | boolean | No | If `true`, receiving transactions is permitted. Default: `true` |
Pattern: "If true, [what happens]. Default: [value]"
Numeric Fields
Integer:
| version | integer | — | Balance version, incremented with each transaction |
| limit | integer | No | Results per page (1-100). Default: 10 |
With range:
| scale | integer | Yes | Decimal places for the asset (0-18) |
Timestamp Fields
| createdAt | timestamptz | — | Timestamp of creation (UTC) |
| updatedAt | timestamptz | — | Timestamp of last update (UTC) |
| deletedAt | timestamptz | — | Timestamp of soft deletion, if applicable (UTC) |
Pattern: "Timestamp of [event] (UTC)"
Always specify UTC.
Object Fields (JSONB)
| metadata | jsonb | No | Key-value pairs for custom data |
| status | jsonb | — | Status information including code and description |
| address | jsonb | No | Address information (street, city, country, postalCode) |
For complex objects, document child fields separately or link to schema.
Array Fields
| source | array | Yes | List of source account aliases |
| operations | array | — | List of operations in the transaction |
| tags | array | No | List of string tags for categorization |
Specify what the array contains.
Required vs Optional
In Request Documentation
| Indicator | Meaning |
|---|---|
| Yes | Field must be provided |
| No | Field is optional |
| Conditional | Required in specific scenarios (explain in description) |
Conditional example:
| portfolioId | uuid | Conditional | Required when creating customer accounts |
In Response Documentation
Response fields don't have "Required" – they're always returned (or null).
Use — in the Required column for response-only fields.
Default Values
Always document defaults for optional fields:
| limit | integer | No | Results per page. Default: 10 |
| allowSending | boolean | No | Permit sending. Default: `true` |
| type | string | No | Account type. Default: none (untyped) |
Nullable Fields
Indicate when fields can be null:
| deletedAt | timestamptz | — | Soft deletion timestamp, or `null` if not deleted |
| description | string | No | Optional description, or `null` if not provided |
| parentAccountId | uuid | No | Parent account ID, or `null` for root accounts |
Deprecated Fields
Mark deprecated fields clearly:
| chartOfAccounts | string | No | **[Deprecated]** Use `route` instead |
Or with more context:
| chartOfAccountsGroupName | string | — | **[Deprecated]** This field is present for backward compatibility. Use `route` for new integrations. |
Read-Only Fields
Indicate fields that can't be set by the client:
| id | uuid | — | **Read-only.** Generated by the system |
| createdAt | timestamptz | — | **Read-only.** Set automatically on creation |
| version | integer | — | **Read-only.** Incremented automatically |
Field Relationship Descriptions
When fields relate to other entities:
| ledgerId | uuid | Yes | The unique identifier of the Ledger this account belongs to |
| portfolioId | uuid | No | The Portfolio grouping this account. See [Portfolios](link) |
| assetCode | string | Yes | References an Asset code. Must exist in the Ledger |
Writing Good Descriptions
Be Specific
| Vague | Specific |
|---|---|
| The name | The display name of the Account |
| Status info | Account status: ACTIVE, INACTIVE, BLOCKED |
| A number | Balance version, incremented with each transaction |
Include Constraints
| Missing Constraints | With Constraints |
|---|---|
| The code | The asset code (max 10 chars, uppercase) |
| Page number | Page number (starts at 1) |
| Amount | Amount in smallest unit (e.g., cents for BRL) |
Add Context
| No Context | With Context |
|---|---|
| The timestamp | Timestamp of creation (UTC) |
| Account ID | The Account receiving the funds |
| Parent ID | Parent account for hierarchical structures |
Quality Checklist
For each field, verify:
- Description explains the field's purpose
- Data type is accurate
- Required/optional status is clear
- Constraints are documented (max length, valid values)
- Default value noted (if optional)
- Nullable behavior explained (if applicable)
- Deprecated fields are marked
- Read-only fields are indicated
- Relationships to other entities are clear
- Example values are realistic