Clarity on referencing Components Parameters

[frankkilcommins]

fixes #129

[handrews]

I'll get to this tomorrow or at the latest Friday.

[handrews]

@frankkilcommins Sorry for the delay, I had to go back and reconsider this as I missed some things with my original feedback. For some reason, I had thought this was resolving names from the Components Object (like Security Requirement Objects resolve Security Scheme names from Components).

But now I see that this is a Reference Object, and AFAICT it's the only use of a Reference Object in the spec. So I read through that section, and I'm guessing one reason it's a Reference Object is to allow referencing parameter definitions that go with the target operation, which would require referencing external documents.

Then I thought... since this is the only use of a Reference Object, and everything else is using some form of runtime expression (sometimes with a JSON Pointer), why not get rid of this Reference Object and use a runtime expression instead? With whatever modification you need to do the value override thing.

You would still have JSON Schema references, but they are slightly different anyway.

I apologize for throwing a new idea in at the last minute here, but given the work we've done to avoid using $ref outside of JSON Schema in Moonwalk, since you're already very close to that goal here, why not go the last little bit and do everything with the runtime expression syntax? It's nicer in that it already unambiguously resolves from source documents. (if I am reading all of this correctly - if I'm not making sense please just lmk).

[frankkilcommins]

@handrews I think it's achievable to move in this direction and not have any specification specific Reference Object situations. It means I'll have to re-write some code I build for parsing but such is life 😛

This section will also need an update (it's not correct in it's current state anyway IMO with the exception of a JSON Schema reference but that's not mentioned either).

Instead of the current situation of:

  - $ref: "#/components/parameters/page"
    value: 1

We could have something like (with the appropriate verbiage that the parameter page defined is to be used and the value MUST override that of the evaluated Parameter object):

- $components.parameters.page
  value: 1

[handrews]

@frankkilcommins that looks great to me! (although you either need to make both of those array entries or give a property name to the $components part, I think?) It will also be really interesting for moonwalk to see how this all-runtime-expression-syntax approach works in practice.

[frankkilcommins]

@handrews finally got around to making this change........no more Reference Object 🚀