JSON Schema Tag Redocly Custom Tag

The json-schema tag renders schemas inside a pre-styled element optimized for readability and layout. The tag can reference existing schemas, like OpenAPI descriptions or external files, but also accepts inline schemas.

Syntax and usage

Use the schema attribute to pass data to the tag. This method works with pre-defined schemas or inline schemas. Optionally, modify how the schema renders using configuration options in the options attribute.

Existing schemas

Render an existing schema from inside an OpenAPI description or other external file using $ref. To reference a specific part of the schema, pass a string that contains both the filepath and pointer.

{% json-schema
  schema={
    "$ref": "../../openapi/museum-api.yaml#/components/schemas/BuyMuseumTicketsRequest"
  }
/%}

Schemas defined inline

Define a schema directly inside the schema attribute (aka "inline").

{% json-schema
  schema={
    "type": "object",
    "title": "Oatmeal",
    "properties": {
      "weight": {
        "type": "number",
        "description": "Weight in grams."
      }
    }
  }
/%}

Attributes

Configuration options

The options attribute is used to modify the behavior and appearance of the rendered schema.

{% json-schema
  schema={
    "$ref": "../../openapi/museum-api.yaml#/components/schemas/ListSpecialEventsResponse"
  }
  options={
    hideSchemaTitles: true
  }
/%}

The following configurations work with the JSON schema tag:

Examples

From an OpenAPI description

The example below uses a reference to a JSON schema that is already defined within an OpenAPI description.

Example json-schema syntax: (OpenAPI description)

{% json-schema
  schema={
    "$ref": "../../openapi/museum-api.yaml#/components/schemas/ListSpecialEventsResponse"
  }
/%}

Example json-schema element: (OpenAPI description)

From an external file

The example below uses a reference to a pre-existing JSON schema defined in an external file.

Example json-schema syntax: (external file)

{% json-schema
  schemaFilePath="external-schema.json"
  options={
    requiredPropsFirst: true
  }
/%}

Example json-schema element: (external file)

Inline schema

The example below uses an "inline" schema, where the JSON schema is defined directly on the schema attribute as part of the tag.

Example json-schema syntax: (inline schema)

{% json-schema
  schema={
    "title": "Artifact",
    "type": "object",
    "properties": {
      "artifactId": {
        "type": "string",
        "description": "Unique artifact identifier."
      },
      "name": {
        "type": "string",
        "description": "Name of the artifact."
      },
      "yearCreated": {
        "type": "integer",
        "description": "Approximate year the artifact comes from.",
      }
    }
  }
/%}

Example json-schema element: (inline schema)

Best practices

Validate schemas before use

Validating your schema ensures it adheres to standards and plays nicely with the JSON schema tag. For OpenAPI descriptions, we recommend validating with the Redocly CLI.

Keep schemas organized

Organized schemas are easier to find and manage, which improves maintainability and reduces errors (especially on larger teams).

• OpenAPI descriptions should use descriptive schema names and structure.
• External schema files should use a clear directory structure and file names.

Debug common issues

Changes to schema not reflected in UI

If you're running the development server locally, you'll need to restart the project after making changes to a schema in an OpenAPI description or external file.

Schema not rendering

This can be caused by issues in schema format. The JSON schema tag is designed to display a schema, but doesn't validate. You should validate your schema to ensure the format is correct.

UI or console shows "Can't resolve $ref" error

The tag cannot access the reference that was passed in an attribute. Verify that the pre-defined schema exists and then check the $ref value. It should include the filepath and pointer as a single string.