Conversation
Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>
| If a URI contains a fragment identifier, then the fragment MUST be resolved per the fragment resolution mechanism of the referenced document. | ||
|
|
||
| For Overlay Object fields that identify whole documents (`$self` and `extends`), fragment identifiers MUST NOT be used. |
There was a problem hiding this comment.
Here I find the wording a bit confusing. The two statements seem to contradict each other. I think we should qualify the first one further to state things like common mark links etc... Thoughts?
There was a problem hiding this comment.
Do Overlays ever use fragment references? Perhaps in Schema Objects? Or is it always only whole-document external references or same-document internal references?
I also still think that talking about forbidding fragments for extends doesn't make much sense. $self already forbids it. A document retrieval URI won't have one, unless maybe if the Overlay were embedded in a larger JSON-like document, but that's outside of the spec and we can ignore it.
Under what circumstances would someone try to use a fragment in extends? What would they expect to happen? I'm trying to understand why we need to say anything here.
There was a problem hiding this comment.
in v1.1 and 1.0: only whole document references (we want an entire OpenAPI document). I think some people target fragment documents (e.g. a single JSON schema), but recent discussions on the topic have lead to the conclusion that they really shouldn't be doing that.
in 1.2, we're introducing same document references for the reusable actions. Since there's already been a discussion about being able to refer to reusable actions that live outside of the overlay document, this might introduce external references with fragment identifiers in the future. We explicitly decided NOT to do that for now.
There was a problem hiding this comment.
I think some people target fragment documents (e.g. a single JSON schema), but recent discussions on the topic have lead to the conclusion that they really shouldn't be doing that.
I think the place to handle this is under "Parsing Documents", with language requiring each document to be fully parsed. That makes it clear that extracting only a fragment goes against the parsing model. And yes, extracting a JSON Schema from an OAD without checking the openapi, $self and jsonSchemaDialect fields, as wall as any parent schema $id or $schema fields, leads to unpredictable behavior and possibly security vulnerabilities.
I think just keeping the first paragraph here and not the second should be fine. The prohibitions on fragments in $self and extends flow from how they work already. Even if yo uhave reusable actions elsewhere, that wouldnt' be via extends.
There was a problem hiding this comment.
I forgot to reply to this comment, but the paragraph were merged and I believe this is all the changes we needed? Let me know if I missed anything.
| | Field Name | Type | Description | | ||
| | ---- | :----: | ---- | | ||
| | <a name="overlay-version"></a>overlay | `string` | **REQUIRED**. This string MUST be the [version number](#versions) of the Overlay Specification that the Overlay document uses. The `overlay` field SHOULD be used by tooling to interpret the Overlay document. | | ||
| | <a name="overlay-self"></a>$self | `string` | A URI-reference for the Overlay document. This string MUST be in the form of a URI-reference as defined by [RFC3986 Section 4.1](https://tools.ietf.org/html/rfc3986#section-4.1). When present, this field provides the self-assigned URI of this Overlay document, which also serves as its base URI in accordance with [RFC3986 Section 5.1.1](https://tools.ietf.org/html/rfc3986#section-5.1.1) for resolving relative references within this document. The `$self` URI MUST NOT contain a fragment identifier. Overlay documents SHOULD include a `$self` field to ensure portable, unambiguous reference resolution. | |
There was a problem hiding this comment.
Overlay documents SHOULD include a
$selffield to ensure portable, unambiguous reference resolution.
I had not noticed this in the Arazzo PR. I just put the following comment there and it applies here, too, perhaps even more so if extends is the only field that would use $self right now, and it is an optional field:
While [including
$self] is my personal preference, there are times when you really do want things to be relative to wherever you are, so I hesitate to include a SHOULD here. A SHOULD is pretty strong.
There was a problem hiding this comment.
@baywet it's interested that you softened that language with a "MAY" while @frankkilcommins made it a "can" over in Overlays. I have no idea which is better and am fine with either, I just thought I'd make a note of it.
There was a problem hiding this comment.
To give you more context about my decision process: I feel like the more prescriptive we can be, the better as it removes ambiguity. MAY is normative to some level, at least more than can. It felt like providing additional guidance to me.
Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>
| | 1.1.0 | 2026-01-14 | Release of the Overlay Specification 1.1.0 | | ||
| | 1.0.0 | 2024-10-17 | First release of the Overlay Specification | | ||
|
|
||
| ## Appendix B: Examples of Base URI Determination and Identifier Resolution |
There was a problem hiding this comment.
@baywet Is there a reason you skipped the enclosing context and application-assigned cases that we have in OAS and Arazzo?
There was a problem hiding this comment.
an oversight, thanks for calling this out, updated.
Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>
Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>
2 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)