Last updated

metadata

Configure metadata properties for your project, APIs, and documentation files. Metadata is used for content categorization, search facets, catalog filtering, and scorecard functionality.

How it works

The metadata option accepts an object with key-value pairs:

  • Keys can be any string identifier
  • Values can be any scalar value (string, number, boolean)
  • Some metadata keys have special functionality (e.g., redocly_category for search facets)

Metadata can be defined in several ways, with the following priority (highest to lowest):

  1. x-metadata extension in OpenAPI files
  2. Front matter in Markdown files
  3. metadata in the redocly.yaml configuration

Options

OptionTypeDescription
metadataobjectAn object of key-value pairs. Keys can be any string, and values can be any scalar value.

Examples

Basic metadata configuration

redocly.yaml
metadata:
  owner: Redocly
  team: Documentation
  department: Engineering
  status: Published

API-specific metadata

You can define metadata for specific APIs in your configuration:

redocly.yaml
apis:
  museum:
    root: ./museum.yaml
    type: openapi
    metadata:
      owner: API Team
      category: eCommerce
      status: Beta

Use the x-metadata extension in OpenAPI files

openapi.yaml
openapi: 3.1.0
info:
  title: Museum API
  description: A sample API for museum tickets
  version: 1.0.0
  x-metadata:
    owner: API Team
    department: Product
    category: eCommerce
    status: Production

Use metadata in Markdown front matter

introduction.md
---
metadata:
  owner: Documentation Team
  category: Guides
  status: Draft
  redocly_category: Learn
---

# Introduction

This is an introduction to our API documentation.

Use metadataGlobs for pattern-based assignment

redocly.yaml
metadataGlobs:
  'apis/museum/**':
    owner: Museum Team
    redocly_category: API Reference
  'guides/**':
    redocly_category: Guides
  '**':
    company: Redocly

Use reserved metadata keys

Some metadata keys are reserved for specific functionality:

redocly.yaml
metadata:
  redocly_category: API Reference  # Used for search facets and categorization
  team: API Team                   # Can be used for scorecard team attribution
  owner: John Doe                  # Can be used for ownership attribution

Reserved metadata keys

While most metadata keys can be used for any purpose, some have special functionality:

  • redocly_category: Used for search facets and content categorization
  • team and owner: Often used for attribution in scorecards and catalogs

Resources

 
Next page