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.