Display schemas separately from operations


One concern that our users have is that they are missing a "data dictionary" for our API objects. For example, in our old API reference documentation, we have a section that I can link to that provides the values and descriptions for an object. Is there a way to configure Redocly to present object value/definition information more directly? I know I can browse down into the body parameter and response definitions for each endpoint.


The "data dictionary" refers to schemas in OpenAPI.

People have asked about this feature fairly often over the years. The implementation in our product is quite raw and dates back a few years. It's hard to use and tedious if you want to display multiple schemas or organize them neatly.

<SchemaDefinition schemaRef="#/components/schemas/Planet" />

This could be added to any tag or info description and the corresponding schema would display. This is fine if you want to render one schema in a one-off way. However, this approach isn't good if you want to display your entire data dictionary.

So how could Redocly improve this further?


Two divergent approaches seemed valuable to implement:

  • Display all of the schemas in a sidebar group.
  • Display schemas grouped with their operations (like how Stripe does it).

All schemas grouped together

Use the feature schemaDefinitionsTagName to group all of the schemas together. They display with a tag name that appears in the sidebar.

This is a configuration setting to place into your Redocly configuration file:


    schemaDefinitionsTagName: Schemas

all schemas together

Schemas grouped with operations

Use x-tags specification extension to tag specific schemas with the tag names that should appear in the sidebar. You can have a single schema appear multiple times.

        - Listing ingredients
        - Adding ingredients

schema with operations

schema grouped with operations

It's important to note that these features shipped in the Developer portal 1.1.0-beta.95. If you're using a prior version, update it to take advantage of this feature.


Schemas don't need to be displayed outside of operations' request or response descriptions very often. In case they do, Redocly offers two main options for that:

  • display all of the schemas together using schemaDefinitionsTagName; or
  • tag specific schemas to display alongside operations with x-tags.

If you found this helpful, please share it on social media and let us know (tag @Redocly).

Latest from our blog

Tips for Documentation Migration

Make your documentation migration a huge success with these practical tips on planning, collaboration, and quality checks.

Git branching strategies for documentati...

Docs-as-code workflows need solid branching strategies. This article helps you pick the right one.

YAML basics for Technical Writers

YAML is a data format, used in many documentation tools. Learn all you need to work effectively with YAML.