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
- 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
Standards Loading (MANDATORY)
Before writing field descriptions:
- Load API documentation skill -
ring:writing-api-docsfor endpoint context - Load voice and tone -
ring:voice-and-tonefor consistent style - Verify data types - Confirm actual types from API schema
HARD GATE: CANNOT document fields without verified type information.
Blocker Criteria - STOP and Report
| Condition | Decision | Action |
|---|---|---|
| Field types unknown | STOP | Report: "Need schema or type definitions" |
| Constraints not defined | STOP | Report: "Need validation rules for constraints" |
| Required/optional unclear | STOP | Report: "Need field requirement status" |
| Enum values undefined | STOP | Report: "Need complete list of enum values" |
| Default values unknown | STOP | Report: "Need default values for optional fields" |
Cannot Be Overridden
These requirements are NON-NEGOTIABLE:
- MUST document purpose for every field
- MUST include accurate data type
- MUST specify required vs optional status
- MUST document all constraints (length, format, range)
- MUST use realistic example values (not "foo", "bar")
- CANNOT leave fields undocumented
- CANNOT guess types or constraints
Severity Calibration
| Severity | Criteria | Examples |
|---|---|---|
| CRITICAL | Wrong type, missing required fields | Documents string as integer, skips required field |
| HIGH | Missing constraints, no examples | Max length undocumented, no example values |
| MEDIUM | Vague descriptions, inconsistent format | "The name" instead of "The display name of the Account" |
| LOW | Could be clearer, minor format issues | Description could include more context |
Pressure Resistance
| User Says | Your Response |
|---|---|
| "Field names are self-explanatory" | "Self-explanatory to you ≠ self-explanatory to users. MUST write explicit descriptions." |
| "Just copy the schema" | "Schema lacks context. MUST add purpose, constraints, and examples." |
| "Skip constraints, they're in validation" | "Constraints MUST be documented. Users shouldn't discover limits via errors." |
| "Use placeholder examples (foo, bar)" | "MUST use realistic examples. Placeholders don't demonstrate proper usage." |
| "Required/optional is obvious" | "Nothing is obvious. MUST explicitly mark required vs optional." |
Anti-Rationalization Table
| Rationalization | Why It's WRONG | Required Action |
|---|---|---|
| "Schema documents the type" | Schema doesn't explain purpose or usage | MUST add human description |
| "ID fields don't need description" | Users need to know what ID refers to | Document ALL fields including IDs |
| "Boolean is self-documenting" | Users need to know effect of true/false | MUST explain boolean behavior |
| "Timestamp format is standard" | Which standard? Timezone? Format? | MUST specify format and timezone |
| "Enum values are obvious" | Enum meanings may not be clear | MUST describe each enum value |
| "Same field, same description everywhere" | Context may differ | Tailor description to context |
When This Skill is Not Needed
Signs that field descriptions already meet standards:
- ALL fields have purpose-explaining descriptions
- ALL data types documented accurately
- ALL required/optional status clearly marked
- ALL constraints documented (length, format, valid values)
- ALL default values noted for optional fields
- ALL nullable behavior explained
- ALL deprecated fields marked with migration path
- ALL examples use realistic values
If all above are true: Field descriptions are complete, no changes needed.