Initial commit

2025-11-30 08:37:25 +08:00
commit 71961f9eff
18 changed files with 3314 additions and 0 deletions
--- a/skills/api-field-descriptions/SKILL.md
+++ b/skills/api-field-descriptions/SKILL.md
@@ -0,0 +1,303 @@
+---
+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 should answer:
+
+1. **What is it?** – The field's purpose
+2. **What type?** – Data type and format
+3. **Required?** – Is it mandatory?
+4. **Constraints?** – Limits, validations, formats
+5. **Example?** – What does valid data look like?
+
+---
+
+## Basic Field Description Format
+
+### 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).
+
+### Nested Object Format
+
+```markdown
+| 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
+
+```markdown
+| 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:**
+```markdown
+| name | string | Yes | The display name of the Account |
+```
+
+**String with constraints:**
+```markdown
+| 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:**
+```markdown
+| email | string | Yes | Email address (e.g., "user@example.com") |
+| phone | string | No | Phone number in E.164 format (e.g., "+5511999999999") |
+```
+
+---
+
+### Enum Fields
+
+```markdown
+| 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
+
+```markdown
+| 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:**
+```markdown
+| version | integer | — | Balance version, incremented with each transaction |
+| limit | integer | No | Results per page (1-100). Default: 10 |
+```
+
+**With range:**
+```markdown
+| scale | integer | Yes | Decimal places for the asset (0-18) |
+```
+
+---
+
+### Timestamp Fields
+
+```markdown
+| 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)
+
+```markdown
+| 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
+
+```markdown
+| 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:**
+```markdown
+| 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:
+
+```markdown
+| 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:
+
+```markdown
+| 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:
+
+```markdown
+| chartOfAccounts | string | No | **[Deprecated]** Use `route` instead |
+```
+
+Or with more context:
+
+```markdown
+| 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:
+
+```markdown
+| 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:
+
+```markdown
+| 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