OpenAPI Document Structure — Root Object and Top-Level Fields

In this tutorial, you will learn about OpenAPI Document Structure. We cover key concepts, practical examples, and best practices to help you master this topic.

The OpenAPI document structure consists of the root object with top-level fields including openapi, info, servers, paths, components, security, tags, and externalDocs that together define the complete API contract.

In this tutorial, you will learn every top-level field in the OpenAPI root object, which are required versus optional, and how they relate to each other.

What You'll Learn

You will learn the complete list of top-level OpenAPI fields, their data types, which are required, and how to structure a valid OpenAPI document from the root level down.

Why It Matters

Understanding the document structure is essential for writing valid OpenAPI specs. A well-organized spec is easier to maintain, review, and extend. Missing or misplaced fields cause validation errors.

Real-World Use

DodaTech standardizes the OpenAPI document structure across all services. Every spec follows the same template with required sections, ensuring consistent documentation and tooling compatibility.

graph TD
  A[openapi: 3.1.0] --> B[info]
  A --> C[servers]
  A --> D[paths]
  A --> E[components]
  A --> F[security]
  A --> G[tags]
  A --> H[externalDocs]
  A --> I[webhooks]
  B:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Root Object Fields

The root object is the entire OpenAPI document. It has these top-level fields:

openapi is a required string specifying the OpenAPI Specification version. It must be a valid version string like 3.1.0. This field tells tools which version of the specification to use for Parsing.

info is a required object providing metadata about the API. It includes title and version as required sub-fields, and optional fields for description, termsOfService, contact, and license.

jsonSchemaDialect is an optional string in 3.1 specifying the default JSON Schema dialect for schemas in the document.

servers is an optional array of server objects that provide base URLs for the API. At least one server is recommended.

paths is the core of the document. It is an optional object containing all relative API endpoints and their operations. While technically optional, a spec with no paths is not useful.

Webhooks is an optional object in 3.1 defining Webhook events the API can emit. Each key is an event name with a path-item-like object.

components is an optional container for reusable schemas, parameters, responses, request bodies, headers, security schemes, examples, links, and callbacks.

security is an optional array of security requirement objects that apply globally to all operations.

tags is an optional array of tag objects for grouping operations in documentation.

externalDocs is an optional object linking to external documentation.

openapi: 3.1.0
jsonSchemaDialect: https://spec.openapis.org/oas/3.1/dialect/base
info:
  title: DodaTech Users API
  version: 1.0.0
  description: API for managing user accounts on the DodaTech platform
  termsOfService: https://dodatech.com/terms
  contact:
    name: API Support
    email: api@dodatech.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: https://api.dodatech.com/v1
    description: Production
paths:
  /users:
    get:
      summary: List users
      operationId: listUsers
      responses:
        "200":
          description: User list
webhooks:
  user.created:
    post:
      summary: New user created
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
security:
  - BearerAuth: []
tags:
  - name: Users
    description: User management operations
externalDocs:
  description: Full API documentation
  url: https://docs.dodatech.com

Ordering and Conventions

OpenAPI does not require a specific field order, but convention suggests: openapi, info, servers, paths, webhooks, components, security, tags, externalDocs.

# Conventional field ordering
openapi: 3.1.0
info: {}
servers: []
paths: {}
webhooks: {}
components: {}
security: []
tags: []
externalDocs: {}

Common Mistakes

1. Missing openapi field — Every spec must declare the OpenAPI version. Tools cannot parse a spec without this field.

2. Incorrect version format — Using an old version string like swagger: "2.0" instead of openapi: 3.1.0. The version field changed from swagger to openapi.

3. Info without title and version — The info object requires both title and version. Omitting either makes the spec invalid.

4. Paths key format errors — Paths must start with a forward slash. Using users instead of /users causes parsing errors.

5. Typo in field names — OpenAPI field names are case-sensitive. Use paths not pathes, components not componentss.

Practice Questions

1. What are the required fields in an OpenAPI document?
2. What is the purpose of the jsonSchemaDialect field?
3. How does the webhooks field differ from paths?
4. What is the conventional field ordering?
5. What happens if paths is omitted?

Challenge

Write a valid OpenAPI 3.1 document with all top-level fields populated. Include a meaningful info section, two server URLs, at least two paths, one webhook, components with a schema and security scheme, tags, and externalDocs. Validate it with an OpenAPI validator.

FAQ

Mini Project

Create an OpenAPI document template that your team can use as a starting point for new APIs. Include all top-level fields with placeholder content, comments explaining each field, and standard security schemes and error responses in components.

What's Next

In the next lesson, you will learn the info object in detail, including contact, license, and metadata fields.