Extra JSON Reference properties ignored - reduces reusability of references

Hi everyone.

I feel that the ignoring of extra properties when using JSON References goes against the goal of reusability.

Take this example from a fictional Swagger contract:

{
    addresses: [
        "homeAddress": {
            "description": "The premises at which electricity is provided.",
            "$ref": "#/definitions/Address"
        },
        "invoiceAddress": {
            "description": "The billing address - must be where the customer's credit card is registered.",
            "$ref": "#/definitions/Address"
        }
    ]
}

The "description" properties help to distinguish between the two uses of the "Address" Reference. Of course you could argue that better naming of the "homeAddress" and "invoiceAddress" properties could achieve this, but we are not always in control of property names in our data models and sometimes you need a more verbose description.

The Swagger editor (http://editor.swagger.io/#/) is an example of an application that could be improved by removing this limitation.

Is this something that has been raised previously? Please see here for a discussion on the Swagger Google Group: https://groups.google.com/forum/#!topic/swagger-swaggersocket/ewgimdO2cOI

Currently, we use JSON References as-is. While there's a huge advantage to that tooling-wise, it does hinder reusability in some cases, and the issue has been raised (unofficially) a few times. Overriding the description is one case, but there are also cases of wanting to override whether fields are required and so on. Not sure if we should change it, given the cost, but we should consider it.

I think this is a very good Proposal.
In my example I want to set:

      parameters:
        - $ref: '#/parameters/fields'
          default: 'local_default'

I would be willing to update json-refs to have a flag that allowed you to handle this situation. Based on OpenAPI feature requests, I can see a few different things we'd need:

Merging keys, like the example above
Overriding/Replacing keys, possibly like the example below

The JSON Reference spec clearly says these should be ignored. But...there's nothing stopping json-refs from allowing extra functionality on top in an opt-in manner.

Realize, this has nothing specific to do with OpenAPI other than a number of the Node.js tools around OpenAPI use json-refs. A decision on either side does not have to reflect or impact the ability/decision of the other. I hope that is clear.

@webron

I would love this feature, but I strongly advise we don't do it. If we did, tooling support would be inconsistent because the spec says it's a no-no.

There is a construct in JSON schema draft 5 but I don't think we're considering updating to that (@webron?)

Good point. I was just pointing out that if the decision was to do this, I have no objection for my tooling. As for JSON Schema Draft 5, unless it alters the JSON References specification I don't see us being able to support this if we do things the JSON References way. I wonder if we should reach out to the JSON References authors?

I'd also love to be able to override items from a $ref. I'd actually been using them before but now that the swagger editor is flagging them as warnings I'd been reconsidering it.

The warnings are accurate so don't attempt to merge/override properties in a referenced object as it won't work. I would love to see this addressed as well.

Parent meta issue: #579

I haven't checked draft 5, so I don't know if it has effects on JSON References as well (possibly with a new draft to that). I don't think we'll be moving to draft 5 as it's not official (yeah, an official draft).

Breaking away from specs is a challenge. Unlike some expansions to JSON Schema which are actually allowed by JSON Schema itself, we're suggesting here something that goes against the spec of JSON References.

That said, within the spec, the inability to add/override JSON References makes them unusable in some cases and forces people to not DRY or make incomplete documentation.

The real challenge here is not to say we allow it, but try to think of the edge cases that could help users abuse this feature in a way, and causing more problems for the tooling. I'd like to see this change happening, but we need to be careful here.

There is a merge construct which addresses this issue. But I think moving to draft 5 would be a big mistake right now.

@fehguy

I have a team trying to use the swagger editor hosted on swaggers site to edit our API's but with the recent enhancement to the editor to use this update, our descriptions were showing as warnings. We have a very similar issue as @JimSangwine which I can post our actual example but for now we've just cloned an older tag of the swagger editor and are running it locally.

So the reason that I posted is to support this change but to ask for clarification, is @fehguy suggesting that we do not support this because the draft version of the JSON Schema does not support it and the swagger editor was upgraded to use the new draft version?

If i'm following correctly, it's a draft and a reason why this argument should be made to change the specification.

Actually it supported both in Swagger and Draft-4, you just need to use allOf keyword.
So instead of:

description: 'The premises at which electricity is provided.'
$ref": '#/definitions/Address'

You should write:

description: 'The premises at which electricity is provided.'
allOf:
  - $ref: '#/definitions/Address'

It standard usage of allOf nothing fancy here, and I think it fully solve this problem.

I'd expect that this (OpenAPI 3)

"startLocation": {
    "description": "The location of the trip start.",
    "nullable": true,
    "oneOf": [
        {
            "$ref": "#/components/schemas/Location"
        }
    ]
},

or this (Swagger 2)

"startLocation": {
    "description": "The location of the trip start.",
    "allOf": [
        {
            "$ref": "#/components/schemas/Location"
        }
    ]
},

should be allowed, but eg. swagger-codegen does not allow this. Why is one of these samples not the current way to go? Or something similar to avoid $ref with additional properties?

In Schema Objects, $ref siblings will be supported in OAS 3.1 which will use the JSON Schema 2019-09. As mentioned in JSON Schema 2019-09 release notes, it now allows keywords alongside $ref.

However, this change does not affect $refs outside of Schema Objects, such as $refs in parameters or responses.

Related: #2099

Add and update descriptions in DSS API

@hkosova

As @hkosova mentions, siblings are now welcome in schema objects, and will likely be allowed in various other places around the OpenAPI spec.

openapi: Fixed problematic schemas breaking SwaggerUI with bundled ve…

openapi: Use allOf for contextual description of referenced schemas

I think that a good solution here would be to split the definition of description. you could split into field description and class description.

This is slightly related to new config property and annotation as detailed in wiki

Use allOf workaround for additional ref properties

Navigation Menu

Repository navigation

Extra JSON Reference properties ignored - reduces reusability of references #556

71 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Extra JSON Reference properties ignored - reduces reusability of references #556

Description

Activity

webron commented on Feb 8, 2016

qcho commented on Feb 24, 2016

whitlockjc commented on Feb 24, 2016

whitlockjc commented on Feb 24, 2016

fehguy commented on Feb 24, 2016

whitlockjc commented on Feb 24, 2016

drewish commented on Feb 24, 2016

whitlockjc commented on Feb 24, 2016

webron commented on Feb 24, 2016

webron commented on Feb 24, 2016

fehguy commented on Feb 24, 2016

jmatcuk commented on Mar 3, 2016

IvanGoncharov commented on Mar 3, 2016

71 remaining items

RicoSuter commented on Sep 12, 2019

hkosova commented on Feb 24, 2020

philsturgeon commented on Jul 9, 2020

thejeff77 commented on May 18, 2023

frantuma commented on Oct 8, 2024

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions