Lerianstudio Ring API Field Descriptions

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

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

Writing Good Descriptions

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:

1. Load API documentation skill - ring:writing-api-docs for endpoint context
2. Load voice and tone - ring:voice-and-tone for consistent style
3. Verify data types - Confirm actual types from API schema

HARD GATE: CANNOT document fields without verified type information.

Blocker Criteria - STOP and Report

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

Pressure Resistance

Anti-Rationalization Table

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.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.