Can you define placeholders to replace in component schemas?

[Andre601]

I'm interested in creating an OpenAPI specification for my Rest API, but one thing that bothers me is the defining of responses for the API.

My API has 2 specific JSON replies based on HTTP response codes:

• 200

  {
    "error": false,
    "link": "https://example.com/img/animals/cat/cat_001.jpg",
    "time": 0
  }

• 403 or 404
  The info is mostly the same, with the exception of the message being different. Example with an invalid path (403) is shown here.

  {
    "details": {
      "path": "/api/invalid/path",
      "content-type": "application/json",
      "user-agent": "Some-UA/1.0"
    },
    "error": true,
    "message": "The provided path is not valid.",
    "time": 0
  }

While I can, for the most part, create two components to cover the 403 and 404 cases, would I like to have an example scheme that depicts an example link matching the provided URL path for the successful request.
If f.e. the path defined is /api/img/cat/ should the example JSON have a URL pointing to a random cat image (As shown above).

This, to my knowledge, requires me to create a separate scheme for each API endpoint I have if I want to have this.

So my question now is, can I define some kind of placeholder in the scheme, to then be replaced with whatever value I provide?

Like f.e.

components:
  schemas:
    image-response-200:
      type: object
      properties:
        error:
          type: boolean
          example: false
        link:
          type: string
          example: "https://example.com/img/{type}/{type}_001.jpg"
        time:
          type: integer
          format: int32
          example: 0

would then allow me to provide "cat" as type somewhere and the example shown would have {type} replaced with cat

I hope such a feature exists, as it would reduce the copy-paste jobs I have by a lot in the end...

[MelleD]

Any update here? Is this possible?

[PavelKhatsimtsau]

I do believe - one way to answer/tackle initial ask is to use uri template approach which is common way to discover/resolve API behavior in scope of HATEOS semantics.
So if you are able to generate strictly defined parameterized uri on the server side within specified context/scope - then consumer will be responsible for template expansion.
Or hopefully it is possible to isolate such a logic into dedicated filter/aspect on the server side - and rely on the dynamic context or some sort of the discriminator field to fill in required uri parameters.
(For example spring has dedicate UriTemplate class to handle such a use case).

Thanks.

[handrews]

@MelleD it is possible in 3.1 using JSON Schema draft 2020-12's $dynamicAnchor and $dynamicRef. It is not possible in 3.0 or earlier.

[handrews]

Closing as answered, given no further replies.