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.

Array [
eventIdstring(uuid)(EventId)required

Identifier for a special event.

Example: "3be6453c-03eb-4357-ae5a-984a0e574a54"
namestring(EventName)required

Name of the special event.

Example: "Pirate Coding Workshop"
locationstring(EventLocation)required

Location where the special event is held.

Example: "Computer Room"
eventDescriptionstring(EventDescription)required

Description of the special event.

Example: "Captain Blackbeard shares his love of the C...language. And possibly Arrrrr (R lang)."
datesArray of strings(date)(EventDates)required

List of planned dates for the special event.

Example: ["2023-10-29"]
pricenumber(float)(EventPrice)required

Price of a ticket for the special event.

Example: 25
]

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": "../../../demo/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

AttributeTypeDescription
schemaJSON schema objectREQUIRED. A JSON schema to render in the tag. The schema can be defined inline or pulled from another file using $ref. Only local files are supported.
optionsObjectModifies how the JSON schema is displayed from configuration options.

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:

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

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": "../../../demo/openapi/museum-api.yaml#/components/schemas/ListSpecialEventsResponse"
  }
/%}

Example json-schema element: (OpenAPI description)

Array [
eventIdstring(uuid)(EventId)required

Identifier for a special event.

Example: "3be6453c-03eb-4357-ae5a-984a0e574a54"
namestring(EventName)required

Name of the special event.

Example: "Pirate Coding Workshop"
locationstring(EventLocation)required

Location where the special event is held.

Example: "Computer Room"
eventDescriptionstring(EventDescription)required

Description of the special event.

Example: "Captain Blackbeard shares his love of the C...language. And possibly Arrrrr (R lang)."
datesArray of strings(date)(EventDates)required

List of planned dates for the special event.

Example: ["2023-10-29"]
pricenumber(float)(EventPrice)required

Price of a ticket for the special event.

Example: 25
]

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)

any

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)

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 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.