Is there a way to make the $ref even more reusable with placeholders?

[elfin-sbreuers]

My use case is the following:

I have several schema definitions. The API should return these definitions always wrapped in a certain structure. So my idea would be to have something like this:

paths:
  /path
     responses:
       '200':
          content:
            application/json:
              schema:
                $ref:
                  scaffold: '#/components/schemas/dataContainer'
                  placeholders:
                     data: '#/components/schemas/pet'
components:
  schemas:
    dataContainer:
       type: object
       properties:
         data:
           type: placeholder
           name: data

    pet:
      type: object
      properties:
         arbitrary:
            type: string

Searching for placeholder, nested $ref, DRY, and similar variations did not lead me to satisfying solution. I found the allOf keyword but this forces me to rebuild the structure that should be provided by the scaffold.

There is also something comparable for the servers key with url and variables.

Is something comparable possible to reuse schema scaffolds?

If not I would rephrase this issue as feature request.

[darrelmiller]

This has been a fairly common request over the years. Sometimes it is described as an envelope or wrapper for the internal data. The issue is more of a schema related issue. If you can find a schema language that supports this concept then you may be able to use that using with the proposed alternative schema feature.

From an API design perspective, I often find that envelopes around data are just duplicating what HTTP headers can already do.

[handrews]

https://github.com/json-schema-org/json-schema-spec/issues/322 is the JSON Schema issue closest to this. It has not really found a champion, and it does open up considerable amounts of complexity. But we haven't rejected it either. It definitely won't go into draft-08, which is now wrapping up, but could possibly get into a future draft if someone can advocate for it successfully.

I'm personally a bit skeptical as I've been down this road of essentially implementing function calls in what was supposed to be a declarative system before, and it was mostly a sign that the original solution was being re-purposed in a way that didn't really fit, but feel free to comment on the issue :-)

[kscheirer]

This issue has been listed as a possible use case for Overlays. I don't think it would help here though - you could have overlays replace a value in the contract, but the replacement value would be fixed/static in the overlay, it would not be able to dynamically merge to elements.

[handrews]

Do $dynamicAnchor and $dynamicRef (available in OAS 3.1) help here? They allow you to reference something that is determined at runtime. Sadly they're a bit confusing- json-schema-org/json-schema-spec#1140 has a proposal for simplifying them.

[github-actions[bot]]

This issue has been labeled with No recent activity because there has been no recent activity. It will be closed if no further activity occurs within 28 days. Please re-open this issue or open a new one after this delay if you need to.