shield_lock
JinDaGe
← Back to skills
extension
Category: Development & EngineeringNo API key required

ring:api-field-descriptions

Patterns for writing clear, consistent API field descriptions including types, constraints, examples, and edge cases.

personAuthor: jakexiaohubgithub
open_in_newRepositorydownloadDownload package

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 | "Iftrue, [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:

  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

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