Skip to content

Conversation

MikeRalphson
Copy link
Member

Now this may be controversial, but I believe this small added complexity has several benefits in writing and structuring OAS definitions:

  • Allows aliasing of reused components, i.e where they are semantically different, but syntactically the same
  • Allows easy extraction of a reused component to an external reference, without having to update all the source $ref pointers
  • Gives us future expansion possibilities, such as proposed JSON schema merge keyword or RAML-style type extensions
  • It will make converting existing 2.0 definitions easier, as the 2.0 Schema Object had a $ref property
  • Due to the prevalent tooling'$ref anywhere' problem, we prevent ambiguity/abuse of the specification by explicitly allowing this construct

@RobDolinMS
Copy link
Contributor

Tagging @fehguy @darrelmiller and @webron for their two cents

@darrelmiller
Copy link
Member

Ron and discussed a similar idea that I had suggested last week when we were trying to get RC1 done. But I had added the reference object one level higher and it caused issues that I didn't like so we bailed.
This is a interesting compromise. It does require explicitly referencing every element that you are re-using from an external source, but that ensures that $refs in the spec itself could be kept just local.

In general I like this idea. It is simple to describe and fairly simple to implement.

@RobDolinMS
Copy link
Contributor

TDC: @webron, @fehguy, and @darrelmiller give this a thumbs-up

@webron webron merged commit a5bf8a0 into OAI:OpenAPI.next May 5, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants