feat: adds support for self in overlay by baywet · Pull Request #322 · OAI/Overlay-Specification

baywet · 2026-04-13T14:07:18Z

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)

Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>

baywet · 2026-04-13T14:09:16Z

versions/1.2.0-dev.md

+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.


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?

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.

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.

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.

baywet · 2026-04-13T14:10:16Z

versions/1.2.0-dev.md

 overlay: 1.2.0
+$self: 'https://example.com/overlays/tictactoe.overlay.yaml'
 info:
  title: Overlay for the Tic Tac Toe API document
  version: 1.0.0
-extends: 'https://raw.githubusercontent.com/OAI/learn.openapis.org/refs/heads/main/examples/v3.1/tictactoe.yaml'
+extends: 'https://api.example.com/openapi/tictactoe.yaml'


Here because of the changes, we effectively lost the "regular resolution" example (use of extend without self). I suggest we re-introduce it. Even though we have some in the appendix section, it's a long way down. Thoughts?

Well... when extends is a full URI (starting with a scheme) the base URI is irrelevant, so this extends example behaves the same regardless of $self. So I'm not sure what was lost?

My concern is that we don't have an example without $self anymore and that might confuse people?

I've re-added an example without self to address this concern in afd5fc3

handrews · 2026-04-13T19:29:23Z

versions/1.2.0-dev.md


+### Parsing Documents
+
+Each possible target [[OpenAPI]] Description document MUST be fully parsed in order to locate possible `extends` resolution targets before attempting to resolve an Overlay's `extends` value.


The requirement here is slightly different: You can't declare a referencing (including extends) un-resolvable without parsing all known potential target documents [NOTE: I later saw that you have this requirement correct further down, I'm leaving up this explanation to explain why this part shouldn't be here, apologies if it is overkill].

To explain this, let's assume we (for... reasons) have some OADs and overlays that have been placed on an air-gapped network. The laws of physics prevent fetching them from any network location- no wires, no wireless, no nothing.

The Overlay tool would need to be told what documents to consider. It might be given the intended retrieval URIs of the documents as well, meaning "pretend that you retrieved these documents from these URIs". This is common in JSON Schema reference resolvers, because you are not guaranteed to have an $id, and you are not guaranteed to have full network or filesystem access.

If one of those retrieval URIs matches your $extends, you can resolve it to that retrieval URI. Hopefully the $self matches, but it technically does not have to. A mismatch would be... not a user error, but a user being weird and counter-intuitive.

On the other hand, if you weren't provided a retrieval URI for each document (or if none of them match your extends) and the extends field is a network URI (on your air-gapped machine with no network access, because physics), then your implementation needs to have been told what documents to check, and needs to search them for a matching $self.

So the condition here is "don't give up until you've parsed everything". We definitely do not want to make parsing every possible target a precondition to resolution. That might be a lot of wasted effort!

I believe the rewrite of the section makes that a bit clearer. But I'm happy to iterate here now that we have less text. afd5fc3

handrews · 2026-04-13T19:31:31Z

versions/1.2.0-dev.md

+### Parsing Documents
+
+Each possible target [[OpenAPI]] Description document MUST be fully parsed in order to locate possible `extends` resolution targets before attempting to resolve an Overlay's `extends` value.
+Reference targets include the root object's `$self` field when present.


There's something a bit odd about this phrasing to me. $self provides a self-assigned URI. URIs are what are used for references. Saying "reference targets include the root object's $self" makes this feel like a special case. It's not. It's just a consequence of two steps:

References use URIs

$self assignes a URI

The reference (extends) shouldn't care at all where the URI came from. In fact, it should be possible to write a URI determination module and a reference resolution module independently. The URIs are the interface, how they got there is an implementation detail that only applies to one side. Does that make sense?

hopefully the rewording in afd5fc3 makes it much easier to understand without omitting important information. Let me know what you think.

handrews · 2026-04-13T19:33:55Z

versions/1.2.0-dev.md

+**Fragmentary parsing** occurs when an implementation parses only the specific part of a target description that seems needed, rather than parsing complete candidate target descriptions first.
+This practice is **strongly discouraged** and produces undefined behavior.


Has this behavior previously been recommended in Overlays? If not, I would cut this whole section. The only reason anything like this is in the OAS is that OAS 2.0 specified fragmentary parsing. And OAS 3.0 was completely unclear. So we needed to explain the change. But if Overlays only point to entire documents, there's no need for this and it's just confusing.

Removed in afd5fc3

handrews · 2026-04-13T19:37:56Z

versions/1.2.0-dev.md

+#### Identifier-Based Referencing
+
+To ensure interoperability, when an Overlay identifies a target [[OpenAPI]] Description by URI using `extends`, that URI MUST be the target description's `$self` URI if the target defines `$self`.
+
+This means implementations MUST examine possible target OpenAPI Description documents to check for matching `$self` values before deciding no document matches the `extends` URI.
+
+Implementations MAY support additional, non-interoperable lookup methods (such as retrieval URI matching), but relying on those methods is NOT RECOMMENDED.


