Properties with "$ref" and "description" cause warnings in editor

[hlubovac]

I'm having a hard time finding information about this in specs, so I can't guess whether the problem that I'm about to describe is by design or a if it's a bug.

When, within definitions, an entry exists with a property referencing another definition via $ref and also having a description value, then swagger-editor shows a warning.

If it's only one, it wouldn't bother me as much, but my swagger-json is large, and I have dozens (and growing) of these. I'm trying to stay adamant with keeping the description field where it is (as opposed to moving it to the actual referenced definition, which is what fixes the problem), because otherwise swagger-ui doesn't display it at all.

For example, the editor does not like description values in this YAML definition snippet):

  'response:container:collection:agent':
    type: object
    properties:
      jsonapi:
        $ref: '#/definitions/response:container:jsonapi'
        description: Service information
      meta:
        $ref: '#/definitions/response:container:meta'
        description: Request processing information
      links:
        $ref: '#/definitions/response:container:links'
        description: URLs related to the primary resource(s)
      data:
        type: array
        items:
          $ref: '#/definitions/response:data:agent'
      included:
        type: array
        items:
          $ref: '#/definitions/response:container:related'
        description: 'Related resources of types: "lab"'
    required:
      - data
      - jsonapi
      - links
      - meta

... while swagger-ui displays those description values regardless (which I like):

When I move those description fields to definition of objects that $ref values point to, then swagger-editor shows the content as valid (so, no warning), but swagger-ui does not display those description values at all (not at the property level, not at the type level).

I did find some traces showing that my description values are where they are supposed to be - see this:

Source: http://json-schema.org/example1.html

It seems logical to me that both locations should allow description field: it may be desired that the definition ($ref) is described in some generic way, while its usage (properties) is described in addition to that. E.g. I could say that my $ref "agent" is "a record that represents an employee", while my data property can be described as "collection of agents". In other words, I think that both editor and swagger-ui should add the missing functionality in their code base, cause there's an obvious mismatch. I guess, if description can't be in both places, then if the two projects are at least in agreement about where it goes, it would help.

Thanks.

[webron]

Unfortunately, you just can't add anything to $refs. The JSON Reference spec is very clear, saying that anything added to it will be ignored.

We're working on a major update which will affect both the UI and the editor. In the UI - you will no longer see the descriptions. In the editor, warnings will appear only in the gutter, but will not appear under Errors section in the editor.

[hlubovac]

Please confirm this (rephrased): are you saying that my YAML above is, by design, illegal, and that those description fields should be moved to definitions that their $refs point to, and that swagger-ui should be adjusted to look for those values there instead of where I defined it?

What about those 2 example JSON snippets that I copied over from http://json-schema.org/example1.html (bottom of that page)? They are clearly showing examples of description values acceptable at both locations.

[fehguy]

In JSON Schema, $ref does not allow siblings. Thus description in all of the above will be ignored (the editor should be warning you about this). So yes, you should not expect it to work, and yes, their example too is incorrect.

[webron]

@hlubovac - When it comes to technical subtleties, it's not illegal. You can write whatever you want alongside a $ref - they will just be ignored (so not the behavior you'd expect). The example in JSON Schema's website is just misleading. It's not an error, but processors will ignore it. The text can still be read by any person actually reading the schema itself.

[hlubovac]

I see. Thank you.

I noticed that @fehguy is involved in swagger-ui project. You two indirectly stated that swagger-ui is the one that incorrectly processes that description as the sibling of $ref. Perhaps he'll want to adjust that there then. Again, swagger-ui ignores description within $ref, but it processes it as sibling instead.

[webron]

@hlubovac - I've mentioned in the first comment that this is going to change in swagger-ui.

[fehguy]

that darn @fehguy

[hlubovac]

@webron - sorry, I misinterpreted that somehow. Thank you very much.

[rrberry]

I'm new to Swagger and have run into this issue as well. After the update, will the UI display descriptions from referenced definitions? Or will it simply become impossible to display a description for any property that is defined by $ref?

