OpenAPI - schema examples are not used

[gotson]

Description

I have an OpenAPI spec, where the example is set on each field of the schema. I don't have any example set at the API response level. When using my OpenAPI spec, the example from the schema fields are not used, and instead dummy data is generated.

Reproduction steps

Here is a trimmed down version of my OpenAPI spec:

openapi.json

Here is what the mock returns for GET /api/v1/announcements:

{
  "description": "truly",
  "home_page_url": "savor",
  "items": [
    {
      "_komga": {
        "read": false
      },
      "author": {
        "name": "after",
        "url": "misty"
      },
      "content_html": "yahoo",
      "date_modified": "2025-11-13T10:58:20.178Z",
      "id": "where",
      "summary": "owner",
      "tags": [
        "chant",
        "dimly",
        "along",
        "after",
        "since",
        "realm"
      ],
      "title": "yahoo",
      "url": "torte"
    },
    {
      "_komga": {
        "read": false
      },
      "author": {
        "name": "fooey",
        "url": "giant"
      },
      "content_html": "circa",
      "date_modified": "2025-07-30T12:11:50.348Z",
      "id": "fooey",
      "summary": "since",
      "tags": [
        "armor",
        "which"
      ],
      "title": "yahoo",
      "url": "round"
    }
  ],
  "title": "until",
  "version": "fooey"
}

Expected behavior

The mock JSON should be using the example fields of the schema.

Initial assessment

No clue…

[slawomir-b]

I had a similar issue recently and realised that if you look into the docs here https://source.mswjs.io/docs/integrations/open-api#response-definition
you will see that only examples specified directly in the responses block are taken into consideration. While the OpenAPI spec allows you to define examples on the object schemas as well, this library doesn't implement reading them.
Would love to see this working but I think this is not a bug - just lack of functionality.

[grantralls]

I ran into the same issue and can also confirm that the response-block examples do work but not the object schema examples.

[grantralls]

So I just spent the last hour diving into JSONSchema, OpenAPI, and the seed-json-schema. This repo uses seed-json-schema which uses JSONSchema standard to read and seed OpenAPI docs which is unfortunate. Based on the code as it exists today, it doesn't support OpenAPI. I wonder if it would be a good call to remove mentions of OpenAPI from the interface and the docs since the support doesn't exist quite yet. Also the PR that was there to patch seed-json-schema to force it to support example. Which would make it incompatible with json-schema. But that's been stale for over a year now.

As for us, the best next move may be to consider tools other than msw/source.

[kettanaito]

I am more than happy to consider a different library than seed-json-schema. At the moment I wrote this toolchain, no suitable alternative existed so I made one.

One missing feature doesn't negate the rest of the OpenAPI support (paths, responses by status code, default, etc). I understand your frustration, but it seems misplaced.

The actual issue here is that response examples are freeform. To my best knowledge, they are meant to be read by humans and don't follow any specification. This forces Source into guesswork, which will never satisfy every user. The difference between OpenAPI versions makes this even harder, as some support examples why others don't.

Let's summarize.

Root cause

• This is a missing feature.
• This has nothing to do with seed-json-schema because response examples aren't JSON Schemas.
• Response examples are freeform and subject this library to guesswork.

How to solve this

I propose the following solution.

1. response.examples is taken into consideration during the response object lookup. I'd put them right before default in terms of priority.
2. If examples is specified, Source does the minimum guesswork possible, being:
   1. If it's a plain value, it's used as-is.
   2. If it's a map, the first defined example is used.

We can also support example keys as the value of the response request URL search parameter. So you could target a specific response example from the client:

fetch('/user?response=exampleName')

I see this as the only sensible way to support variable response examples.

[kettanaito]

@gotson, hi 👋 I just used your exact OpenAPI spec in the tests in #88 and it is behaving as you described. I cannot seem to reproduce the issue. The mocked response uses the first available example from response examples correctly.

We already support both example and examples:

source/src/open-api/utils/open-api-utils.ts

Lines 205 to 240 in a1f1948

	// First, if the response has a literal example, use it.
	if (mediaTypeObject.example) {
	if (typeof mediaTypeObject.example === 'object') {
	return JSON.stringify(mediaTypeObject.example)
	}
	return mediaTypeObject.example
	}
	// If the response has multiple literal examples, use the first one.
	if (mediaTypeObject.examples) {
	// Support exact response example specified in the
	// "example" request URL search parameter.
	const url = new URL(request.url)
	const exampleName = url.searchParams.get('example')
	if (exampleName) {
	const exampleByName = mediaTypeObject.examples[exampleName] as
	| OpenAPIV3.ExampleObject
	| OpenAPIV3_1.ExampleObject
	| undefined
	return exampleByName
	? exampleByName.value
	: `Cannot find example by name "${exampleName}"`
	}
	// Otherwise, use the first example.
	const firstExample = Object.values(mediaTypeObject.examples)[0] as
	| OpenAPIV3.ExampleObject
	| OpenAPIV3_1.ExampleObject
	if (typeof firstExample.value === 'object') {
	return JSON.stringify(firstExample.value)
	}
	return firstExample.value
	}

Please update your version of Source and let me know if the issue is still there. If it is, please open a new issue and provide a reproduction repo so I could look into it. Thanks.

[kettanaito]

Released: v0.6.1 🎉

This has been released in v0.6.1.

• 📄 Release notes
• 📦 View on npm

Get these changes by running the following command:

npm i @msw/source@latest

---

Predictable release automation by Release.