feat: adds support for self in overlay#322
Conversation
Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>
Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>
Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>
Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>
handrews
left a comment
handrews
left a comment
There was a problem hiding this comment.
This is getting quite close! BTW, I have only had time to review the markdown file, I hope someone else can look at the tests and schemas, and just ping me if there are questions you can't resolve.
Co-authored-by: Vincent Biret <vincentbiret@hotmail.com>
handrews
left a comment
handrews
left a comment
There was a problem hiding this comment.
GitHub is acting weird- it still shows my "sorry I didn't hit send two days ago" as not having been sent despite it obviously having been.
More importantly, it's showing the entire Markdown file as deleted and re-added?
I'm pretty sure tha changes are correct now based on the discussion, but the diff is unusable and I'm worried something went wrong with a recent commit?
baywet
force-pushed
the
feat/self-support
branch
from
e789604 to
6f3adf7
Compare
It looks like the commit I had made from the UI messed up the line returns somehow. I reapplied that commit correctly and force-pushed. The diff looks ok now. Thanks for calling it out! |
| Implementations MUST NOT treat an `extends` value as unresolvable before checking all possible target [[OpenAPI]] Description documents provided to the implementation. | ||
|
|
||
| To ensure portability, when a target [[OpenAPI]] Description defines `$self`, the Overlay's `extends` value SHOULD match the target's `$self` URI. | ||
| Implementations MUST examine all available target documents for matching `$self` values before concluding that no document matches the `extends` URI. |
There was a problem hiding this comment.
This sentence seems to be mostly a rephrasing of the first sentence, with the additional info to match $self values - can these be combined into one sentence or paragraph?
There was a problem hiding this comment.
You mean lines 70 and 73, correct?
There was a problem hiding this comment.
| Implementations MUST examine all available target documents for matching `$self` values before concluding that no document matches the `extends` URI. |
(to be consistent with the other rewording)
|
|
||
| #### Resolving URI Fragments | ||
|
|
||
| Where a URI appears in contexts such as CommonMark hyperlinks within `description` fields and contains a fragment identifier, the fragment MUST be resolved per the fragment resolution mechanism of the referenced document. |
There was a problem hiding this comment.
Why do we state this here? Is Overlay tooling supposed to resolve URI fragments in CommonMark hyperlinks?
I'd rather remove this sentence.
There was a problem hiding this comment.
@ralfhandl I probably agree with you now that you mention it. This is only relevant if Overlays use CommonMark in a way that a tool is expected to render. If Overlays only use them in the sense of changing OAS CommonMark fields, then this is not necessary (Overlays should consider the content a black box, and just render the raw string in visual editors, etc.)
There was a problem hiding this comment.
One thing that wasn't clear for me was for all the description fields (in overlay objects). Do we expect them to be rendered at any point? If not, this is moot, but because we have a common mark section I thought it was important to port that part as well.
There was a problem hiding this comment.
Where Overlay tooling renders rich text
looks like it does some rendering so, yes, this probably should be included. I'm not sure why overlay tooling would be doing this rendering, but clearly someone expects it to.
| #### Relative URI References in CommonMark Fields | ||
|
|
||
| Relative references in CommonMark hyperlinks (such as those in `description` fields) are resolved in their rendered context, which might differ from the context of the Overlay document. |
There was a problem hiding this comment.
Do we expect Overlay documents to be rendered?
We know that OpenAPI documents are often rendered as API documentation, so the sentence makes sense there, from where it was copied.
Co-authored-by: Ralf Handl <ralf.handl@gmail.com>
3 participants
fixes #310
heavy use of GCC to put this one together. (based on the discussion in the issue, and the arazzo PR as a template)