[webron]

If you define it in the object you reference, it will be displayed. If at the same level of the $ref, it will be ignored.

[Cooker-Monster]

Just to mention that new editor defines "Sibling values are not allowed alongside a $ref." as a Semantic Error as the previous one defined it as a Warning. Is there a reason for that ? I can't figure out why put a comment for a $ref induces a semantic error ?

[webron]

@Cooker-Monster it's a bug. it should be a warning.

[Cooker-Monster]

Ok, fine.
"Error": it's a bit stressing :-)

[webron]

@Cooker-Monster would you mind filing a ticket on that?

[naldino74]

Hi,

I came across the same issue more than once and, IMHO, this is a quite relevant limitation in current implementation (I'm not an expert... so I dont know whether it depends on some constraints in the OpenAPI specs or in the Swagger-ui/editor...).

In my experience the scenario @hlubovac depicted in his original post is quite common...

I'd like/need often to obtain something similar to what in picture below:

As you can see, in this case I need to provide a "general description" for the array of strings listing the set of possible values a property can take, and a "context-spceific" description for the attribute of the specific class of object (a "device", in the example) referring to the array.

The purposes of the two descriptions are very different:

• the "general" one clarifies that the array contains all the possible values the "status" field can assume (something very important to be known when you need to set the value in a PUT/POST/PATCH)
• the "context-specific" one clarifies that the property contains the current value of the attribute for the specific object, returned by (probably) a GET.

If I've well understood, this is something we cannot achieve now and is not in any future plan.

Bye.

[webron]

@naldino74 - again, this is a limitation of the spec, not the tool. We can't make this work in the editor without making changes in the spec. There are related tickets on it on the spec's repo. If you'd like to see it changed, you should voice your opinion there.

[vincnetas]

Issue in OpenAPI spec repo OAI/OpenAPI-Specification#1514

[otto-gebb]

@webron The spec guys don't want to collaborate. Can we ignore the spec in this particular case and allow descriptions alongside $refs?

[webron]

@otto-gebb I'm actually one of those 'spec guys', but regardless, no - we can't ignore the spec in this particular case.

[rafenden]

YAML anchors can be used to achieve this (Swagger 2).

Example:

definitions:
  country: &country
    type: string
    enum: [UK, DE, PL, UNKNOWN]
    default: UNKNOWN

parameters:
  country:
    name: country
    in: query
    description: Country
    <<: *country

More info in the Swagger documentation for enums

[hkosova]

@rafenden In OpenAPI 3.0 your example can be written without YAML anchors:

components:
  schemas:
    country:
      type: string
      enum: [UK, DE, PL, UNKNOWN]
      default: UNKNOWN

  parameters:
    country:
      name: country
      in: query
      description: Country
      schema:
        $ref: '#/components/schemas/country'

There's also the allOf workaround that can be used to "add" (sort of) extra properties to a $ref. This works in Swagger Editor and Swagger UI:

some_property:
  description: My custom description
  allOf:
    - $ref: '#/components/schemas/Something'

[mindstretch23]

Is @hkosova's allOf workaround above safe to use? Or will it just depend on the particular tool used to process the spec?

...Badly needing to solve the use case of having $ref "siblings"...

[shockey]

@mindstretch23 AFAIK, this should work in any tool that is properly(!) implementing the OpenAPI Specification.

[dejf-js]

For me the error occurred when using incorrectly the required attribute.
Under https://swagger.io/docs/specification/data-models/data-types/#object
we find : !!

Note that required is an object-level attribute, not a property attribute:

type: object
properties:
  id:
   type: integer
    required: true  **# Wrong!**

required:           **# Correct**
  - id

[Porl91]

Hi @hkosova, sorry for digging up an old thread, but for the first suggestion you made in this comment, is it possible to define schema properties inside properties or would this only work inside parameters?:
#1184 (comment)