ring:api-field-descriptions

编写清晰、一致的API字段描述的通用模式，涵盖类型、约束、示例与边缘场景。

SKILL.md

--- frontmatter

name: ring: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)"