Skip to content

Commit df3eeb6

Browse files
committed
Authoritative rendering; "schema" usage (3.1.1 port of 3927)
This adds a note about the authoritative HTML rendering and adds a definition for "Schema" to explain the three ways the term is used in or with the specification.
1 parent 6a24378 commit df3eeb6

File tree

1 file changed

+8
-2
lines changed

1 file changed

+8
-2
lines changed

versions/3.1.1.md

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ An OpenAPI description can then be used by documentation generation tools to dis
1414

1515
For examples of OpenAPI usage and additional documentation, please visit [learn.openapis.org](https://learn.openapis.org/).
1616

17-
For extension registries and other specifications published by the OpenAPI Initiative, please visit [spec.openapis.org](https://spec.openapis.org/)
17+
For extension registries and other specifications published by the OpenAPI Initiative, as well as the authoritative rendering of this specification, please visit [spec.openapis.org](https://spec.openapis.org/).
1818

1919
## Table of Contents
2020
<!-- TOC depthFrom:1 depthTo:3 withLinks:1 updateOnSave:1 orderedList:0 -->
@@ -75,6 +75,12 @@ For extension registries and other specifications published by the OpenAPI Initi
7575
##### <a name="oasDocument"></a>OpenAPI Description
7676
An OpenAPI Description (OAD) formally describes the surface of an API and its semantics. It is composed of an [entry document](#documentStructure) and any/all of its referenced documents. An OAD uses and conforms to the OpenAPI Specification, and MUST contain at least one [paths](#pathsObject) field, [components](#oasComponents) field, or [webhooks](#oasWebhooks) field.
7777

78+
##### <a name="definitionsSchema"></a>Schema
79+
80+
A "schema" is a formal description of syntax and structure.
81+
This document serves as the [schema](#schema) for the OpenAPI Specification format; a non-authoritative JSON Schema based on this document is also provided on [spec.openapis.org](https://spec.openapis.org) for informational purposes.
82+
This specification also _uses_ schemas in the form of the [Schema Object](#schemaObject).
83+
7884
##### <a name="pathTemplating"></a>Path Templating
7985
Path templating refers to the usage of template expressions, delimited by curly braces (`{}`), to mark a section of a URL path as replaceable using path parameters.
8086

@@ -145,7 +151,7 @@ For example, if a field has an array value, the JSON array representation will b
145151
All field names in the specification are **case sensitive**.
146152
This includes all fields that are used as keys in a map, except where explicitly noted that keys are **case insensitive**.
147153

148-
The schema exposes two types of fields: Fixed fields, which have a declared name, and Patterned fields, which declare a regex pattern for the field name.
154+
The [schema](#schema) exposes two types of fields: Fixed fields, which have a declared name, and Patterned fields, which declare a regex pattern for the field name.
149155

150156
Patterned fields MUST have unique names within the containing object.
151157

0 commit comments

Comments
 (0)