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

OpenAPI extension mappings

Map selected operation-level x-* values into Shoalrun metadata without depending on a particular authoring service.

Updated
Read as Markdown

OpenAPI permits specification extensions whose names begin with x-. Their names and values belong to the tool or team that wrote the description. Shoalrun reads standard OpenAPI fields directly and applies an extension only when the project config explicitly maps it to a supported Shoalrun field.

Supported mapping

Use these source locations and value shapes when mapping OpenAPI extensions to Shoalrun fields.

Shoalrun target Source location Accepted source shape Shoalrun values
subjectLifecycle An operation under paths or OpenAPI 3.1 webhooks A scalar x-* value, or a scalar member inside an x-* object beta, in-development, experimental, deprecated

Use apis.<apiId>.mappings.subjectLifecycle. from starts with an operation-level x-* key. For an object, add a dot and the member name; further simple member names may follow. values maps exact source values to Shoalrun values. Unlisted, missing, null, array, or object values do not set a badge.

For example, this fictional OpenAPI operation uses an object-shaped extension:

openapi.yaml
paths:
  /widgets:
    get:
      operationId: listWidgets
      x-docs-availability:
        status: testing
        note: May change before general release
      responses:
        '200': { description: Widgets returned }

Map its status member without changing the OpenAPI file:

config/api.yaml
catalog:
  source: { kind: file, path: ../apis/catalog/openapi.yaml }
  mappings:
    subjectLifecycle:
      from: x-docs-availability.status
      values:
        testing: beta
        building: in-development
        retired: deprecated
  generateReferences: true

The listWidgets reference now shows Beta in its page header and navigation. Its Markdown twin and documents.json also report the mapped status. For a scalar extension such as x-docs-availability: testing, use from: x-docs-availability with the same values map. The source names are examples; the project chooses its own extension name and values.

An authored reference page's subjectLifecycle takes precedence over the mapping. OpenAPI deprecated: true always makes the operation Deprecated; a conflicting authored status fails the build. A mapping is scoped to one API registration and applies to that API's selected operations across its publications.

Other extension shapes

Extensions outside the supported mapping may need source changes or a different Shoalrun feature.

Source extension purpose Current Shoalrun behavior Use in Shoalrun today
Tag names and tag groups No automatic mapping Use OpenAPI tags for generated groups and navigation config for editorial grouping and MDX pages.
Custom code samples No automatic mapping Add an authored MDX example or reusable snippet; standard OpenAPI request and response examples still appear automatically.
Enum labels or descriptions No automatic mapping Standard enum values appear in schemas. Put explanatory prose in a schema or field description.
Hide or internal flags No automatic mapping Select public operations with generateReferences.include or explicit operations; set page access in authored frontmatter. Do not rely on an unrecognized extension to hide content.
Explorer settings and SDK naming No automatic mapping Shoalrun does not execute API requests. Keep SDK-specific settings in their owning tool.
Webhook markers in older descriptions No automatic mapping Describe inbound events with OpenAPI 3.1 webhooks.

An unmapped x-* value does not change the rendered reference. A focused contract omits extension properties while retaining literal example payload keys, even when those keys begin with x-. A full OpenAPI download enabled by source.publish: true contains the source file as authored, including its extensions. Review that file before publishing it.

Choosing a new mapping target

The target list above is intentionally small. An extension can describe presentation, visibility, SDK behavior, or actual wire semantics, and identical names do not guarantee identical shapes. When adding a target, define its source location, accepted value shapes, Shoalrun output, precedence over authored metadata and standard OpenAPI, and behavior for unknown values. Keep the source name configurable so projects can adapt descriptions from different tools without baking a vendor vocabulary into Shoalrun.