Examples referencing other examples

[mcrobbj]

So for example I have an example address which I want to refrence in an example customer:

components:

  examples:
  
    address:
      summary: Address example
      value:
          address1: 41 Main Street
          address2: Morningside
          address3: Edinburgh
          address4: Lothian
          postCode: EH21 8TF
          
    customerArrayExample1:
      summary: An array of 1 customer
      value:
        total: 1
        page: 1
        pageSize: 1
        customers:
          - id: "123e4567-e89b-12d3-a456-426614174000"
            firstName: "John"
            lastName: "Doe"
            email: "john.doe@example.com"
            phone: "+1234567890"
            address:
              $ref: '#/components/examples/address'

This is accepted, however in Swagger Editor it appears as

{
  "total": 1,
  "page": 1,
  "pageSize": 1,
  "customers": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "phone": "+1234567890",
      "address": {
        "$ref": "#/components/examples/address"
      }
    }
  ]
}

Is this supported and if so what am I doing wrong?

{
  "total": 1,
  "page": 1,
  "pageSize": 1,
  "customers": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "phone": "+1234567890",
      "address": {
        "address1": "41 Main Street",
        "address2": "Morningside",
        "address3": "Edinburgh",
        "address4": "Lothian",
        "postCode": "EH21 8TF"
      }
    }
  ]
}

Is the desired result

[handrews]

@mcrobbj I hope you don't mind I formatted your examples with syntax highlighting :-)

Unfortunately this is not supported, because the example value is a literal value. In some cases, you will want a literal property $ref as part of your example, and will not want it treated as a reference. There's really no good way around this, as any escape sequence you might think up will have some literal use case, no matter how unlikely.

The way to work around this is to use the Example Object's externalValue field to point to a document that you generate separately. Then you can have a build process to assemble complex examples from re-usable components.

[handrews]

@mcrobbj I have moved this from Q&A to Enhancements in lieu of keeping #3910 open as a separate issue.

[handrews]

@mcrobbj I wonder if overlays could help here? As noted, the problem is that we can't support $ref inside examples because then you couldn't have examples that used properties named "$ref". But overlays modify things from outside of the main specification document, so you could use that to build up more complex examples. I think.

[mcrobbj]

Perhaps, I would have to see some concrete examples, seems like a simple ask for the main spec?

…

On Fri, 6 Jun 2025 at 18:03, Henry Andrews ***@***.***> wrote: @mcrobbj <https://github.com/mcrobbj> I wonder if overlays <https://github.com/OAI/Overlay-Specification> could help here? As noted, the problem is that we can't support $ref inside examples because then you couldn't have examples that used properties named "$ref". But overlays modify things from outside of the main specification document, so you could use that to build up more complex examples. I think. — Reply to this email directly, view it on GitHub <#3902 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACQL2EE5ZGYKLEL7PBMFO2T3CHCXZAVCNFSM6AAAAAB6YRJZWOVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTGMZZGI2TKNY> . You are receiving this because you were mentioned.Message ID: ***@***.*** com>

[handrews]

@mcrobbj the problem is that there is no way to distinguish between a literal $ref in an example and a $ref that is intended to behave as a reference value. We have discussed this before several times, and the Example Object was the result.