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 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)"

Quality Checklist

Standards Loading (MANDATORY)

Before writing field descriptions:

Load API documentation skill - ring:writing-api-docs for endpoint context
Load voice and tone - ring:voice-and-tone for 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.

ring:api-field-descriptions