{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"metadata","__idx":0},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["metadata"]}]},{"$$mdtype":"Tag","name":"ConfigOptionRequirements","attributes":{"products":["Redoc","Revel","Reef","Realm"],"plans":["Pro","Enterprise","Enterprise+"]},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Configure metadata properties for your project, APIs, and documentation files."," ","Metadata is used for content categorization, search facets, catalog filtering, and scorecard functionality."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-it-works","__idx":1},"children":["How it works"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["metadata"]}," option accepts an object with key-value pairs:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Keys can be any string identifier."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Values can be any scalar value (string, number, boolean)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Some metadata keys have special functionality (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly_category"]}," for search facets)."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Metadata can be defined in several ways, with the following priority (highest to lowest):"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-metadata"]}," extension in OpenAPI files"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Front matter in Markdown files"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["metadata"]}," in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly.yaml"]}," configuration"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"options","__idx":2},"children":["Options"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Option"},"children":["Option"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["metadata"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An object of key-value pairs."," ","Keys can be any string, and values can be any scalar value."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"examples","__idx":3},"children":["Examples"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"basic-metadata-configuration","__idx":4},"children":["Basic metadata configuration"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","data-title":"redocly.yaml","header":{"title":"redocly.yaml","controls":{"copy":{}}},"source":"metadata:\n  owner: Redocly\n  team: Documentation\n  department: Engineering\n  status: Published\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"api-specific-metadata","__idx":5},"children":["API-specific metadata"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can define metadata for specific APIs in your configuration:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","data-title":"redocly.yaml","header":{"title":"redocly.yaml","controls":{"copy":{}}},"source":"apis:\n  museum:\n    root: ./museum.yaml\n    type: openapi\n    metadata:\n      owner: API Team\n      category: eCommerce\n      status: Beta\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"use-the-x-metadata-extension-in-openapi-files","__idx":6},"children":["Use the x-metadata extension in OpenAPI files"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","data-title":"openapi.yaml","header":{"title":"openapi.yaml","controls":{"copy":{}}},"source":"openapi: 3.1.0\ninfo:\n  title: Museum API\n  description: A sample API for museum tickets\n  version: 1.0.0\n  x-metadata:\n    owner: API Team\n    department: Product\n    category: eCommerce\n    status: Production\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"use-metadata-in-markdown-front-matter","__idx":7},"children":["Use metadata in Markdown front matter"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","data-title":"introduction.md","header":{"title":"introduction.md","controls":{"copy":{}}},"source":"---\nmetadata:\n  owner: Documentation Team\n  category: Guides\n  status: Draft\n  redocly_category: Learn\n---\n\n# Introduction\n\nThis is an introduction to our API documentation.\n","lang":"markdown"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"use-metadataglobs-for-pattern-based-assignment","__idx":8},"children":["Use metadataGlobs for pattern-based assignment"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","data-title":"redocly.yaml","header":{"title":"redocly.yaml","controls":{"copy":{}}},"source":"metadataGlobs:\n  'apis/museum/**':\n    owner: Museum Team\n    redocly_category: API Reference\n  'guides/**':\n    redocly_category: Guides\n  '**':\n    company: Redocly\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"use-reserved-metadata-keys","__idx":9},"children":["Use reserved metadata keys"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Some metadata keys are reserved for specific functionality:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","data-title":"redocly.yaml","header":{"title":"redocly.yaml","controls":{"copy":{}}},"source":"metadata:\n  redocly_category: API Reference  # Used for search facets and categorization\n  team: API Team                   # Can be used for scorecard team attribution\n  owner: John Doe                  # Can be used for ownership attribution\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"catalog-categorization","__idx":10},"children":["Catalog categorization"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Catalogs are important tools to make APIs more discoverable."," ","At full potential, a catalog should include all of your APIs and be filterable across categories that users find useful."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"importance-of-categorization","__idx":11},"children":["Importance of categorization"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Despite its predominance in library systems, Amazon does not use the Dewey Decimal System to organize books."," ","The Dewey Decimal System assigns numerical codes based on subject matter and works well for physical libraries where users locate books on shelves."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Amazon, as an online retailer, uses a hierarchical categorization system that sorts books into categories and subcategories based on genre, subject matter, and other criteria."," ","This system allows users to easily browse and discover books by filtering through categories of interest or using search functions."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Dewey Decimal System serves physical libraries well."," ","Amazon's categorization system is better suited for digital environments where users can search and navigate through vast collections."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Similarly, Redocly has a flexible categorization system."," ","You can define metadata in APIs (using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-metadata"]},"), in Markdown front matter, or in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["metadata"]}," object of the configuration file."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"category-governance","__idx":12},"children":["Category governance"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Distributed category creation can lead to overlapping categories, or near-identical categories that result in confusing results."," ","Instead, categories should be created sparingly, and category values should also be created sparingly."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Self-categorization of data is important for scalability and must happen in a distributed way across teams."," ","You need a mechanism to enforce a limited number of categories and accepted values in a distributed fashion."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Redocly lint rules can enforce ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-metadata"]}," usage in APIs and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["metadata"]}," in configuration files using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["metadata-schema"]}," rule."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","data-title":"redocly.yaml","header":{"title":"redocly.yaml","controls":{"copy":{}}},"source":"rules:\n  metadata-schema:\n    type: object\n    properties:\n      team:\n        type: string\n        enum:\n          - Finance\n          - Operations  \n          - Marketing\n          - Product\n          - Engineering\n        description: Team responsible for the API.\n      category:\n        type: string\n        enum:\n          - Accounting\n          - Analytics\n          - Payments\n          - User Management\n        description: Business category for the API.\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This governance approach helps prevent inconsistencies like \"Managerial Accounting\" versus \"Management Accounting\" that can occur with distributed teams."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"reserved-metadata-keys","__idx":13},"children":["Reserved metadata keys"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["While most metadata keys can be used for any purpose, some have special functionality:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly_category"]},": Used for search facets and content categorization"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["team"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["owner"]},": Often used for attribution in scorecards and catalogs"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"resources","__idx":14},"children":["Resources"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/config/metadata-globs"},"children":["MetadataGlobs"]}]}," - Apply metadata using glob patterns for automated content organization and categorization"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/api-docs/openapi-extensions/x-metadata"},"children":["x-metadata extension"]}]}," - Add metadata to OpenAPI files for enhanced documentation and search functionality"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/config/catalog-classic"},"children":["Catalog classic"]}]}," - Configure classic catalog that uses metadata for filtering and organization of API documentation"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/config/scorecard-classic"},"children":["Scorecard"]}]}," - Configure classic scorecard that uses metadata for targeting specific content and quality assessment"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/config/search#apply-facets-to-files"},"children":["Configure search"]}]}," - Use metadata for search facets to enable advanced content filtering and discovery"]}]}]},"frontmatter":{"products":["Redoc","Revel","Reef","Realm"],"plans":["Pro","Enterprise","Enterprise+"],"description":"Configure metadata properties for your project, APIs, and documentation files."},"tagList":["configOptionRequirements","table"],"title":"metadata","lastModified":"2026-08-24T16:21:33.000Z"}