Incorrect handling of $ref in non-permitted areas

[kylef]

I discovered a user trying to describe a property called $ref in a schema, for example:

type: object
properties:
  $ref:
    type: string

This is failing as we're trying to dereference the $ref found in the property, after some digging I discovered that $ref should only be dereferenced in cases where a schema is expected thus since properties is not expected to be a schema, $ref here should not be dereferenced.

From draft-wright-json-schema-00:

Limited use of "$ref" to wherever a schema is expected

Swagger 2 specification does allow $ref to be in more places, they don't clarify completely in the spec but it would seem that the JSON Schema rule is used, and there are additional places in the spec where 'Reference Object' is permitted, for example a 'Parameter Object' a default value, etc.

I have noticed that some of our users are using $ref in their example values which does not appear to support 'Reference Object', it is not a schema and it is not explicitly mentioned in the OpenAPI 2 specification that a 'Reference Object' may be placed in a example property of a 'Schema Object', the example property contains Any with description 'A free-form property to include an example of an instance for this schema.'.

This means that the following:

definitions:
  Name:
    type: string
    example: Doe
  User:
    type: object
    properties:
      name:
        $ref: '#/definitions/Name'
    example:
      name:
        $ref: '#/definitions/Name/example'

Should be dereferenced as:

definitions:
  Name:
    type: string
    example: Doe
  User:
    type: object
    properties:
      name:
        type: string
        example: Doe
    example:
      name:
        $ref: '#/definitions/Name/example'

Currently the value in #/definitions/User/example/name would be incorrectly dereferenced and I believe some customers are depending on this behaviour. Due to this implementation, it means if you try to use $ref as a property name in either a schema example or schema properties the parser will incorrectly attempt to dereference it (or crash if it is not valid) thus preventing users from using $ref as a property name.

---

The users that are using $ref inside an example may have been trying to work around some of our prior limitations that example in a nested structure wouldn't be used for JSON body generation or data structure generation. As of https://github.com/apiaryio/fury-adapter-swagger/releases/tag/v0.22.3 this should no longer be necessary.