# Lerianstudio Ring API Field Descriptions > API Field Descriptions - Skill: `tomevault-io/lerianstudio-ring-api-field-descriptions` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/lerianstudio-ring-api-field-descriptions` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/lerianstudio-ring-api-field-descriptions/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/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) ```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., "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: 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. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/lerianstudio) — claim your Tome and manage your conversions.