You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<td>This string <em class="rfc2119">MUST</em> be in the form of a URI reference as defined by [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc3986" title="Uniform Resource Identifier (URI): Generic Syntax">RFC3986</a></cite>] <a href="https://tools.ietf.org/html/rfc3986#section-4.1">Section 4.1</a>. The <code>$self</code> field provides the self-assigned URI of this document, which also serves as its base URI in accordance with [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc3986" title="Uniform Resource Identifier (URI): Generic Syntax">RFC3986</a></cite>] <a href="https://tools.ietf.org/html/rfc3986#section-5.1.1">Section 5.1.1</a>. Implementations <em class="rfc2119">MUST</em> support identifying the targets of <a href="#relative-references-in-api-description-uris">API description URIs</a> using the URI defined by this field when it is present. See <a href="#establishing-the-base-uri">Establishing the Base URI</a> for the base URI behavior when <code>$self</code> is absent or relative, and see <a href="(#appendix-f-examples-of-base-uri-determination-and-reference-resolution)">Appendix F</a> for examples of using <code>$self</code> to resolve references.</td>
407
+
<td>This string <em class="rfc2119">MUST</em> be in the form of a URI reference as defined by [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc3986" title="Uniform Resource Identifier (URI): Generic Syntax">RFC3986</a></cite>] <a href="https://tools.ietf.org/html/rfc3986#section-4.1">Section 4.1</a>. The <code>$self</code> field provides the self-assigned URI of this document, which also serves as its base URI in accordance with [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc3986" title="Uniform Resource Identifier (URI): Generic Syntax">RFC3986</a></cite>] <a href="https://tools.ietf.org/html/rfc3986#section-5.1.1">Section 5.1.1</a>. Implementations <em class="rfc2119">MUST</em> support identifying the targets of <a href="#relative-references-in-api-description-uris">API description URIs</a> using the URI defined by this field when it is present. See <a href="#establishing-the-base-uri">Establishing the Base URI</a> for the base URI behavior when <code>$self</code> is absent or relative, and see <a href="#appendix-f-examples-of-base-uri-determination-and-reference-resolution">Appendix F</a> for examples of using <code>$self</code> to resolve references.</td>
<p>A querystring parameter using regular form encoding, but managed with a Media Type Object.
1807
-
This shows spaces being handled per the <code>application/x-www-form-urlencoded</code> media type rules (encode as <code>+</code>) rather than the RFC6570 process (encode as <code>%20</code>); see <a href="appendix-e-percent-encoding-and-form-media-types">Appendix E</a> for further guidance on this distinction.
1807
+
This shows spaces being handled per the <code>application/x-www-form-urlencoded</code> media type rules (encode as <code>+</code>) rather than the RFC6570 process (encode as <code>%20</code>); see <a href="#appendix-e-percent-encoding-and-form-media-types">Appendix E</a> for further guidance on this distinction.
1808
1808
Examples are shown at both the media type and parameter level to emphasize that, since <code>application/x-www-form-urlencoded</code> is suitable for use in query strings by definition, no further encoding or escaping is applied to the serialized media type value:</p>
<p>To upload multiple files, a <code>multipart</code> media type <em class="rfc2119">MUST</em> be used as shown under <a href="#example-multipart-form-with-multiple-files">Example: Multipart Form with Multiple Files</a>.</p>
<p>A single encoding definition applied to a single value, with the mapping of Encoding Objects to values determined by the <a href="@media-type-object">Media Type Object</a> as described under <a href="#encoding-usage-and-restrictions">Encoding Usage and Restrictions</a>.</p>
2336
+
<p>A single encoding definition applied to a single value, with the mapping of Encoding Objects to values determined by the <a href="#media-type-object">Media Type Object</a> as described under <a href="#encoding-usage-and-restrictions">Encoding Usage and Restrictions</a>.</p>
2337
2337
<p>See <a href="#appendix-b-data-type-conversion">Appendix B</a> for a discussion of converting values of various types to string representations.</p>
2338
2338
<p>See <a href="#appendix-e-percent-encoding-and-form-media-types">Appendix E</a> for a detailed examination of percent-encoding concerns for form media types.</p>
</section><section id="example-ordered-multipart-with-required-header"><div class="header-wrapper"><h5 id="x4-15-4-7-example-ordered-multipart-with-required-header"><bdi class="secno">4.15.4.7 </bdi>Example: Ordered Multipart With Required Header</h5><a class="self-link" href="#example-ordered-multipart-with-required-header" aria-label="Permalink for Section 4.15.4.7"></a></div>
2644
2644
<p>As described in [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc2557" title="MIME Encapsulation of Aggregate Documents, such as HTML (MHTML)">RFC2557</a></cite>], a set of resources making up a web page can be sent in a <code>multipart/related</code> payload, preserving links from the <code>text/html</code> document to subsidiary resources such as scripts, style sheets, and images by defining a <code>Content-Location</code> header for each page.
2645
2645
The first part is used as the root resource (unless using <code>Content-ID</code>, which RFC2557 advises against and is forbidden in this example), so we use <code>prefixItems</code> and <code>prefixEncoding</code> to define that it must be an HTML resource, and then allow any of several different types of resources in any order to follow.</p>
2646
-
<p>The <code>Content-Location</code> header is defined using <code>content: {text/plain: {...}}</code> to avoid percent-encoding its URI value; see <a href="appendix-d-serializing-headers-and-cookies">Appendix D</a> for further details.</p>
2646
+
<p>The <code>Content-Location</code> header is defined using <code>content: {text/plain: {...}}</code> to avoid percent-encoding its URI value; see <a href="#appendix-d-serializing-headers-and-cookies">Appendix D</a> for further details.</p>
<p>For <code>multipart/byteranges</code> [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc9110" title="HTTP Semantics">RFC9110</a></cite>] <a href="https://tools.ietf.org/html/rfc9110#section-14.6">Section 14.6</a>, a <code>Content-Range</code> header is required:</p>
2697
-
<p>See <a href="appendix-d-serializing-headers-and-cookies">Appendix D</a> for an explanation of why <code>content: {text/plain: {...}}</code> is used to describe the header value.</p>
2697
+
<p>See <a href="#appendix-d-serializing-headers-and-cookies">Appendix D</a> for an explanation of why <code>content: {text/plain: {...}}</code> is used to describe the header value.</p>
<p>As also noted in the RFC, <code>Set-Cookie</code> is an exception as it allows unquoted, non-escaped commas in its values, and can only use the one-value-per-line form.
3539
3539
For HTTP messages, this is purely a serialization concern, and no more of a problem than a message that uses the multi-line form of any other header.</p>
3540
3540
<p>However, because examples and values modeled with <code>content</code> do not incorporate the header name, for these fields <code>Set-Cookie</code> <em class="rfc2119">MUST</em> be handled by placing each value on a separate line, without the header name or the <code>:</code> delimiter.</p>
3541
-
<p>Note also that any URI percent-encoding, base64 encoding, or other escaping <em class="rfc2119">MUST</em> be performed prior to supplying the data to OAS tooling; see <a href="appendix-d-serializing-headers-and-cookies">Appendix D</a> for details.</p>
3541
+
<p>Note also that any URI percent-encoding, base64 encoding, or other escaping <em class="rfc2119">MUST</em> be performed prior to supplying the data to OAS tooling; see <a href="#appendix-d-serializing-headers-and-cookies">Appendix D</a> for details.</p>
3542
3542
<p>The following example shows two different ways to describe <code>Set-Cookie</code> headers that require cookies named <code>"lang"</code> and <code>"foo"</code>, as well as a <code>"urlSafeData"</code> cookie that is expected to be percent-encoded. The first uses <code>content</code> in order to show exactly how such examples are formatted, but also notes the limitations of schema constraints with multi-line text. The second shows the use of <code>style: "simple"</code>, which produces the same serialized example text (with each line corresponding to one <code>Set-Cookie:</code> line in the HTTP response), but allows schema constraints on each cookie; note that the percent-encoding is already applied in the <code>dataValue</code> field of the example:</p>
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments