home / skills / lerianstudio / ring / api-field-descriptions

api-field-descriptions skill

safe

This skill generates clear, consistent API field descriptions including type, constraints, examples, and edge cases to improve documentation quality.

npx playbooks add skill lerianstudio/ring --skill api-field-descriptions

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

3.8 KB

---
name: ring:api-field-descriptions
description: |
  Patterns for writing clear, consistent API field descriptions including
  types, constraints, examples, and edge cases.

trigger: |
  - Writing API field documentation
  - Documenting request/response schemas
  - Creating data model documentation

skip_when: |
  - Writing conceptual docs → use writing-functional-docs
  - Full API endpoint docs → use writing-api-docs

related:
  complementary: [writing-api-docs]
---

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

```markdown
| 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., "[email protected]")` |
| 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

Overview

This skill provides patterns and templates for writing clear, consistent API field descriptions that surface type, purpose, constraints, examples, and edge cases. It codifies a predictable table format, description patterns by data type, and guidance for request vs response semantics. The goal is faster authoring, fewer support questions, and higher-quality API docs consumed by engineers and integrators.

How this skill works

The skill inspects a field and produces a concise description following a checklist: purpose, data type, required/optional status, constraints, default/nullable behavior, examples, and any deprecation or read-only notes. It recommends a table-first format for lists of fields and specific sentence patterns per type (UUID, string, enum, boolean, integer, timestamp, object, array). It also handles nested fields (dot notation) and conditional requirement language.

When to use it

When drafting or reviewing API request and response schemas
When converting internal models into public documentation
When standardizing field language across multiple endpoints
When documenting edge cases like nullable fields, defaults, or conditional requirements
When marking deprecated or read-only fields to avoid consumer confusion

Best practices

Follow the table format: Field | Type | Required | Description for quick scanning
Always state purpose first, then type-specific constraints and an example
Use `—` for response-only fields and explicit `Yes/No/Conditional` for requests
Document ranges, max lengths, formats, and enum values inline (e.g., max 255 chars, UTC)
Mark deprecated and read-only fields clearly and explain relationships to other entities

Example use cases

Documenting an Account object: id: uuid — The unique identifier of the Account
Describing an enum field: status: enum — Account status: `ACTIVE`, `INACTIVE`, `BLOCKED`
Explaining conditional fields: promoCode: string — Required when plan = `trial`
Clarifying nullable timestamps: deletedAt: timestamptz — Soft deletion timestamp or `null` if not deleted
Listing arrays and nested fields: items: array — List of line items; items[].sku: string — Item SKU (max 50 chars)

FAQ

How should I document response-only fields?

Mark Required as `—` and note in the description that the field is read-only or system-generated.

What pattern should I use for enums?

List the purpose then inline allowed values using code formatting, e.g., Account status: `ACTIVE`, `INACTIVE`, `BLOCKED`.