I don't think this needs to be separate from the first section, which overlaps considerably.

I've probably said contradictory things about using retrieval URIs. I don't want to be too discouraging here, because they do work, and sometimes they are the only option. If a tool handles them, it should be interoperable. But we don't say exactly how a tool learns the retrieval URI (provided by user, determined by actually fetching it as a URL, etc.). And the caveats also apply to URIs that might come from other contexts, e.g. Content-Location in multipart/related, although I'm not aware of anyone actually doing that (which is a shame, it's a nice solution to bundling documents of different formats).

merged the sections together in afd5fc3

handrews · 2026-04-13T19:41:06Z

versions/1.2.0-dev.md

 ### Relative References in URIs

-Unless specified otherwise, all fields that are URI references MAY be relative references as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2).
+URIs used in an Overlay document, including `$self` and `extends`, are resolved as _identifiers_.


I'm not sure most people know what "resolved as identifiers" means. I tend to say something like "are identifiers (URIs), and not necessarily locators (URLs)." This gets paired with discussion of how documents can be made available to the implementation so that the identifiers are seen.

updated with your suggestion in afd5fc3

handrews · 2026-04-13T20:56:36Z

versions/1.2.0-dev.md

 | 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. |


Overlay documents SHOULD include a $self field 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.

updated to MAY in afd5fc3

handrews · 2026-04-13T20:57:13Z

versions/1.2.0-dev.md

+The `extends` property is an identifier.
+When candidate OpenAPI description documents define `$self`, the `extends` value MUST be matched to `$self` as described in [Identifier-Based Referencing](#identifier-based-referencing).


This feels a bit redundant, and as noted before I'm not entirely sure it ought to be called out anyway as it's just a consequence of how URIs work.

removed in afd5fc3

handrews · 2026-04-13T20:58:16Z

versions/1.2.0-dev.md

 overlay: 1.2.0
+$self: 'https://example.com/overlays/tictactoe.overlay.yaml'
 info:
  title: Overlay for the Tic Tac Toe API document
  version: 1.0.0
-extends: 'https://raw.githubusercontent.com/OAI/learn.openapis.org/refs/heads/main/examples/v3.1/tictactoe.yaml'
+extends: 'https://api.example.com/openapi/tictactoe.yaml'


Well... when extends is a full URI (starting with a scheme) the base URI is irrelevant, so this extends example behaves the same regardless of $self. So I'm not sure what was lost?

handrews · 2026-04-13T20:59:08Z

versions/1.2.0-dev.md

-## Appendix A: Revision History
+## Appendix A: Examples of Base URI Determination and Identifier Resolution


I believe Revision History is always Appendex A in the OAS. The others appendices come afterwards.

ah... I thought I was improving readability of the document moving it down. Sorry. Reverted in afd5fc3

handrews · 2026-04-13T21:00:24Z

versions/1.2.0-dev.md

+
+Retrieved from `file:///Users/dev/projects/overlays/purchase.overlay.yaml`, the relative `extends` URI resolves to `file:///Users/dev/projects/openapi/petstore.yaml`.
+
+### Identity vs Location: Why `extends` Should Match `$self`


I'd say this is more "why potential target documents should be checked for $self", although I don't feel strongly about this.

updated to your suggestion in afd5fc3

Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>

feat: adds support for self in overlay

4efbc49

Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>

baywet self-assigned this Apr 13, 2026

baywet commented Apr 13, 2026

View reviewed changes

baywet mentioned this pull request Apr 13, 2026

The extends field should support referencing OADs by their $self #310

Open

handrews suggested changes Apr 13, 2026

View reviewed changes

chore: applies review feedback

afd5fc3

Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>

baywet requested a review from handrews April 14, 2026 13:55

		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.


		### Parsing Documents

		Each possible target [[OpenAPI]] Description document MUST be fully parsed in order to locate possible `extends` resolution targets before attempting to resolve an Overlay's `extends` value.

		Fragmentary parsing occurs when an implementation parses only the specific part of a target description that seems needed, rather than parsing complete candidate target descriptions first.
		This practice is strongly discouraged and produces undefined behavior.

		The `extends` property is an identifier.
		When candidate OpenAPI description documents define `$self`, the `extends` value MUST be matched to `$self` as described in [Identifier-Based Referencing](#identifier-based-referencing).

		## Appendix A: Revision History
		## Appendix A: Examples of Base URI Determination and Identifier Resolution


		Retrieved from `file:///Users/dev/projects/overlays/purchase.overlay.yaml`, the relative `extends` URI resolves to `file:///Users/dev/projects/openapi/petstore.yaml`.

		### Identity vs Location: Why `extends` Should Match `$self`

Conversation

baywet commented Apr 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

baywet commented Apr 13, 2026 •

edited

Loading