Skip to content

Commit

Permalink
Updated intro
Browse files Browse the repository at this point in the history
  • Loading branch information
@ralfhandl
ralfhandl committed Sep 10, 2024
1 parent 54faaec commit 503e83e
Show file tree
Hide file tree
Showing 2 changed files with 32 additions and 32 deletions.
32 changes: 16 additions & 16 deletions overlay/latest.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@
</script>

<meta name="color-scheme" content="light">
<meta name="description" content="The Overlay specification is an extension or companion to the OpenAPI specification.
<meta name="description" content="The Overlay Specification is an extension or companion to the [OpenAPI] specification.
An Overlay describes a set of changes to be applied or “overlaid” onto an existing OpenAPI description.">
<link rel="canonical" href="https://spec.openapis.org/overlay/v1.0.0.html">
<style>
Expand Down Expand Up @@ -156,14 +156,14 @@
]
}
],
"publishISODate": "2024-09-09T00:00:00.000Z",
"generatedSubtitle": "09 September 2024"
"publishISODate": "2024-09-10T00:00:00.000Z",
"generatedSubtitle": "10 September 2024"
}</script>
<link rel="stylesheet" href="https://www.w3.org/StyleSheets/TR/2021/base.css"></head><body class="h-entry"><div class="head">
<p class="logos"><a class="logo" href="https://openapis.org/"><img crossorigin="" alt="OpenAPI Initiative" height="48" src="https://raw.githubusercontent.com/OAI/OpenAPI-Style-Guide/master/graphics/bitmap/OpenAPI_Logo_Pantone.png">
</a></p>
<h1 id="title" class="title">Overlay Specification v1.0.0 </h1> <h2 id="subtitle" class="subtitle">Version 1.0.0</h2>
<p id="w3c-state"> <time class="dt-published" datetime="2024-09-09">09 September 2024</time></p>
<p id="w3c-state"> <time class="dt-published" datetime="2024-09-10">10 September 2024</time></p>
<details open="">
<summary>More details about this document</summary>
<dl>
Expand Down Expand Up @@ -217,25 +217,25 @@ <h1 id="title" class="title">Overlay Specification v1.0.0 </h1> <h2 id="subtitle
</div><style>
#respec-ui { visibility: hidden; }#title { color: #578000; } #subtitle { color: #578000; }.dt-published { color: #578000; } .dt-published::before { content: "Published "; }h1,h2,h3,h4,h5,h6 { color: #578000; font-weight: normal; font-style: normal; }a[href] { color: #45512c; }body:not(.toc-inline) #toc h2 { color: #45512c; }table { display: block; width: 100%; overflow: auto; }table th { font-weight: 600; }table th, table td { padding: 6px 13px; border: 1px solid #dfe2e5; }table tr { background-color: #fff; border-top: 1px solid #c6cbd1; }table tr:nth-child(2n) { background-color: #f6f8fa; }pre { background-color: #f6f8fa !important; }code { color: #c83500 } th code { color: inherit }a.bibref { text-decoration: underline;}/** * GitHub Gist Theme * Author : Louis Barranqueiro - https://github.com/LouisBarranqueiro */ .hljs { display: block; background: white; padding: 0.5em; color: #333333; overflow-x: auto; } .hljs-comment, .hljs-meta { color: #727070; } .hljs-string, .hljs-variable, .hljs-template-variable, .hljs-strong, .hljs-emphasis, .hljs-quote { color: #c74700; } .hljs-number { color: #005e5e; } .hljs-keyword, .hljs-selector-tag, .hljs-type { color: #a71d5d; } .hljs-literal, .hljs-symbol, .hljs-bullet, .hljs-attribute { color: #007aa2; } .hljs-section, .hljs-name { color: #4b7c46; } .hljs-tag { color: #333333; } .hljs-title, .hljs-attr, .hljs-selector-id, .hljs-selector-class, .hljs-selector-attr, .hljs-selector-pseudo { color: #795da3; } .hljs-addition { color: #55a532; background-color: #eaffea; } .hljs-deletion { color: #bd2c00; background-color: #ffecec; } .hljs-link { text-decoration: underline; }
</style><section class="notoc introductory" id="abstract"><h2>What is the Overlay Specification?</h2>
<p>The Overlay specification is an extension or companion to the OpenAPI specification.
<p>The Overlay Specification is an extension or companion to the [<cite><a class="bibref" data-link-type="biblio" href="#bib-openapi" title="OpenAPI Specification">OpenAPI</a></cite>] specification.
An Overlay describes a set of changes to be applied or “overlaid” onto an existing OpenAPI description.</p>
<p>The main purpose of Overlays is to provide a way to repeatably apply transformations to one or many OpenAPI descriptions.
<p>The main purpose of the Overlay Specification is to provide a way to repeatably apply transformations to one or many OpenAPI descriptions.
Use cases include updating descriptions, adding metadata to be consumed by another tool, or removing certain elements from an API description before sharing it with partners.
Overlays may be specific to a single OpenAPI description, or be designed to apply the same transform to any OpenAPI description.</p>
</section><section class="override introductory notoc" id="sotd" data-max-toc="0"><h2>Status of This Document</h2>The source-of-truth for this specification is the HTML file referenced above as <em>This version</em>.</section><nav id="toc"><h2 class="introductory" id="table-of-contents">Table of Contents</h2><ol class="toc"><li class="tocline"><a class="tocxref" href="#overlay-specification"><bdi class="secno">1. </bdi>Overlay Specification</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#conformance"><bdi class="secno">1.1 </bdi>Version 1.0.0</a></li></ol></li><li class="tocline"><a class="tocxref" href="#introduction"><bdi class="secno">2. </bdi>Introduction</a></li><li class="tocline"><a class="tocxref" href="#definitions"><bdi class="secno">3. </bdi><span>Definitions</span></a><ol class="toc"><li class="tocline"><a class="tocxref" href="#overlay-document"><bdi class="secno">3.1 </bdi><span>Overlay Document</span></a></li></ol></li><li class="tocline"><a class="tocxref" href="#specification"><bdi class="secno">4. </bdi>Specification</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#versions"><bdi class="secno">4.1 </bdi>Versions</a></li><li class="tocline"><a class="tocxref" href="#format"><bdi class="secno">4.2 </bdi>Format</a></li><li class="tocline"><a class="tocxref" href="#document-structure"><bdi class="secno">4.3 </bdi>Document Structure</a></li><li class="tocline"><a class="tocxref" href="#relative-references-in-urls"><bdi class="secno">4.4 </bdi>Relative References in URLs</a></li><li class="tocline"><a class="tocxref" href="#schema"><bdi class="secno">4.5 </bdi>Schema</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#overlay-object"><bdi class="secno">4.5.1 </bdi>Overlay Object</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#fixed-fields"><bdi class="secno">4.5.1.1 </bdi>Fixed Fields</a></li></ol></li><li class="tocline"><a class="tocxref" href="#info-object"><bdi class="secno">4.5.2 </bdi>Info Object</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#fixed-fields-0"><bdi class="secno">4.5.2.1 </bdi>Fixed Fields</a></li></ol></li><li class="tocline"><a class="tocxref" href="#action-object"><bdi class="secno">4.5.3 </bdi>Action Object</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#fixed-fields-1"><bdi class="secno">4.5.3.1 </bdi>Fixed Fields</a></li></ol></li></ol></li><li class="tocline"><a class="tocxref" href="#examples"><bdi class="secno">4.6 </bdi>Examples</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#structured-overlays-example"><bdi class="secno">4.6.1 </bdi>Structured Overlays Example</a></li><li class="tocline"><a class="tocxref" href="#targeted-overlays"><bdi class="secno">4.6.2 </bdi>Targeted Overlays</a></li><li class="tocline"><a class="tocxref" href="#wildcard-overlays-examples"><bdi class="secno">4.6.3 </bdi>Wildcard Overlays Examples</a></li><li class="tocline"><a class="tocxref" href="#array-modification-examples"><bdi class="secno">4.6.4 </bdi>Array Modification Examples</a></li><li class="tocline"><a class="tocxref" href="#traits-examples"><bdi class="secno">4.6.5 </bdi>Traits Examples</a></li></ol></li><li class="tocline"><a class="tocxref" href="#specification-extensions"><bdi class="secno">4.7 </bdi>Specification Extensions</a></li></ol></li><li class="tocline"><a class="tocxref" href="#appendix-a-revision-history"><bdi class="secno">A. </bdi>Appendix A: Revision History</a></li><li class="tocline"><a class="tocxref" href="#references"><bdi class="secno">B. </bdi>References</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#normative-references"><bdi class="secno">B.1 </bdi>Normative references</a></li></ol></li></ol></nav>
An Overlay may be specific to a single OpenAPI description, or be designed to apply the same transform to any OpenAPI description.</p>
</section><section class="override introductory notoc" id="sotd" data-max-toc="0"><h2>Status of This Document</h2>The source-of-truth for this specification is the HTML file referenced above as <em>This version</em>.</section><nav id="toc"><h2 class="introductory" id="table-of-contents">Table of Contents</h2><ol class="toc"><li class="tocline"><a class="tocxref" href="#overlay-specification"><bdi class="secno">1. </bdi>Overlay Specification</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#conformance"><bdi class="secno">1.1 </bdi>Version 1.0.0</a></li></ol></li><li class="tocline"><a class="tocxref" href="#introduction"><bdi class="secno">2. </bdi>Introduction</a></li><li class="tocline"><a class="tocxref" href="#definitions"><bdi class="secno">3. </bdi><span>Definitions</span></a><ol class="toc"><li class="tocline"><a class="tocxref" href="#overlay"><bdi class="secno">3.1 </bdi><span>Overlay</span></a></li></ol></li><li class="tocline"><a class="tocxref" href="#specification"><bdi class="secno">4. </bdi>Specification</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#versions"><bdi class="secno">4.1 </bdi>Versions</a></li><li class="tocline"><a class="tocxref" href="#format"><bdi class="secno">4.2 </bdi>Format</a></li><li class="tocline"><a class="tocxref" href="#document-structure"><bdi class="secno">4.3 </bdi>Document Structure</a></li><li class="tocline"><a class="tocxref" href="#relative-references-in-urls"><bdi class="secno">4.4 </bdi>Relative References in URLs</a></li><li class="tocline"><a class="tocxref" href="#schema"><bdi class="secno">4.5 </bdi>Schema</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#overlay-object"><bdi class="secno">4.5.1 </bdi>Overlay Object</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#fixed-fields"><bdi class="secno">4.5.1.1 </bdi>Fixed Fields</a></li></ol></li><li class="tocline"><a class="tocxref" href="#info-object"><bdi class="secno">4.5.2 </bdi>Info Object</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#fixed-fields-0"><bdi class="secno">4.5.2.1 </bdi>Fixed Fields</a></li></ol></li><li class="tocline"><a class="tocxref" href="#action-object"><bdi class="secno">4.5.3 </bdi>Action Object</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#fixed-fields-1"><bdi class="secno">4.5.3.1 </bdi>Fixed Fields</a></li></ol></li></ol></li><li class="tocline"><a class="tocxref" href="#examples"><bdi class="secno">4.6 </bdi>Examples</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#structured-overlays-example"><bdi class="secno">4.6.1 </bdi>Structured Overlays Example</a></li><li class="tocline"><a class="tocxref" href="#targeted-overlays"><bdi class="secno">4.6.2 </bdi>Targeted Overlays</a></li><li class="tocline"><a class="tocxref" href="#wildcard-overlays-examples"><bdi class="secno">4.6.3 </bdi>Wildcard Overlays Examples</a></li><li class="tocline"><a class="tocxref" href="#array-modification-examples"><bdi class="secno">4.6.4 </bdi>Array Modification Examples</a></li><li class="tocline"><a class="tocxref" href="#traits-examples"><bdi class="secno">4.6.5 </bdi>Traits Examples</a></li></ol></li><li class="tocline"><a class="tocxref" href="#specification-extensions"><bdi class="secno">4.7 </bdi>Specification Extensions</a></li></ol></li><li class="tocline"><a class="tocxref" href="#appendix-a-revision-history"><bdi class="secno">A. </bdi>Appendix A: Revision History</a></li><li class="tocline"><a class="tocxref" href="#references"><bdi class="secno">B. </bdi>References</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#normative-references"><bdi class="secno">B.1 </bdi>Normative references</a></li></ol></li></ol></nav>
<section id="overlay-specification"><div class="header-wrapper"><h2 id="x1-overlay-specification"><bdi class="secno">1. </bdi>Overlay Specification</h2><a class="self-link" href="#overlay-specification" aria-label="Permalink for Section 1."></a></div>
<section class="override" id="conformance"><div class="header-wrapper"><h3 id="x1-1-version-1-0-0"><bdi class="secno">1.1 </bdi>Version 1.0.0</h3><a class="self-link" href="#conformance" aria-label="Permalink for Section 1.1"></a></div>
<p>The key words “<em class="rfc2119">MUST</em>”, “<em class="rfc2119">MUST NOT</em>”, “<em class="rfc2119">REQUIRED</em>”, “<em class="rfc2119">SHALL</em>”, “<em class="rfc2119">SHALL NOT</em>”, “<em class="rfc2119">SHOULD</em>”, “<em class="rfc2119">SHOULD NOT</em>”, “<em class="rfc2119">RECOMMENDED</em>”, “<em class="rfc2119">NOT RECOMMENDED</em>”, “<em class="rfc2119">MAY</em>”, and “<em class="rfc2119">OPTIONAL</em>” in this document are to be interpreted as described in <a href="https://tools.ietf.org/html/bcp14">BCP 14</a> [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc2119" title="Key words for use in RFCs to Indicate Requirement Levels">RFC2119</a></cite>] [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc8174" title="Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words">RFC8174</a></cite>] when, and only when, they appear in all capitals, as shown here.</p>
<p>This document is licensed under <a href="https://www.apache.org/licenses/LICENSE-2.0.html">The Apache License, Version 2.0</a>.</p>
</section></section><section id="introduction"><div class="header-wrapper"><h2 id="x2-introduction"><bdi class="secno">2. </bdi>Introduction</h2><a class="self-link" href="#introduction" aria-label="Permalink for Section 2."></a></div>
<p>The Overlay specification is an extension or companion to the OpenAPI specification.
<p>The Overlay Specification is an extension or companion to the [<cite><a class="bibref" data-link-type="biblio" href="#bib-openapi" title="OpenAPI Specification">OpenAPI</a></cite>] specification.
An Overlay describes a set of changes to be applied or “overlaid” onto an existing OpenAPI description.</p>
<p>The main purpose of Overlays is to provide a way to repeatably apply transformations to one or many OpenAPI descriptions.
<p>The main purpose of the Overlay Specification is to provide a way to repeatably apply transformations to one or many OpenAPI descriptions.
Use cases include updating descriptions, adding metadata to be consumed by another tool, or removing certain elements from an API description before sharing it with partners.
Overlays may be specific to a single OpenAPI description, or be designed to apply the same transform to any OpenAPI description.</p>
An Overlay may be specific to a single OpenAPI description, or be designed to apply the same transform to any OpenAPI description.</p>
</section><section id="definitions"><div class="header-wrapper"><h2 id="x3-definitions"><bdi class="secno">3. </bdi><dfn id="dfn-definitions" tabindex="0" aria-haspopup="dialog" data-dfn-type="dfn">Definitions</dfn></h2><a class="self-link" href="#definitions" aria-label="Permalink for Section 3."></a></div>
<section id="overlay-document"><div class="header-wrapper"><h3 id="x3-1-overlay-document"><bdi class="secno">3.1 </bdi><dfn id="dfn-overlay-document" tabindex="0" aria-haspopup="dialog" data-dfn-type="dfn">Overlay Document</dfn></h3><a class="self-link" href="#overlay-document" aria-label="Permalink for Section 3.1"></a></div>
<p>An overlay document contains an ordered list of <a href="#overlay-actions">Action Objects</a> that are to be applied to the target document. Each <a href="#action-object">Action Object</a> has a <code>target</code> property and a modifier type (<code>update</code> or <code>remove</code>). The <code>target</code> property is a <cite><a class="bibref" data-link-type="biblio" href="#bib-rfc9535" title="JSONPath: Query Expressions for JSON">JSONPath</a></cite> query expression that identifies the elements of the target document to be updated and the modifier determines the change.</p>
<section id="overlay"><div class="header-wrapper"><h3 id="x3-1-overlay"><bdi class="secno">3.1 </bdi><dfn id="dfn-overlay" tabindex="0" aria-haspopup="dialog" data-dfn-type="dfn">Overlay</dfn></h3><a class="self-link" href="#overlay" aria-label="Permalink for Section 3.1"></a></div>
<p>An Overlay is a JSON or YAML structure containing an ordered list of <a href="#overlay-actions">Action Objects</a> that are to be applied to the target document. Each <a href="#action-object">Action Object</a> has a <code>target</code> property and a modifier type (<code>update</code> or <code>remove</code>). The <code>target</code> property is a <cite><a class="bibref" data-link-type="biblio" href="#bib-rfc9535" title="JSONPath: Query Expressions for JSON">JSONPath</a></cite> query expression that identifies the elements of the target document to be updated and the modifier determines the change.</p>
</section></section><section id="specification"><div class="header-wrapper"><h2 id="x4-specification"><bdi class="secno">4. </bdi>Specification</h2><a class="self-link" href="#specification" aria-label="Permalink for Section 4."></a></div>
<section id="versions"><div class="header-wrapper"><h3 id="x4-1-versions"><bdi class="secno">4.1 </bdi>Versions</h3><a class="self-link" href="#versions" aria-label="Permalink for Section 4.1"></a></div>
<p>The Overlay Specification is versioned using a <code>major</code>.<code>minor</code>.<code>patch</code> versioning scheme. The <code>major</code>.<code>minor</code> portion of the version string (for example 1.0) <em class="rfc2119">SHALL</em> designate the Overlay feature set. <code>.patch</code> versions address errors in, or provide clarifications to, this document, not the feature set. The patch version <em class="rfc2119">SHOULD NOT</em> be considered by tooling, making no distinction between 1.0.0 and 1.0.1 for example.</p>
Expand All @@ -258,7 +258,7 @@ <h1 id="title" class="title">Overlay Specification v1.0.0 </h1> <h2 id="subtitle
</section><section id="schema"><div class="header-wrapper"><h3 id="x4-5-schema"><bdi class="secno">4.5 </bdi>Schema</h3><a class="self-link" href="#schema" aria-label="Permalink for Section 4.5"></a></div>
<p>In the following description, if a field is not explicitly <strong><em class="rfc2119">REQUIRED</em></strong> or described with a <em class="rfc2119">MUST</em> or <em class="rfc2119">SHALL</em>, it can be considered <em class="rfc2119">OPTIONAL</em>.</p>
<section id="overlay-object"><div class="header-wrapper"><h4 id="x4-5-1-overlay-object"><bdi class="secno">4.5.1 </bdi>Overlay Object</h4><a class="self-link" href="#overlay-object" aria-label="Permalink for Section 4.5.1"></a></div>
<p>This is the root object of the <a href="#overlay-document">Overlay document</a>.</p>
<p>This is the root object of the <a href="#overlay">Overlay</a>.</p>
<section id="fixed-fields"><div class="header-wrapper"><h5 id="x4-5-1-1-fixed-fields"><bdi class="secno">4.5.1.1 </bdi>Fixed Fields</h5><a class="self-link" href="#fixed-fields" aria-label="Permalink for Section 4.5.1.1"></a></div>
<table>
<thead>
Expand Down Expand Up @@ -536,10 +536,10 @@ <h1 id="title" class="title">Overlay Specification v1.0.0 </h1> <h2 id="subtitle
<ul>
<li>Not referenced in this document.</li>
</ul>
</div><div class="dfn-panel" hidden="" role="dialog" aria-modal="true" id="dfn-panel-for-dfn-overlay-document" aria-label="Links in this document to definition: Overlay Document">
</div><div class="dfn-panel" hidden="" role="dialog" aria-modal="true" id="dfn-panel-for-dfn-overlay" aria-label="Links in this document to definition: Overlay">
<span class="caret"></span>
<div>
<a class="self-link" href="#dfn-overlay-document" aria-label="Permalink for definition: Overlay Document. Activate to close this dialog.">Permalink</a>
<a class="self-link" href="#dfn-overlay" aria-label="Permalink for definition: Overlay. Activate to close this dialog.">Permalink</a>

</div>
<p><b>Referenced in:</b></p>
Expand Down
Loading

0 comments on commit 503e83e

Please sign in to comment.