Last updated

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

To use the tag, pass the reference to your schema using the schema attribute. 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. Optionally, modify how the schema renders using the options attribute.

Code:
{% json-schema
  schema={
    "$ref": "../../../demo/openapi/museum-api.yaml#/components/schemas/GetMuseumHoursResponse"
  }
/%}
Result:
Array [
datestring(date)(Date)required
Example: "2023-10-29"
timeOpenstring^([01]\d|2[0-3]):?([0-5]\d)$required

Time the museum opens on a specific date. Uses 24 hour time format (HH:mm).

Example: "09:00"
timeClosestring^([01]\d|2[0-3]):?([0-5]\d)$required

Time the museum closes on a specific date. Uses 24 hour time format (HH:mm).

Example: "18:00"
]

Render existing schemas

Render an existing schema from inside an OpenAPI description or other external file using $ref, as in the following example:

Code:
{% json-schema
  schema={
    "$ref": "../../../demo/openapi/museum-api.yaml#/components/schemas/GetMuseumHoursResponse"
  }
/%}
Result:
Array [
datestring(date)(Date)required
Example: "2023-10-29"
timeOpenstring^([01]\d|2[0-3]):?([0-5]\d)$required

Time the museum opens on a specific date. Uses 24 hour time format (HH:mm).

Example: "09:00"
timeClosestring^([01]\d|2[0-3]):?([0-5]\d)$required

Time the museum closes on a specific date. Uses 24 hour time format (HH:mm).

Example: "18:00"
]

Render schemas defined inline

Define a schema directly inside the schema attribute (aka "inline"), as in the following example:

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

Weight in grams.

Attributes

AttributeTypeDescription
schemaJSON schema objectREQUIRED. A reference to or an inline JSON schema to render. The schema can be defined inline or pulled from another file using $ref. Only local files are supported.
optionsOptions objectOptions for modifying how the JSON schema is displayed.

Options object

The options attribute is used to modify the behavior and appearance of the rendered schema, as in the following example:

Code:
{% json-schema
  schema={
    "$ref": "../../../demo/openapi/museum-api.yaml#/components/schemas/GetMuseumHoursResponse"
  }
  options={
    "hideSchemaTitles": true
  }
/%}
Result:
Array [
datestring(date)required
Example: "2023-10-29"
timeOpenstring^([01]\d|2[0-3]):?([0-5]\d)$required

Time the museum opens on a specific date. Uses 24 hour time format (HH:mm).

Example: "09:00"
timeClosestring^([01]\d|2[0-3]):?([0-5]\d)$required

Time the museum closes on a specific date. Uses 24 hour time format (HH:mm).

Example: "18:00"
]

The following configurations work with the JSON schema tag:

OptionTypeDescription
hideSchemaPatternBooleanIf true, the pattern is not shown in the schema.
hideSchemaTitlesBooleanIf true, hides the schema title next to the type.
maxDisplayedEnumValuesNumberDisplays a specified number of enum values and hides remaining values behind an expandable element. All values are displayed by default.
requiredPropsFirstBooleanIf true, shows required properties in schemas first, ordered in the same order as in required array.

Examples

From an OpenAPI description

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

Example json-schema syntax: (OpenAPI description)

Code:
{% json-schema
  schema={
    "$ref": "../../../demo/openapi/museum-api.yaml#/components/schemas/GetMuseumHoursResponse"
  }
/%}
Result:
Array [
datestring(date)(Date)required
Example: "2023-10-29"
timeOpenstring^([01]\d|2[0-3]):?([0-5]\d)$required

Time the museum opens on a specific date. Uses 24 hour time format (HH:mm).

Example: "09:00"
timeClosestring^([01]\d|2[0-3]):?([0-5]\d)$required

Time the museum closes on a specific date. Uses 24 hour time format (HH:mm).

Example: "18:00"
]

Inline schema

The following example 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)

Code:
{% 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.",
      }
    }
  }
/%}
Result:
artifactIdstring

Unique artifact identifier.

namestring

Name of the artifact.

yearCreatedinteger

Approximate year the artifact comes from.

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 issue can be caused by problems in the schema format. The JSON schema tag is designed to display a schema, but doesn't validate. 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. The ref value must include the filepath and pointer as a single string.

 
Next page