{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"json-schema-tag","__idx":0},"children":["JSON Schema tag"]},{"$$mdtype":"Tag","name":"ConfigOptionRequirements","attributes":{"products":["Revel","Reef","Realm"],"plans":["Pro","Enterprise","Enterprise+"]},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"syntax-and-usage","__idx":1},"children":["Syntax and usage"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To use the tag, pass the reference to your schema using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["schema"]}," attribute."," ","Render an existing schema from inside an OpenAPI description or other external file using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$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 ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#options-object"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["options"]}," attribute"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"render-existing-schemas","__idx":2},"children":["Render existing schemas"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Render an existing schema from inside an OpenAPI description or other external file using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]},", as in the following example:"]},{"$$mdtype":"Tag","name":"MarkdocExample","attributes":{"renderDemo":true,"title":null,"language":"markdoc","demoContent":[{"$$mdtype":"Tag","name":"JsonSchema","attributes":{"schema":{"$ref":"../../openapi-files/redocly-museum.yaml#/components/schemas/GetMuseumHoursResponse"},"options":{},"schemaResolved":{"openapi":"3.1.0","components":{"schemas":{"__root":{"$ref":"#/components/schemas/GetMuseumHoursResponse"},"Date":{"type":"string","format":"date","example":"2023-10-29"},"MuseumDailyHours":{"description":"Daily operating hours for the museum.","type":"object","properties":{"date":{"description":"Date the operating hours apply to.","$ref":"#/components/schemas/Date","example":"2024-12-31"},"timeOpen":{"type":"string","pattern":"^([01]\\d|2[0-3]):?([0-5]\\d)$","description":"Time the museum opens on a specific date. Uses 24 hour time format (`HH:mm`).","example":"09:00"},"timeClose":{"description":"Time the museum closes on a specific date. Uses 24 hour time format (`HH:mm`).","type":"string","pattern":"^([01]\\d|2[0-3]):?([0-5]\\d)$","example":"18:00"}},"required":["date","timeOpen","timeClose"]},"GetMuseumHoursResponse":{"description":"List of museum operating hours for consecutive days.","type":"array","items":{"$ref":"#/components/schemas/MuseumDailyHours"}}}}},"schemaResolvedErrors":[]},"children":[]}],"rawContent":"{% json-schema\nschema={\n  \"$ref\": \"../../openapi-files/redocly-museum.yaml#/components/schemas/GetMuseumHoursResponse\"\n}\n/%}\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"render-schemas-defined-inline","__idx":3},"children":["Render schemas defined inline"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Define a schema directly inside the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["schema"]}," attribute (aka \"inline\"), as in the following example:"]},{"$$mdtype":"Tag","name":"MarkdocExample","attributes":{"renderDemo":true,"title":null,"language":"markdoc","demoContent":[{"$$mdtype":"Tag","name":"JsonSchema","attributes":{"schema":{"type":"object","title":"Oatmeal","properties":{"weight":{"type":"number","description":"Weight in grams."}}},"options":{},"schemaResolved":{"openapi":"3.1.0","components":{"schemas":{"__root":{"type":"object","title":"Oatmeal","properties":{"weight":{"type":"number","description":"Weight in grams."}}}}}},"schemaResolvedErrors":[]},"children":[]}],"rawContent":"{% json-schema\n  schema={\n    \"type\": \"object\",\n    \"title\": \"Oatmeal\",\n    \"properties\": {\n      \"weight\": {\n        \"type\": \"number\",\n        \"description\": \"Weight in grams.\"\n      }\n    }\n  }\n/%}\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"attributes","__idx":4},"children":["Attributes"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Attribute"},"children":["Attribute"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["schema"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["JSON schema object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED."]}," ","A reference to or an inline JSON schema to render."," ","The schema can be defined inline or pulled from another file using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]},"."," ","Only local files are supported."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["title"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An optional heading displayed above the rendered schema block."," ","This tag attribute is separate from a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["title"]}," property inside the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["schema"]}," object, which appears within the schema UI next to the type."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["options"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#options-object"},"children":["Options object"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Options for modifying how the JSON schema is displayed."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"options-object","__idx":5},"children":["Options object"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["options"]}," attribute is used to modify the behavior and appearance of the rendered schema, as in the following example:"]},{"$$mdtype":"Tag","name":"MarkdocExample","attributes":{"renderDemo":true,"title":null,"language":"markdoc","demoContent":[{"$$mdtype":"Tag","name":"JsonSchema","attributes":{"schema":{"$ref":"../../openapi-files/redocly-museum.yaml#/components/schemas/GetMuseumHoursResponse"},"options":{"hideSchemaTitles":true},"schemaResolved":{"openapi":"3.1.0","components":{"schemas":{"__root":{"$ref":"#/components/schemas/GetMuseumHoursResponse"},"Date":{"type":"string","format":"date","example":"2023-10-29"},"MuseumDailyHours":{"description":"Daily operating hours for the museum.","type":"object","properties":{"date":{"description":"Date the operating hours apply to.","$ref":"#/components/schemas/Date","example":"2024-12-31"},"timeOpen":{"type":"string","pattern":"^([01]\\d|2[0-3]):?([0-5]\\d)$","description":"Time the museum opens on a specific date. Uses 24 hour time format (`HH:mm`).","example":"09:00"},"timeClose":{"description":"Time the museum closes on a specific date. Uses 24 hour time format (`HH:mm`).","type":"string","pattern":"^([01]\\d|2[0-3]):?([0-5]\\d)$","example":"18:00"}},"required":["date","timeOpen","timeClose"]},"GetMuseumHoursResponse":{"description":"List of museum operating hours for consecutive days.","type":"array","items":{"$ref":"#/components/schemas/MuseumDailyHours"}}}}},"schemaResolvedErrors":[]},"children":[]}],"rawContent":"{% json-schema\n  schema={\n    \"$ref\": \"../../openapi-files/redocly-museum.yaml#/components/schemas/GetMuseumHoursResponse\"\n  }\n  options={\n    \"hideSchemaTitles\": true\n  }\n/%}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following options work with the JSON schema tag:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Option"},"children":["Option"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["hideSchemaPattern"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["If ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},", the pattern is not shown in the schema."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["hideSchemaTitles"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["If ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},", hides the schema title next to the type."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["maxDisplayedEnumValues"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["number"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Displays a specified number of enum values and hides remaining values behind an expandable element."," ","All values are displayed by default."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["requiredPropsFirst"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["If ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},", shows required properties in schemas first, ordered in the same order as in required array."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"examples","__idx":6},"children":["Examples"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"from-an-openapi-description","__idx":7},"children":["From an OpenAPI description"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The example below uses a reference to a JSON schema that is already defined within an OpenAPI description."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example json-schema syntax:"]}," (OpenAPI description)"]},{"$$mdtype":"Tag","name":"MarkdocExample","attributes":{"renderDemo":true,"title":null,"language":"markdoc","demoContent":[{"$$mdtype":"Tag","name":"JsonSchema","attributes":{"schema":{"$ref":"../../openapi-files/redocly-museum.yaml#/components/schemas/GetMuseumHoursResponse"},"options":{},"schemaResolved":{"openapi":"3.1.0","components":{"schemas":{"__root":{"$ref":"#/components/schemas/GetMuseumHoursResponse"},"Date":{"type":"string","format":"date","example":"2023-10-29"},"MuseumDailyHours":{"description":"Daily operating hours for the museum.","type":"object","properties":{"date":{"description":"Date the operating hours apply to.","$ref":"#/components/schemas/Date","example":"2024-12-31"},"timeOpen":{"type":"string","pattern":"^([01]\\d|2[0-3]):?([0-5]\\d)$","description":"Time the museum opens on a specific date. Uses 24 hour time format (`HH:mm`).","example":"09:00"},"timeClose":{"description":"Time the museum closes on a specific date. Uses 24 hour time format (`HH:mm`).","type":"string","pattern":"^([01]\\d|2[0-3]):?([0-5]\\d)$","example":"18:00"}},"required":["date","timeOpen","timeClose"]},"GetMuseumHoursResponse":{"description":"List of museum operating hours for consecutive days.","type":"array","items":{"$ref":"#/components/schemas/MuseumDailyHours"}}}}},"schemaResolvedErrors":[]},"children":[]}],"rawContent":"{% json-schema\n  schema={\n    \"$ref\": \"../../openapi-files/redocly-museum.yaml#/components/schemas/GetMuseumHoursResponse\"\n  }\n/%}\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"inline-schema","__idx":8},"children":["Inline schema"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example uses an \"inline\" schema, where the JSON schema is defined directly on the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["schema"]}," attribute as part of the tag:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example json-schema syntax:"]}," (inline schema)"]},{"$$mdtype":"Tag","name":"MarkdocExample","attributes":{"renderDemo":true,"title":null,"language":"markdoc","demoContent":[{"$$mdtype":"Tag","name":"JsonSchema","attributes":{"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."}}},"options":{},"schemaResolved":{"openapi":"3.1.0","components":{"schemas":{"__root":{"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."}}}}}},"schemaResolvedErrors":[]},"children":[]}],"rawContent":"{% json-schema\n  schema={\n    \"title\": \"Artifact\",\n    \"type\": \"object\",\n    \"properties\": {\n      \"artifactId\": {\n        \"type\": \"string\",\n        \"description\": \"Unique artifact identifier.\"\n      },\n      \"name\": {\n        \"type\": \"string\",\n        \"description\": \"Name of the artifact.\"\n      },\n      \"yearCreated\": {\n        \"type\": \"integer\",\n        \"description\": \"Approximate year the artifact comes from.\",\n      }\n    }\n  }\n/%}\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"best-practices","__idx":9},"children":["Best practices"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Validate schemas before use"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Validating your schema ensures it adheres to standards and is compatible with the JSON schema tag."," ","For OpenAPI descriptions, Redocly recommends validating with the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://redocly.com/docs/cli/"},"children":["Redocly CLI"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Keep schemas organized"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Organized schemas are easier to find and manage, which improves maintainability and reduces errors (especially on larger teams)."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["For OpenAPI descriptions, use descriptive schema names and structure."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["For external schema files, use a clear directory structure and file names."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"debug-common-issues","__idx":10},"children":["Debug common issues"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Changes to schema not reflected in UI"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You might run the development server locally."," ","In that case, restart the project after making changes to a schema in an OpenAPI description or external file."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Schema not rendering"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["UI or console shows \"Can't resolve $ref\" error"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The tag cannot access the reference that was passed in an attribute."," ","Verify that the pre-defined schema exists and then check the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]}," value."," ","The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ref"]}," value must include the filepath and pointer as a single string."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"resources","__idx":11},"children":["Resources"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://redocly.com/learn/markdoc"},"children":["Markdoc overview for technical writers"]}]}," - Learn how to use Markdoc in your documentation"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/markdoc-tags"},"children":["Markdoc tags"]}]}," - See the full list of supported Markdoc tags"]}]}]},"frontmatter":{"products":["Revel","Reef","Realm"],"plans":["Pro","Enterprise","Enterprise+"]},"tagList":["configOptionRequirements","json-schema","markdoc-example","table"],"title":"JSON Schema tag","lastModified":"2026-08-24T16:21:33.000Z"}