[devin-ai-integration]

Summary

types: true is a new opt-in flag on an - api: navigation item in docs.yml. It gives every schema that no endpoint, webhook, or WebSocket references its own page in the API Reference. Before this, an API whose value lives in its schemas, such as an XML element vocabulary (TwiML-style paths: {} specs), shared models, or unwired event payloads, rendered nothing for those schemas. Now customers can document them, and each type page's example shows the values the API author wrote in the schema's example (for example, voice="alice" on a TwiML <Say> page) instead of placeholders, with every variant of a oneOf list.

Implements docs for:

• feat(docs): types: true on an api navigation item adds a Types section with a page per unreferenced schema (XML example for XML types) (fern-api/fern#18846)
• fix(docs): title the types: true section Schemas next to a GraphQL Types section; locale-stable sort (fern-api/fern#18853)
• feat(docs): standalone type pages (apiType navigation node) for schemas no operation references (fern-api/fern-platform#16145)
• feat(docs): type pages use the schema's provided example (fern-api/fern#18860)
• feat(docs): type definitions carry the schema's provided examples; type pages render them (fern-api/fern-platform#16172)

navigation:
  - api: API Reference
    types: true

Pages changed

• customize-api-ref.mdx (canonical): new ### Documenting standalone types section after "Paginating endpoints", plus a types ParamField in the configuration options reference. It covers:
  • the Types section, which comes last, is sorted by title, and lives at <api-reference>/types/<type-name>
  • referenced and inline schemas staying on their parent's page
  • the page contents: properties, values, or variants, plus an example in the side panel
  • examples (fern#18860, CLI 5.213.0; fern-platform#16172): the OpenAPI object schema's first example/examples entry, or one assembled from property-level examples only when every required property has one, otherwise placeholders; shown as XML for XML-encoded types and as JSON otherwise. An XML example writes only the properties the example sets, one element per list item, each oneOf item as the variant it matches. Includes a short OpenAPI example snippet.
  • search, llms.txt, and Markdown twin coverage
  • the Schemas title and slug when the API also has a GraphQL Types section
• generate-graphql-ref.mdx: one sentence in ## Types noting that types: true schema pages go in a separate Schemas section.
• sdks/deep-dives/xml-encoded-types.mdx: one sentence noting that standalone type pages in Fern Docs show an XML example for these types. The frozen legacy/ copy is left unchanged.
• fern-instructions/docs/api-reference.mdx: workflow step 4 now mentions types: true.

The cli-changelog/ directory was not edited.

Validation

• fern check --warnings (5.59.0): 0 errors. The 18 warnings are all pre-existing and unrelated.
• pre-commit/vale on the changed files: the new text has no findings. The one remaining vale error (customize-api-ref.mdx line 313, "API reference") is in existing playground.hidden text and was left alone.

Note: the docs.yml schema in fern#18846 marks types as availability: in-development, as it does for paginated. The page documents types without a beta label.

---

🟢 Devin Review found nothing to fix · View findings

[devin-ai-integration]

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

• Disable automatic comment, CI, and merge conflict monitoring

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

[github-actions]

🌿 Preview your docs: https://fern-preview-devin-1794676163-api-types-pages.docs.buildwithfern.com/learn

Here are the markdown pages you've updated:

• learn/docs/api-references/customize-api-reference-layout
• learn/docs/api-references/generate-graphql-ref
• learn/home/fern-instructions/docs/api-reference
• learn/sdks/deep-dives/xml-encoded-types