Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 37 ยท Specification Basics

OpenAPI Document Structure: The Root Fields Explained

A map of an OpenAPI 3.1 document: openapi, info, servers, paths, webhooks, components, security, tags and externalDocs, with a live structure explorer.

Before you write long specifications, you need a mental map of the document. An OpenAPI document is one object with a small, fixed set of top-level fields. Every other piece (operations, schemas, security) lives inside one of them. Once you know the map, the specification stops feeling like a wall of keywords.

The root object

YAML
openapi: 3.1.0            # required
info: {}                  # required
jsonSchemaDialect: ...    # optional (3.1)
servers: []               # optional
paths: {}                 # your endpoints
webhooks: {}              # optional (3.1): calls your API sends out
components: {}            # reusable pieces
security: []              # default security requirements
tags: []                  # names and descriptions for grouping
externalDocs: {}          # link to longer documentation

In 3.1 the document must contain at least one of paths, components or webhooks. In 3.0 paths was mandatory.

flowchart TD
  ROOT["OpenAPI document"] --> A["openapi"]
  ROOT --> B["info"]
  ROOT --> C["servers"]
  ROOT --> D["paths"]
  ROOT --> W["webhooks"]
  ROOT --> E["components"]
  ROOT --> F["security"]
  ROOT --> G["tags"]
  ROOT --> H["externalDocs"]
  D --> D1["Path item"] --> D2["Operation"] --> D3["parameters, requestBody, responses"]
  E --> E1["schemas, responses, parameters,<br/>requestBodies, headers, examples,<br/>securitySchemes, links, callbacks, pathItems"]

The root fields and the places where the most important objects hang.

Field by field

Field Purpose
openapi The specification version the document follows (3.1.0).
info Title, version, description, contact, license. See info, servers and tags.
servers Base URLs where the API is available.
paths Every URL path and the operations on it. See paths and operations.
webhooks Requests your API sends to others, described like path items.
components A library of reusable objects referenced with $ref. See components and $ref.
security Which security schemes apply to every operation by default. See security schemes.
tags Metadata for tags that operations use to group themselves.
externalDocs A link to documentation that lives elsewhere.

Specification extensions

Any object in the document may carry extra fields whose names start with x-. Tools ignore extensions they do not know, which makes them a safe place for your own metadata:

YAML
paths:
  /pets:
    get:
      x-rate-limit: 100
      x-team-owner: pets-squad

Vendors use x- fields heavily (for example x-codeSamples, x-logo). You will meet them again in code generation and documentation tools.

Naming rules to remember

  • Keys are case sensitive. Paths is not paths.
  • Unknown keys without the x- prefix are errors in strict validators.
  • Fixed fields are lowercase camelCase (operationId, requestBody, securitySchemes).
  • Names under components (such as schema names) may only contain letters, digits and . - _.

Explore a document programmatically

This stand-in prints the outline of any document: which root fields are present and how big each one is. It is the same walk a document-outline panel in an editor does.

Python Stand-in: outline an OpenAPI document

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Where does everything go? A quick guide

  • A URL and its HTTP verbs: paths.
  • A shape of data used in several places: components.schemas.
  • A header or error response repeated on many operations: components.headers / components.responses.
  • A way to authenticate: components.securitySchemes, applied with security.
  • A request the server sends to a customer's URL: webhooks (or callbacks inside an operation).

Defining something under components does not use it. A component only has an effect when something references it with $ref, or, for security schemes, when it is listed in a security requirement.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which root fields are required in an OpenAPI 3.1 document?

    3.1 requires openapi and info, and at least one of paths, components or webhooks.
  2. 2. What is the purpose of fields beginning with x-?

    x- fields are the official extension mechanism.
  3. 3. Where do you define a schema that several operations will reuse?

    Reusable schemas live under components.schemas and are referenced with $ref.
  4. 4. What does the webhooks field describe?

    Webhooks are incoming requests from the consumer's point of view: calls your API initiates.
  5. 5. A schema defined under components but never referenced is...

    Components are a library; they only matter once something references them.

Summary

  • The root object has a small set of fixed fields: openapi, info, servers, paths, webhooks, components, security, tags, externalDocs.
  • 3.1 requires at least one of paths, components or webhooks.
  • x- fields hold custom metadata and are ignored by tools that do not know them.
  • components is a library; nothing in it applies until it is referenced.

Next: Info, servers and tags