{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"example-object","__idx":0},"children":["Example Object"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The example object is a reusable object and may be defined in components (named examples), separate files, or used directly in ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/learn/openapi/openapi-visual-reference/media-type"},"children":["Media Type Objects"]},"."]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":["\nExcerpt from the OpenAPI 3.1 specification about the example object\n"]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In all cases, the example value is expected to be compatible with the type schema of its associated value. Tooling implementations MAY choose to validate compatibility automatically, and reject the example value(s) if incompatible."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"example-object-1","__idx":1},"children":["Example Object"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"fixed-fields","__idx":2},"children":["Fixed Fields"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field Name"},"children":["Field Name"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"center","data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["summary"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Short description for the example."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["description"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Long description for the example. ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://spec.commonmark.org/"},"children":["CommonMark syntax"]}," MAY be used for rich text representation."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["value"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Any"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Embedded literal example. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["value"]}," field and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalValue"]}," field are mutually exclusive. To represent examples of media types that cannot naturally represented in JSON or YAML, use a string value to contain the example, escaping where necessary."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["externalValue"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A URI that points to the literal example. This provides the capability to reference examples that cannot easily be included in JSON or YAML documents.  The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["value"]}," field and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalValue"]}," field are mutually exclusive. See the rules for resolving Relative References."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This object MAY be extended with ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/learn/openapi/openapi-visual-reference/specification-extensions"},"children":["Specification Extensions"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In all cases, the example value is expected to be compatible with the type schema of its associated value. Tooling implementations MAY choose to validate compatibility automatically, and reject the example value(s) if incompatible."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"visuals","__idx":3},"children":["Visuals"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following include visuals of request and response examples."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"response-examples","__idx":4},"children":["Response examples"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Redocly renders examples in the sample panel."," ","Examples can be provided for the request body and the response body."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"responses:\n  '200':\n    description: Success\n    content:\n      application/json:\n        schema:\n          $ref: \"#/components/schemas/ChessResult\"\n        examples:\n          winning:\n            summary: Winning a match\n            description: This is a **fictional** win.\n            value:\n              opponent: hikaru\n              result: won\n              id: abc123\n          losing:\n            summary: Losing a match\n            description: This is a **fictional** loss.\n            value:\n              opponent: SenseiDanya\n              result: lost\n              id: def456\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Redocly renders the example in the samples pane."," ","The samples pane is usually on the right panel, but may also be in the main panel in a stacked layout."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/examples-response-ad7942b1e0013160.png","alt":"examples response"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The various examples will be displayed in the select menu."," ","The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["summary"]}," is used as the select menu text."," ","If there is no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["summary"]}," it will fallback to use the named example key (for example, \"winning\" and \"losing\" in the example above)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/examples-response-select-3c4a2d33044dcfcb.png","alt":"examples response select menu"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"request-examples","__idx":5},"children":["Request examples"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Unlike the response, the request may show the payload or code samples."," ","If the code samples are generated, the examples populate dynamically inside of the code samples."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/examples-request-9c9c83739f8ed7bf.png","alt":"examples request"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The select menu works as it does for the response samples."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"synced-examples","__idx":6},"children":["Synced examples"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the request examples and response examples have the same mapping key value (in this following example the named example keys are ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["winning"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["losing"]},")."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"requestBody:\n  content:\n    application/json:\n      schema:\n        $ref: \"#/components/schemas/ChessResult\"\n      examples:\n        winning:\n          summary: Winning a match\n          description: This is a **fictional** win.\n          value:\n            opponent: hikaru\n            result: won\n        losing:\n          summary: Losing a match\n          description: This is a **fictional** loss.\n          value:\n            opponent: SenseiDanya\n            result: lost\nresponses:\n  '200':\n    description: Success\n    content:\n      application/json:\n        schema:\n          $ref: \"#/components/schemas/ChessResult\"\n        examples:\n          winning:\n            summary: Winning a match\n            description: This is a **fictional** win.\n            value:\n              opponent: hikaru\n              result: won\n              id: abc123\n          losing:\n            summary: Losing a match\n            description: This is a **fictional** loss.\n            value:\n              opponent: SenseiDanya\n              result: lost\n              id: def456\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the mapping key exists Redocly will synchronize the request and response examples when they are changed."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Image","attributes":{"src":"https://user-images.githubusercontent.com/1161871/165141339-fb53d9fe-cd86-4249-9472-36445da61b32.gif","alt":"example-switching"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"types","__idx":7},"children":["Types"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NamedExamples"]}," (declared in the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/learn/openapi/openapi-visual-reference/components"},"children":["Components Object"]},"). It is a map of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Example"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Example"]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"js","header":{"controls":{"copy":{}}},"source":"const Example: NodeType = {\n  properties: {\n    value: { isExample: true },\n    summary: { type: 'string' },\n    description: { type: 'string' },\n    externalValue: { type: 'string' },\n  },\n};\n","lang":"js"},"children":[]}]},"frontmatter":{},"tagList":["html"],"title":"Example Object","lastModified":"2025-05-28T16:01:32.000Z"}