Last updated

JSON Schema Tag Redocly Custom Tag

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

Array
eventId
required
string <uuid> (EventId)

Identifier for a special event.

name
required
string (EventName)

Name of the special event

location
required
string (EventLocation)

Location where the special event is held

eventDescription
required
string (EventDescription)

Description of the special event

dates
required
Array of strings <date> (EventDates)

List of planned dates for the special event

price
required
number <float> (EventPrice)

Price of a ticket for the special event

Syntax and usage

Use the tag's attributes to pass a pointer to a schema or inline schema. Optionally include an options attribute to modify the schema based on configuration options.

The attributes you use depend on the type of schema you want to render.

ticketType
required
string

Type of ticket being purchased. Use general for regular museum entry and event for tickets to special events.

Enum: "event" "general"
eventId
string <uuid>

Identifier for a special event.

ticketDate
required
string <date>

Date that the ticket is valid for.

email
required
string <email>

Email address for ticket purchaser.

phone
string

Phone number for the ticket purchaser (optional).

{% json-schema
  openApiFilePath="../../openapi/museum-api.yaml"
  pointer="#/components/schemas/BuyMuseumTicketsRequest"
  options={
    hideSchemaTitles: true
  }
/%}

Schema types

The tag needs schema data to work correctly. Consider your approach to maintaining schemas, then use the attributes that correspond with that type of schema.

  • Schema defined in an OpenAPI description
    • Use openApiFilePath to pass the file's location
    • Use pointer to reference a specific schema
  • Inline schema defined in tag
    • Define your schema inside the schema attribute in the JSON schema tag
  • Schema defined in external file
    • Use schemaFilePath to pass the file's location

Defining your schemas in an OpenAPI description creates a single source of truth and improves your developer experience.

Attributes

The JSON schema tag needs one source data, which means it requires either openApiFilePath, schema, or schemaFilePath.

AttributeTypeDescription
openApiFilePathStringPath to an OpenAPI definition. Must be used with pointer.
pointerStringReference to a specific schema inside the OpenAPI definition passed in openApiFilePath.
optionsObjectModifies how the JSON schema is displayed from configuration options.
schemaObjectAn inline JSON schema defined in the tag. Useful for one-off examples and schemas.
schemaFilePathStringPath to a JSON schema defined in an external, non-OpenAPI file. Only works with local files.

Configuration options

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

{% json-schema
  openApiFilePath="../../openapi/museum-api.yaml"
  pointer="#/components/schemas/BuyMuseumTicketsRequest"
  options={
    hideSchemaTitles: true
  }
/%}

The following configurations work with the JSON schema tag:

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

Examples

Using an OpenAPI schema

Array
date
required
string <date> (Date)

Date the operating hours apply to.

timeOpen
required
string^([01]\d|2[0-3]):?([0-5]\d)$

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

timeClose
required
string^([01]\d|2[0-3]):?([0-5]\d)$

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

{% json-schema
  openApiFilePath="../../openapi/museum-api.yaml"
  pointer="#/components/schemas/GetMuseumHoursResponse"
/%}

Using a schema from an external file

objectId
string

Unique identifier for the object.

objectName
string

The object's name

objectType
object

The type of object at the museum.

Enum: "Painting" "Ceramics" "Sculpture" "Textiles" "Fossil" "Document"
{% json-schema
  schemaFilePath="external-schema.json"
  options={
    requiredPropsFirst: true
  }
/%}

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.

Troubleshooting

Changes to schema not reflected in UI
After making changes to a schema in an OpenAPI description or external file, you'll need to restart the project for that data to be pulled in.

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 shows "Incorrect OpenAPI file path"
The JSON schema tag cannot access the file that was passed in an attribute. Double-check the file's location and the path defined in the attribute.