{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"json-example-tag","__idx":0},"children":["JSON Example 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-example"]}," tag renders JSON examples directly in your documentation, showing users sample data structures."," ","The tag can display a literal value, reference existing examples from OpenAPI descriptions, or generate examples from JSON 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 either a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["value"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["schema"]}," attribute."," ","Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["value"]}," for literal JSON data or references to existing examples."," ","Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["schema"]}," to generate an example from a JSON schema definition."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["With inline value:"]},{"$$mdtype":"Tag","name":"MarkdocExample","attributes":{"renderDemo":false,"language":"markdoc","demoContent":[{"$$mdtype":"Tag","name":"JsonExample","attributes":{"errors":[]},"children":[]}],"rawContent":"{% json-example\n  value={\n    \"name\": \"John Doe\",\n    \"email\": \"john@example.com\"\n  }\n/%}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["With inline schema:"]},{"$$mdtype":"Tag","name":"MarkdocExample","attributes":{"renderDemo":false,"language":"markdoc","demoContent":[{"$$mdtype":"Tag","name":"JsonExample","attributes":{"errors":[]},"children":[]}],"rawContent":"{% json-example\n  schema={\n    \"type\": \"object\",\n    \"properties\": {\n      \"name\": { \"type\": \"string\" },\n      \"email\": { \"type\": \"string\", \"format\": \"email\" }\n    }\n  }\n/%}\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"attributes","__idx":2},"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":["value"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["JSON object or array"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A literal JSON value or a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]}," to an existing example."," ","Takes precedence over ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["schema"]}," if both are provided."]}]},{"$$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":["A JSON schema definition or a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]}," to an existing schema."," ","Used to generate an example value."," ","Only used if ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["value"]}," is not provided."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["mode"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Controls property filtering when using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["schema"]},"."," ","Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["read"]}," to exclude ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["writeOnly"]}," properties (for response examples)."," ","Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["write"]}," to exclude ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["readOnly"]}," properties (for request examples)."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"examples","__idx":3},"children":["Examples"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"inline-value","__idx":4},"children":["Inline value"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Display a literal JSON value directly in your documentation:"]},{"$$mdtype":"Tag","name":"MarkdocExample","attributes":{"renderDemo":true,"title":null,"language":"markdoc","demoContent":[{"$$mdtype":"Tag","name":"JsonExample","attributes":{"json":{"id":1,"name":"Museum Tour","price":25,"available":true},"errors":[]},"children":[]}],"rawContent":"{% json-example\n  value={\n    \"id\": 1,\n    \"name\": \"Museum Tour\",\n    \"price\": 25.00,\n    \"available\": true\n  }\n/%}\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"referenced-value","__idx":5},"children":["Referenced value"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Reference an existing example from an OpenAPI description using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]},":"]},{"$$mdtype":"Tag","name":"MarkdocExample","attributes":{"renderDemo":true,"title":null,"language":"markdoc","demoContent":[{"$$mdtype":"Tag","name":"JsonExample","attributes":{"json":{"name":"Mermaid Treasure Identification and Analysis","location":"Under the seaaa 🦀 🎶 🌊.","eventDescription":"Join us as we review and classify a rare collection of 20 thingamabobs, gadgets, gizmos, whoosits, and whatsits, kindly donated by Ariel.","dates":["2023-09-05","2023-09-08"],"price":0},"errors":[]},"children":[]}],"rawContent":"{% json-example\n  value={\n    \"$ref\": \"../../openapi-files/redocly-museum.yaml#/components/examples/CreateSpecialEventRequestExample/value\"\n  }\n/%}\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"referenced-json-file","__idx":6},"children":["Referenced JSON file"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Reference any JSON file directly using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]},":"]},{"$$mdtype":"Tag","name":"MarkdocExample","attributes":{"renderDemo":true,"title":null,"language":"markdoc","demoContent":[{"$$mdtype":"Tag","name":"JsonExample","attributes":{"json":{"summary":"Example of a Standard User Object","description":"This demonstrates a typical structure for a User resource, suitable for both request and response bodies.","value":{"id":42,"username":"jdoe","email":"jdoe@example.com","isActive":true,"roles":["admin","editor"]}},"errors":[]},"children":[]}],"rawContent":"{% json-example\n  value={\n    \"$ref\": \"../../openapi-files/json-example.json\"\n  }\n/%}\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"with-json-pointer","__idx":7},"children":["With JSON pointer"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use a JSON pointer to display a specific part of a referenced JSON file:"]},{"$$mdtype":"Tag","name":"MarkdocExample","attributes":{"renderDemo":true,"title":null,"language":"markdoc","demoContent":[{"$$mdtype":"Tag","name":"JsonExample","attributes":{"json":{"id":42,"username":"jdoe","email":"jdoe@example.com","isActive":true,"roles":["admin","editor"]},"errors":[]},"children":[]}],"rawContent":"{% json-example\n  value={\n    \"$ref\": \"../../openapi-files/json-example.json#/value\"\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":["Generate an example from an inline JSON schema definition:"]},{"$$mdtype":"Tag","name":"MarkdocExample","attributes":{"renderDemo":true,"title":null,"language":"markdoc","demoContent":[{"$$mdtype":"Tag","name":"JsonExample","attributes":{"json":{"eventId":"d6703cc8-9e79-415d-ac03-a4dc7f6ab43c","name":"Mermaid Treasure Hunt","dates":["2019-08-24"],"price":0},"errors":[]},"children":[]}],"rawContent":"{% json-example\n  schema={\n    \"type\": \"object\",\n    \"properties\": {\n      \"eventId\": { \"type\": \"string\", \"format\": \"uuid\" },\n      \"name\": { \"type\": \"string\", \"example\": \"Mermaid Treasure Hunt\" },\n      \"dates\": {\n        \"type\": \"array\",\n        \"items\": { \"type\": \"string\", \"format\": \"date\" }\n      },\n      \"price\": { \"type\": \"number\", \"minimum\": 0 }\n    }\n  }\n/%}\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"referenced-schema","__idx":9},"children":["Referenced schema"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Generate an example from a schema defined in an OpenAPI description:"]},{"$$mdtype":"Tag","name":"MarkdocExample","attributes":{"renderDemo":true,"title":null,"language":"markdoc","demoContent":[{"$$mdtype":"Tag","name":"JsonExample","attributes":{"json":{"date":"2023-10-29","timeOpen":"09:00","timeClose":"18:00"},"errors":[]},"children":[]}],"rawContent":"{% json-example\n  schema={\n    \"$ref\": \"../../openapi-files/redocly-museum.yaml#/components/schemas/MuseumDailyHours\"\n  }\n/%}\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"with-read-mode","__idx":10},"children":["With read mode"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Generate a response example that excludes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["writeOnly"]}," properties (like passwords):"]},{"$$mdtype":"Tag","name":"MarkdocExample","attributes":{"renderDemo":true,"title":null,"language":"markdoc","demoContent":[{"$$mdtype":"Tag","name":"JsonExample","attributes":{"json":{"id":0,"username":"string"},"errors":[]},"children":[]}],"rawContent":"{% json-example\n  schema={\n    \"type\": \"object\",\n    \"properties\": {\n      \"id\": { \"type\": \"integer\", \"readOnly\": true },\n      \"username\": { \"type\": \"string\" },\n      \"password\": { \"type\": \"string\", \"writeOnly\": true }\n    }\n  }\n  mode=\"read\"\n/%}\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"with-write-mode","__idx":11},"children":["With write mode"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Generate a request example that excludes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["readOnly"]}," properties (like auto-generated IDs):"]},{"$$mdtype":"Tag","name":"MarkdocExample","attributes":{"renderDemo":true,"title":null,"language":"markdoc","demoContent":[{"$$mdtype":"Tag","name":"JsonExample","attributes":{"json":{"username":"string","password":"string"},"errors":[]},"children":[]}],"rawContent":"{% json-example\n  schema={\n    \"type\": \"object\",\n    \"properties\": {\n      \"id\": { \"type\": \"integer\", \"readOnly\": true },\n      \"username\": { \"type\": \"string\" },\n      \"password\": { \"type\": \"string\", \"writeOnly\": true }\n    }\n  }\n  mode=\"write\"\n/%}\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"array-examples","__idx":12},"children":["Array examples"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Display or generate array examples:"]},{"$$mdtype":"Tag","name":"MarkdocExample","attributes":{"renderDemo":true,"title":null,"language":"markdoc","demoContent":[{"$$mdtype":"Tag","name":"JsonExample","attributes":{"json":[{"id":0,"name":"string"},{"id":0,"name":"string"}],"errors":[]},"children":[]}],"rawContent":"{% json-example\n  schema={\n    \"type\": \"array\",\n    \"items\": {\n      \"type\": \"object\",\n      \"properties\": {\n        \"id\": { \"type\": \"integer\" },\n        \"name\": { \"type\": \"string\" }\n      }\n    },\n    \"minItems\": 2\n  }\n/%}\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"best-practices","__idx":13},"children":["Best practices"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["value"]}," for exact examples"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you need to display a specific, curated example (like in tutorials or guides), use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["value"]}," attribute."," ","This gives you full control over the displayed content."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["schema"]}," for generated examples"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you want examples that stay in sync with your API schema definitions, use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["schema"]}," attribute with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]},"."," ","This ensures your documentation examples always match your API structure."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Use mode for request/response context"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mode=\"write\""]}," when showing request body examples to hide server-generated fields like IDs."," ","Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mode=\"read\""]}," when showing response examples to hide sensitive input fields like passwords."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Prefer references over inline definitions"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When your examples or schemas are already defined in an OpenAPI description, use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]}," to reference them."," ","This keeps your documentation in sync with your API definition and reduces duplication."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"debug-common-issues","__idx":14},"children":["Debug common issues"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example not rendering"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you're using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["schema"]},", ensure the schema includes enough information to generate an example."," ","The schema must include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["properties"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["items"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allOf"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["anyOf"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["oneOf"]},", or value keywords like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["example"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["enum"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["const"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["default"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Empty object or array displayed"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Schemas like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ \"type\": \"object\" }"]}," without ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["properties"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ \"type\": \"array\" }"]}," without ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["items"]}," produce empty results."," ","Add property or item definitions to generate meaningful examples."]},{"$$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 referenced example or schema exists and 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 with a proper format (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["file.yaml#/path/to/item"]},")."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Both value and schema provided"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If both ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["value"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["schema"]}," are provided, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["value"]}," takes precedence and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["schema"]}," is ignored."," ","Remove one of the attributes to avoid confusion."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Primitive schema provided"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Schemas with primitive types like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ \"type\": \"string\" }"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ \"type\": \"integer\" }"]}," are not supported."," ","The tag is designed for object and array examples."," ","Wrap primitive values in an object or use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["value"]}," instead."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"resources","__idx":15},"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-example","markdoc-example","table"],"title":"JSON Example tag","lastModified":"2026-06-10T08:51:12.000Z"}