Support requestBody examples using OpenAPI externalValue

Problem

OpenAPI already provides externalValue on an Example Object for examples that are stored externally instead of being embedded in the OpenAPI document.

For APIs with hundreds or thousands of request examples, embedding every payload directly into the OpenAPI document unnecessarily increases document size, generation time, transfer size and parsing time.

Instead, the OpenAPI document can reference externally stored examples.

Example:

requestBody:
  content:
    application/json:
      examples:
        ups-standard:
          summary: Shipper Standard
          externalValue: /api-docs/examples/post-shipment/shipper-standard

The referenced endpoint simply returns the serialized JSON request:

{
  "shippingType": "Shipper_001",
  "packages": [
    ...
  ]
}

This keeps the OpenAPI document small while allowing the full payload to be retrieved only when needed.

Current behavior

The native example selector displays examples correctly.

However, selecting an example does not appear to resolve externalValue for request examples.

As a result:

• generated code snippets do not contain the external payload
• the Test Request dialog does not contain the external payload
• the request preview cannot display the external payload

The endpoint itself is reachable and returns the expected JSON.

Current workaround

We currently solve this by adding a small JavaScript integration which:

• detects the selected example
• reads its externalValue
• downloads the referenced JSON
• updates Scalar's internal request example
• populates the Test Request editor

This works, but it requires accessing internal implementation details such as the WorkspaceStore and CodeMirror editor.

Proposal

When a request example contains externalValue, Scalar could resolve it lazily when the example becomes active.

Conceptually:

1. User selects an example.
2. Scalar resolves the externalValue.
3. Scalar replaces the selected request example with the resolved JSON.
4. Generated snippets, request preview and Test Request all use the resolved payload.

Only the selected example would be downloaded.

Previously selected examples could optionally be cached.

Benefits

This would allow API authors to:

• keep large request examples outside the OpenAPI document
• significantly reduce OpenAPI document size
• preserve Scalar's native example selector
• preserve generated code snippets
• preserve the Test Request experience
• avoid relying on internal implementation details

Additional context

One of our APIs currently exposes more than 1,200 request examples, with time up to 12000 request examples.

Using externalValue reduces the OpenAPI document considerably while remaining standards-compliant.

Supporting externalValue end-to-end would provide a standards-based solution that should also benefit integrations beyond ours.