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! |
|
|
||
| ### Parsing Documents | ||
|
|
||
| Implementations MUST NOT treat an `extends` value as unresolvable before checking all possible target [[OpenAPI]] Description documents provided to the implementation. |
There was a problem hiding this comment.
Can we make this a positive statement, like
| Implementations MUST NOT treat an `extends` value as unresolvable before checking all possible target [[OpenAPI]] Description documents provided to the implementation. | |
| Implementations MUST check all possible target [[OpenAPI]] Description documents provided to the implementation before treating an `extends` value as unresolvable. |
| 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?
|
|
||
| #### 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.)
| #### 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.
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)