Local Reference to Tags Doesn't Validate

[pixelshaded]

Spec

swagger: '2.0'
info:
  version: "0.0.0"
  title: Settings UI API
  description: Api for the UI of settings.ignitionone.com
basePath: /api
tags:
  $ref: 'settingsUI/tags.yaml'

Tags

-
  name: User
  description: User Endpoints
-
  name: RateCard
  description: Rate Card Endpoints
-
  name: Role
  description: Role Endpoints

Hovering over the x, the message says:

value of type object is not allowed, value should be of type array

I've used this spec in swagger-editor so as long as the files are linked properly (seems to be since I can ctrl click the path and go to the file), this should work.

[andylowry]

Alexander, thanks for posting this issue.

Unfortunately, the question of what constitutes a valid reference in a Swagger spec has been a source of much confusion over the past year, and the various software offerings of swagger.io are not consistent in their support.

The current position is that the only references allowed in a Swagger spec are those specifically mentioned in the Swagger 2.0 specification, namely:

• References to named schemas appearing as top-level properties in the definitions object (e.g. #/definitions/Pet)
• References to named parameters appearing in the top-level parameters object (e.g. #/parameters/limit)
• References to named responses appearing in the top-level responses object (e.g. #/responses/NotFound)
• References to paths defined in another file's top-level paths object (e.g. paths.yaml#/paths/~1pets~1{id}). [Note the need to escape slashes appearing in the referenced path object key, as required by the JSONPointer specification.]

In addition to restricting the sorts of objects that can be referenced and where those objects must appear within the spec, Swagger also requires that external files to which references point must themselves be valid Swagger specs, and the referenced objects must be in their designated locations within those specs.

It is quite unfortunate that there has been much confusion around this facility, and particular that there are still parts of the Swagger software suite that do not conform to the current requirements. Swagger does not, in fact, provide any means to split your tags array out into a separate or reusable file, and any support for that in swagger-editor or other software is contrary to the Swagger project's stated intention..

[pixelshaded]

I see. I was following this: http://azimi.me/2015/07/16/split-swagger-into-smaller-files.html for reference. Swagger-parser supports this method as well: swagger-api/swagger-parser#147

[andylowry]

Yes, we went down the same path when we began designing our multi-file swagger support in API Studio. It was in a query to the swagger forum asking for some clarifications that we learned that this blog post does not in fact represent the state of Swagger. See https://groups.google.com/forum/#!searchin/swagger-swaggersocket/resolution/swagger-swaggersocket/-_2-YiuFVFU/8ONnhPT-MwAJ

Andy

[BenjamenMeyer]

FYI - openapi-spec-validator does support this per the v3 spec; but the error messages are rather confusing. I was hoping to try to use KaiZen to try to figure some things out, but it's not getting past the ref errors.

[tedepstein]

@BenjamenMeyer,

openapi-spec-validator does support this per the v3 spec;

The OpenAPI v3 spec does support the use of Reference Objects (i.e. object with a $ref property) in a wider range of contexts. But usage of $ref is still limited to those contexts where it's explicitly allowed in the specification.

The tags property of the top-level OpenAPI Object is not one of those contexts where Reference Object is allowed.

The Components Object contains reusable collections for most of the types that support Reference Object:

• schemas
• responses
• parameters
• examples
• requestBodies
• headers
• links
• callbacks

Additionally, there are some "reference-like" properties supported in Path Items, Link Objects (the operationRef property), and possibly some other places.

Are you seeing some cases where the spec allows $ref, but KaiZen Editor doesn't allow it?

[BenjamenMeyer]

@tedepstein I'm validating my spec with openapi-spec-validator and aside from learning OpenAPI syntax not having issues with where I'm putting the $ref objects; however, I loaded KaiZen Editor into Eclipse (via the Eclipse Marketplace) and was not able to get the same result out of it - it complained more on the $ref objects. Could just be how I'm running it; don't know.

BTW - I was trying out KaiZen via Eclipse to see if I could get better error messages than what JSONSchema provides in openapi-spec-validator....but I've given up for now.

[tedepstein]

@BenjamenMeyer , sorry this one slipped through the cracks. I just re-read this issue in the context of researching another one.

Generally, we believe that KaiZen OpenAPI Editor should allow $ref in all of the places where the OpenAPI 2.0 and 3.0 specifications say that it should be allowed.

And it should pass validation as long as the referenced object is of the expected type.

However, it expects to find the referenced object inside a valid OpenAPI file, and will show an error message if the referenced object is in some other kind of file, e.g. a stand-alone JSON schema file, having only a single schema at top-level. Or a JSON file having only a top-level parameter object.

It may also fail to validate if the referenced object is in a valid OpenAPI document, but not in the designated place for components of that type. (See @andylowry's comment above.)

I need to double-check the specifications and see whether this is a definitive requirement in OpenAPI 2.0. I'm pretty sure that it is not a requirement of OpenAPI 3.0. It may be a requirement of OpenAPI 2.0, in which case our error messages would be correct, though not as helpful as they might be.

I'll post back to this issue, and probably open new issues to capture the specifics.

In the meantime, if you still have an example of a project that fails validation, but you believe should pass validation, please post it here. Or maybe you can just let me know if you think the example you were testing might match one of the known issues described above.

[tedepstein]

@BenjamenMeyer, I have opened a new issue #439 that describes in detail the problem of overly restrictive references.

If you are able to say whether the problems you encountered were of the same nature, that would be helpful.

[BenjamenMeyer]

@tedepstein well, the project I was using it on has changed significantly in how it's using OpenAPI stuff...

namely, we're splitting stuff out across Python docstrings, with a few extra schema files to complete specifications, and having another tool pull it all together into an OpenAPI Specification Document...so not sure it's useful for the testing any more that way.

Per request, #439 does fairly describe some of what the project was previously doing. now I wish I'd be able to test it when I got back to work...but that's no longer feasily 😞 Thanks!