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)

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

• 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-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.