Restructure sections before publication

[lornajane]

Could we shuffle some of the sections in the specification? One thing I find frustrating in 3.1.1 is how difficult it is to find the actual fields in the specification (https://spec.openapis.org/oas/v3.1.1.html#openapi-object). All the information we have is needed, but I think the OpenAPI document structure is a logical entry point for many users and it's an extreme version of "below the fold" at the moment.

[lornajane]

Ping @handrews and @ralfhandl as being my most likely collaborators on this one, but all comments and suggestions are welcome!

[ralfhandl]

What would you like to reshuffle?

I could see sections "4.5 Rich Text Formatting" and sections 4.6 and 4.7 on relative references moved after section "4.8 Schema", and section 4.8 could get a more catchy headline. Unfortunately the natural headline "OpenAPI Description Structure" is already used for describing how to split a Description into Documents.

[handrews]

@ralfhandl I think you are working from an outdated structure. I rearranged the "OpenAPI Description Structure" to encompass all of the mechanics of connecting documents, including URIs (and the related topic of resolving API URLs since they both ultimately can resolve relative to the document).

@lornajane I am skeptical of moving anything that's before §4.7 Schema to after it. The structure and basics of working with data are prerequisites for implementation. I'm particularly opposed to burying the reference resolution rules. People looking for document structure should be directed to the learn site, which should be oriented towards users rather than implementors.

I do think that "Schema" is a horribly confusing name for that section. I could definitely be convinced to change it (and "OpenAPI Description Structure") to something that works better for each section. "OpenAPI Description Structure" is not great for what it's doing right now either, TBH.

Here's the current TOC:

# OpenAPI Specification
## Version 3.2.0

## Introduction

## Definitions
### OpenAPI Description

### OpenAPI Document

### Schema

### Object

### Path Templating

### Media Types
#### Sequential Media Types
#### Media Type Registry

### HTTP Status Codes

### Case Sensitivity

### Undefined and Implementation-Defined Behavior

## Specification

### Versions

### Deprecation

### Format
#### JSON and YAML Compatibility

### OpenAPI Description Structure
#### Parsing Documents
#### Structural Interoperability
#### Relative References in API Description URIs
##### Establishing the Base URI
##### Resolving URI fragments
##### Relative URI References in CommonMark Fields
#### Relative References in API URLs
##### Examples of API Base URL Determination
#### Resolving Implicit Connections

### Working with Data
#### Data Types
##### Data Type Format
#### Parsing and Serializing
##### JSON Data
##### Non-JSON Data
##### Working with Binary Data
###### Schema Evaluation and Binary Data
###### Migrating binary descriptions from OAS 3.0

### Rich Text Formatting

### Schema
#### OpenAPI Object
##### Fixed Fields

#### Info Object
##### Fixed Fields
##### Info Object Example

#### Contact Object
##### Fixed Fields
##### Contact Object Example

#### License Object
##### Fixed Fields
##### License Object Example

#### Server Object
##### Fixed Fields
##### Server Object Example

#### Server Variable Object
##### Fixed Fields

#### Components Object
##### Fixed Fields
##### Components Object Example

#### Paths Object
##### Patterned Fields
##### Path Templating Matching
##### Paths Object Example

#### Path Item Object
##### Fixed Fields
##### Path Item Object Example

#### Operation Object
##### Fixed Fields
##### Operation Object Example

#### External Documentation Object
##### Fixed Fields
##### External Documentation Object Example

#### Parameter Object
##### Parameter Locations
##### Fixed Fields
###### Common Fixed Fields
###### Fixed Fields for use with `schema`
###### Fixed Fields for use with `content`
##### Style Values
##### URL Percent-Encoding
##### Serialization and Examples
##### Style Examples
##### Extending Support for Querystring Formats
##### Parameter Object Examples

#### Request Body Object
##### Fixed Fields
##### Request Body Examples

#### Media Type Object
##### Fixed Fields
##### Complete vs Streaming Content
###### Binary Streams
###### Streaming Sequential Media Types
##### Special Considerations for `text/event-stream` Content
##### Encoding Usage and Restrictions
###### Encoding By Name
###### Encoding By Position
###### Additional Encoding Approaches
##### Media Type Examples
###### JSON
###### Sequential JSON
###### Server-Sent Event Streams
##### Considerations for File Uploads

#### Encoding Object
##### Fixed Fields
###### Common Fixed Fields
###### Fixed Fields for RFC6570-style Serialization
##### Nested Encoding
##### Encoding the `x-www-form-urlencoded` Media Type
###### Example: URL Encoded Form with JSON Values
###### Example: URL Encoded Form with Binary Values
##### Encoding `multipart` Media Types
###### Handling Multiple `contentType` Values
###### `Content-Transfer-Encoding` and `contentEncoding`
###### Example: Basic Multipart Form
###### Example: Multipart Form with Encoding Objects
###### Example: Multipart Form with Multiple Files
###### Example: Ordered, Unnamed Multipart
###### Example: Ordered Multipart With Required Header
###### Example: Streaming Multipart
###### Example: Streaming Byte Ranges
###### Example: Nested `multipart/mixed`

#### Responses Object
##### Fixed Fields
##### Patterned Fields
##### Responses Object Example

#### Response Object
##### Fixed Fields
##### Response Object Examples

#### Callback Object
##### Patterned Fields
##### Key Expression
##### Callback Object Examples

#### Example Object
##### Fixed Fields
##### Working with Examples
###### JSON-Compatible and `value`-Safe Examples
###### Choosing Which Field(s) to Use
###### Criteria for `serializedExample`
###### Validating Examples
##### Example Object Examples
###### JSON Examples
###### Binary Examples
###### Boolean Query Parameter Examples

#### Link Object
##### Fixed Fields
##### Examples
##### `operationRef` Examples
##### Runtime Expressions
##### Examples

#### Header Object
##### Fixed Fields
###### Common Fixed Fields
###### Fixed Fields for use with `schema`
###### Fixed Fields for use with `content`
##### Modeling Link Headers
##### Representing the `Set-Cookie` Header
##### Header Object Example

#### Tag Object
##### Fixed Fields
##### Tag Object Example

#### Reference Object
##### Fixed Fields
##### Reference Object Example
##### Relative Schema Document Example
##### Relative Documents with Embedded Schema Example

#### Schema Object
##### JSON Schema Keywords
##### Fixed Fields
##### Extended Validation with Annotations
###### Non-validating constraint keywords
###### Validating `readOnly` and `writeOnly`
##### Data Modeling Techniques
###### Composition and Inheritance (Polymorphism)
###### Generic (Template) Data Structures
###### Annotated Enumerations
###### XML Modeling
##### Specifying Schema Dialects
##### Schema Object Examples
###### Primitive Example
###### Simple Model
###### Model with Map/Dictionary Properties
###### Model with Annotated Enumeration
###### Model with Example
###### Models with Composition
###### Models with Polymorphism Support
###### Models with Polymorphism Support and a Discriminator Object
###### Models with Polymorphism Support using allOf and a Discriminator Object
###### Generic Data Structure Model

#### Discriminator Object
##### Fixed Fields
##### Conditions for Using the Discriminator Object
##### Options for Mapping Values to Schemas
##### Optional discriminating property
##### Examples

#### XML Object
##### Fixed Fields
##### XML Node Types
###### Modeling Element Lists
###### Implicit and Explicit `text` Nodes
##### XML Node Names
##### Namespace Limitations
##### Handling `null` Values
##### XML Object Examples
###### No XML Object
###### XML Name Replacement
###### XML Attribute, Prefix and Namespace
###### XML Arrays
###### Elements With Attributes And Text
###### Referenced Element With CDATA
###### Ordered Elements and Text
###### XML With `null` Values

#### Security Scheme Object
##### Fixed Fields
##### Security Scheme Object Examples
###### Basic Authentication Example
###### API Key Example
###### JWT Bearer Example
###### MutualTLS Example
###### Implicit OAuth2 Example

#### OAuth Flows Object
##### Fixed Fields

#### OAuth Flow Object
##### Fixed Fields
##### OAuth Flow Object Example

#### Security Requirement Object
##### Patterned Fields
##### Security Requirement Object Examples
###### Non-OAuth2 Security Requirement
###### OAuth2 Security Requirement
###### Optional OAuth2 Security

### Specification Extensions

### Security Filtering

## Security Considerations
### OpenAPI Description Formats
### Tooling and Usage Scenarios
### Security Schemes
### Handling External Resources
### Handling Reference Cycles
### Markdown and HTML Sanitization

## Appendix A: Revision History

## Appendix B: Data Type Conversion

## Appendix C: Using RFC6570-Based Serialization
### Equivalences Between Fields and RFC6570 Operators
### Delimiters in Parameter Values
### Non-RFC6570 Field Values and Combinations
### Examples
#### RFC6570-Equivalent Expansion
#### Expansion with Non-RFC6570-Supported Options
#### Undefined Values and Manual URI Template Construction
#### Illegal Variable Names as Parameter Names

## Appendix D: Serializing Headers and Cookies
### Percent-Encoding and Cookies

## Appendix E: Percent-Encoding and Form Media Types
### Percent-Encoding Character Classes
### Percent-Encoding and `form-urlencoded`
### Percent-Encoding and `form-data`
### Generating and Validating URIs and `form-urlencoded` Strings
#### Interoperability with Historical Specifications
#### Interoperability with Web Browser Environments
### Decoding URIs and `form-urlencoded` Strings
### Percent-Encoding and Illegal or Reserved Delimiters

## Appendix F: Resolving Security Requirements in a Referenced Document

## Appendix G: Examples of Base URI Determination and Reference Resolution
### Base URI Within Content
### Base URI From Encapsulating Entity
### Base URI From the Retrieval URI
### Application-Specific Default Base URI
### Resolving Relative `$self` and `$id`

[handrews]

@lornajane @ralfhandl one option could be to rename 4.7 Schema to 4.7 Specification Objects and Fields or something like that.

[handrews]

OK I've been playing with this, and I think I have an approach that will get the OpenAPI Object section (the first with a table of fields) much closer to the top.

Several front-loaded sections have pretty obvious places where they can go (with a few tweaks here and there), generally right after the "Fixed Fields" and/or "Pattered Fields" sections:

• Path Templating -> Paths Object
• Relative References in API URLs -> Server Object
• Working With Data -> Schema Object (remove "Working with Data" and just put the subsections under here)
• HTTP Response Codes -> Response Object
• Rich Text Formatting -> Format

Some things really could be banished to appendixes, specifically the weird corner case stuff:

• Structural Interoperability (arguably the worst title I've ever come up with) -> reworked Appendix G or new Appendix H
• part of Parsing Documents (the parts about detailed implementation guidance and weird corner cases) -> reworked Appendix G or new Appendix H

A few don't really need to be sections, although they do need to be somewhere (the "Object" and "Schema" under "Definitions" could just be in a smaller Definition section, or a Terminology subsection), and the "Deprecation" section could just be a paragraph in "Versions", or we could call the consolidated section "Versions and Deprecation" or something).

Whatever the remaining terminology section, plus "Undefined and Implementation-Defined Behavior" (which does need to be its own section), and the "Format" section (as expanded above) do need to be before the "Schema"-but-lets-rename-it section.

The remainder is best put under "OpenAPI Object", as the OAD structure stuff is literally rooted in the OpenAPI Object (e.g. the entry document is the one with the OpenAPI Object containing the API's usable Paths Object in it).

The one thing I'm still figuring out is the URI reference stuff- it is probably easiest to just keep that section together with the other structural things stuff it all beneath the "Fixed Fields" subsection fo the OpenAPI Object, but some of it could arguably go to the Reference Object. But that is very far down, so I'd want to yank it up to just after the OpenAPI Object. The tricky one is "Resolving Implicit Connections", as it collects information from a random set of Objects that just don't work in a normal way. No one Object is a good home for it, so the OpenAPI Object is the best option. And if "Resolving Implicit Connections" is under the OpenAPI Object, the URI-reference stuff ought to stay with it. I think? Comments welcome.

[handrews]

Here's a possible revised TOC. I actually decided we could just fold "Schema" (the Definitions one) and "Object" into some other section, if we even still need them. The term "schema" won't be so badly overloaded anymore, and the note about capital-O "Object" could be explained at first use, or just dropped as people will probably figure it out on their own. idk. I'm not sure about that part. [EDIT: Since we're renaming the main "Schema" section "Objects and Fields", we probably don't need to explain capital-O "Object"].

Note also that I got rid of "Specification" as a heading- this lets us keep the nesting levels down, and I feel like it was a redundant heading. The whole thing is the specification. We've never had a clear separation between normative vs informative sections. Or, if "Specification" was supposed to be the only normative part, it's not anymore so there's nothing meaningful in the distinction.

Oh and I moved "Security Filtering" under "Security Considerations" although that's not necessary for this discussion and I don't care if we do it or not.

# OpenAPI Specification
## Version 3.2.0

## Introduction
### Versions and Deprecation
### Undefined and Implementation-Defined Behavior

## Format
### JSON and YAML Compatibility
### Case Sensitivity
### Rich Text Formatting

## Objects and Fields

### OpenAPI Object
#### Fixed Fields
#### OpenAPI Description Structure
##### OpenAPI Description
##### OpenAPI Documents
##### Parsing Documents
##### Relative References in API Description URIs
###### Establishing the Base URI
###### Resolving URI fragments
###### Relative URI References in CommonMark Fields
##### Resolving Implicit Connections

### Info Object
#### Fixed Fields
#### Info Object Example

### Contact Object
#### Fixed Fields
#### Contact Object Example

### License Object
#### Fixed Fields
#### License Object Example

### Server Object
#### Fixed Fields
#### Relative References in API URLs
##### Examples of API Base URL Determination
#### Server Object Example

### Server Variable Object
#### Fixed Fields

### Components Object
#### Fixed Fields
#### Components Object Example

### Paths Object
#### Patterned Fields
#### Path Templating
##### Path Templating Matching
#### Paths Object Example

### Path Item Object
#### Fixed Fields
#### Path Item Object Example

### Operation Object
#### Fixed Fields
#### Operation Object Example

### External Documentation Object
#### Fixed Fields
#### External Documentation Object Example

### Parameter Object
#### Parameter Locations
#### Fixed Fields
##### Common Fixed Fields
##### Fixed Fields for use with `schema`
##### Fixed Fields for use with `content`
#### Style Values
#### URL Percent-Encoding
#### Serialization and Examples
#### Style Examples
#### Extending Support for Querystring Formats
#### Parameter Object Examples

### Request Body Object
#### Fixed Fields
#### Request Body Examples

### Media Type Object
#### Fixed Fields
#### Media Types
##### Sequential Media Types
##### Media Type Registry
#### Complete vs Streaming Content
##### Binary Streams
##### Streaming Sequential Media Types
#### Special Considerations for `text/event-stream` Content
#### Encoding Usage and Restrictions
##### Encoding By Name
##### Encoding By Position
##### Additional Encoding Approaches
#### Media Type Examples
##### JSON
##### Sequential JSON
##### Server-Sent Event Streams
#### Considerations for File Uploads

### Encoding Object
#### Fixed Fields
##### Common Fixed Fields
##### Fixed Fields for RFC6570-style Serialization
#### Nested Encoding
#### Encoding the `x-www-form-urlencoded` Media Type
##### Example: URL Encoded Form with JSON Values
##### Example: URL Encoded Form with Binary Values
#### Encoding `multipart` Media Types
##### Handling Multiple `contentType` Values
##### `Content-Transfer-Encoding` and `contentEncoding`
##### Example: Basic Multipart Form
##### Example: Multipart Form with Encoding Objects
##### Example: Multipart Form with Multiple Files
##### Example: Ordered, Unnamed Multipart
##### Example: Ordered Multipart With Required Header
##### Example: Streaming Multipart
##### Example: Streaming Byte Ranges
##### Example: Nested `multipart/mixed`

### Responses Object
#### Fixed Fields
#### Patterned Fields
#### Responses Object Example

### Response Object
#### Fixed Fields
#### HTTP Status Codes
#### Response Object Examples

### Callback Object
#### Patterned Fields
#### Key Expression
#### Callback Object Examples

### Example Object
#### Fixed Fields
#### Working with Examples
##### JSON-Compatible and `value`-Safe Examples
##### Choosing Which Field(s) to Use
##### Criteria for `serializedExample`
##### Validating Examples
#### Example Object Examples
##### JSON Examples
##### Binary Examples
##### Boolean Query Parameter Examples

### Link Object
#### Fixed Fields
#### Examples
##### `operationRef` Examples
#### Runtime Expressions
##### Example Expressions

### Header Object
#### Fixed Fields
##### Common Fixed Fields
##### Fixed Fields for use with `schema`
##### Fixed Fields for use with `content`
#### Modeling Link Headers
#### Representing the `Set-Cookie` Header
#### Header Object Example

### Tag Object
#### Fixed Fields
#### Tag Object Example

### Reference Object
#### Fixed Fields
#### Reference Object Example
#### Relative Schema Document Example
#### Relative Documents with Embedded Schema Example

### Schema Object
#### JSON Schema Keywords
#### Fixed Fields
#### Data Types
##### Data Type Format
#### Parsing and Serializing
##### JSON Data
##### Non-JSON Data
##### Working with Binary Data
###### Schema Evaluation and Binary Data
###### Migrating binary descriptions from OAS 3.0
#### Extended Validation with Annotations
##### Non-validating constraint keywords
##### Validating `readOnly` and `writeOnly`
#### Data Modeling Techniques
##### Composition and Inheritance (Polymorphism)
##### Generic (Template) Data Structures
##### Annotated Enumerations
##### XML Modeling
#### Specifying Schema Dialects
#### Schema Object Examples
##### Primitive Example
##### Simple Model
##### Model with Map/Dictionary Properties
##### Model with Annotated Enumeration
##### Model with Example
##### Models with Composition
##### Models with Polymorphism Support
##### Models with Polymorphism Support and a Discriminator Object
##### Models with Polymorphism Support using allOf and a Discriminator Object
##### Generic Data Structure Model

### Discriminator Object
#### Fixed Fields
#### Conditions for Using the Discriminator Object
#### Options for Mapping Values to Schemas
#### Optional discriminating property
#### Examples

### XML Object
#### Fixed Fields
#### XML Node Types
##### Modeling Element Lists
##### Implicit and Explicit `text` Nodes
#### XML Node Names
#### Namespace Limitations
#### Handling `null` Values
#### XML Object Examples
##### No XML Object
##### XML Name Replacement
##### XML Attribute, Prefix and Namespace
##### XML Arrays
##### Elements With Attributes And Text
##### Referenced Element With CDATA
##### Ordered Elements and Text
##### XML With `null` Values

### Security Scheme Object
#### Fixed Fields
#### Security Scheme Object Examples
##### Basic Authentication Example
##### API Key Example
##### JWT Bearer Example
##### MutualTLS Example
##### Implicit OAuth2 Example

### OAuth Flows Object
#### Fixed Fields

### OAuth Flow Object
#### Fixed Fields
#### OAuth Flow Object Example

### Security Requirement Object
#### Patterned Fields
#### Security Requirement Object Examples
##### Non-OAuth2 Security Requirement
##### OAuth2 Security Requirement
##### Optional OAuth2 Security

### Specification Extensions

## Security Considerations
### OpenAPI Description Formats
### Tooling and Usage Scenarios
### Security Filtering
### Security Schemes
### Handling External Resources
### Handling Reference Cycles
### Markdown and HTML Sanitization

## Appendix A: Revision History

## Appendix B: Data Type Conversion

## Appendix C: Using RFC6570-Based Serialization
### Equivalences Between Fields and RFC6570 Operators
### Delimiters in Parameter Values
### Non-RFC6570 Field Values and Combinations
### Examples
#### RFC6570-Equivalent Expansion
#### Expansion with Non-RFC6570-Supported Options
#### Undefined Values and Manual URI Template Construction
#### Illegal Variable Names as Parameter Names

## Appendix D: Serializing Headers and Cookies
### Percent-Encoding and Cookies

## Appendix E: Percent-Encoding and Form Media Types
### Percent-Encoding Character Classes
### Percent-Encoding and `form-urlencoded`
### Percent-Encoding and `form-data`
### Generating and Validating URIs and `form-urlencoded` Strings
#### Interoperability with Historical Specifications
#### Interoperability with Web Browser Environments
### Decoding URIs and `form-urlencoded` Strings
### Percent-Encoding and Illegal or Reserved Delimiters

## Appendix F: Resolving Security Requirements in a Referenced Document

## Appendix G: Parsing and Reference Resolution
### Complete vs Fragmentary Documents
#### Structural Interoperability
### Examples of Base URI Determination and Reference Resolution
#### Base URI Within Content
#### Base URI From Encapsulating Entity
#### Base URI From the Retrieval URI
#### Application-Specific Default Base URI
#### Resolving Relative `$self` and `$id`

[lornajane]

This looks pretty good to me!

[handrews]

@lornajane awesome- if no one else objects, I'll do this after the other PRs (cookie, allowReserved etc.)

[lornajane]

Perfect, I guessed we were in an issue because of the conflict potential! I am standing by to review

[ralfhandl]

I like it, although it makes it very hard to figure out the differences between 3.2 and 3.1.

And we may have to tweak the md2html script as it has some built-in assumptions about (the sequence of) the section headings.

[lornajane]

We'll use release notes to summarise the differences, as it's a minor release there is already significantly too much change to make any sort of diff useful.