Shoalrun documentation framework
For agents
Start with https://www.shoalrun.com/llms.txt for the documentation index, then read the Markdown pages it links. Skip to article. Documentation index. Read this page as Markdown.
Reference

Fields

Write field lists in MDX with the same readable format as OpenAPI schemas.

Updated
Read as Markdown

Use <Fields> and <Field> to describe fields that are not selected from an OpenAPI schema, or to explain a small task-specific subset in your own words. The list uses the same field styling as generated schemas. If the exact contract already exists in OpenAPI, ApiSchema can include the source schema or one of its fields.

Syntax

<Fields>
<Field name="name" type="string" required minLength="1" maxLength="80" example="Casey">

The name shown to readers.

</Field>
<Field name="options" type="object" optional nullable>

Extra display settings.

<Fields>
<Field name="compact" type="boolean" optional default="false">

Use a shorter layout.

</Field>
</Fields>

</Field>
</Fields>

  • name — required

    string; minLength: 1; maxLength: 80

    Example: Casey

    The name shown to readers.

  • options — optional

    object; nullable

    Extra display settings.

    • compact — optional

      boolean

      Default: false

      Use a shorter layout.

Fields takes no attributes and needs direct Field children. A Field body accepts ordinary Markdown and supported MDX, including a nested Fields list. A standalone Field or other direct child of Fields fails the build.

Attribute reference

All values are literal MDX attributes. Text and numbers use quoted strings; flags are bare attributes. These declarations describe fields in the published page. They do not validate user input at runtime.

Field attribute Required Meaning
name Yes Nonempty field name.
type Yes Nonempty type label, such as string, integer, or array of objects.
required, optional No Bare presence flags. Omission means optional; the two flags cannot appear together.
nullable No Bare flag allowing a null value. It does not change whether the field is present.
min, max No Finite numeric value bounds; minimum and maximum are equivalent spellings.
minLength, maxLength No Nonnegative integer string-length bounds.
minItems, maxItems No Nonnegative integer array-size bounds.
format, pattern No Nonempty text for a format name or pattern.
example, default No Literal text shown as an example or default value.
deprecated No Bare flag marking the field as deprecated.

Bounds must be numeric, and each minimum must be no greater than its maximum. min cannot be combined with minimum, nor max with maximum. Keep the declared type, constraints, and examples consistent with the actual contract.

<Fields>
<Field name="rank" type="integer" optional min="0" max="10" example="3">

Position in the list.

</Field>
</Fields>

HTML, Markdown, and agents

The build writes a normal nested Markdown list. Each item starts with the field name and presence rule, followed by its type and authored body. For the first field above, the twin contains:

- `name` — **required**

  string; minLength: 1; maxLength: 80

  Example: `Casey`

  The name shown to readers.

Both formats include every field and description. The authored text is part of the page rather than copied from OpenAPI, so keep it aligned with the contract when it describes an API.