# JSON Schema Tag [](/learn/markdoc/tags/tag-library#redocly-tag-badge)

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](#options-object).


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

### Render existing schemas

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


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

### Render schemas defined inline

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


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

## Attributes

| Attribute | Type | Description |
|  --- | --- | --- |
| schema | JSON schema object | **REQUIRED.**
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. |
| options | [Options object](#options-object) | Options 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:


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

The following configurations work with the JSON schema tag:

| Option | Type | Description |
|  --- | --- | --- |
| hideSchemaPattern | Boolean | If `true`, the pattern is not shown in the schema. |
| hideSchemaTitles | Boolean | If `true`, hides the schema title next to the type. |
| maxDisplayedEnumValues | Number | Displays a specified number of enum values and hides remaining values behind an expandable element.
All values are displayed by default. |
| requiredPropsFirst | Boolean | If `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)


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

### 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)


```markdoc
{% 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.",
      }
    }
  }
/%}
```

## 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](https://redocly.com/docs/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.