Skip to content
Last updated

JSON Example tag

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

Syntax and usage

To use the tag, pass either a value or schema attribute. Use value for literal JSON data or references to existing examples. Use schema to generate an example from a JSON schema definition.

With inline value:

{% json-example
  value={
    "name": "John Doe",
    "email": "john@example.com"
  }
/%}

With inline schema:

{% json-example
  schema={
    "type": "object",
    "properties": {
      "name": { "type": "string" },
      "email": { "type": "string", "format": "email" }
    }
  }
/%}

Attributes

AttributeTypeDescription
valueJSON object or arrayA literal JSON value or a $ref to an existing example. Takes precedence over schema if both are provided.
schemaJSON schema objectA JSON schema definition or a $ref to an existing schema. Used to generate an example value. Only used if value is not provided.
modestringControls property filtering when using schema. Use read to exclude writeOnly properties (for response examples). Use write to exclude readOnly properties (for request examples).

Examples

Inline value

Display a literal JSON value directly in your documentation:

Code:
{% json-example
  value={
    "id": 1,
    "name": "Museum Tour",
    "price": 25.00,
    "available": true
  }
/%}
Result:
{
  "id": 1,
  "name": "Museum Tour",
  "price": 25,
  "available": true
}

Referenced value

Reference an existing example from an OpenAPI description using $ref:

Code:
{% json-example
  value={
    "$ref": "../../openapi-files/redocly-museum.yaml#/components/examples/CreateSpecialEventRequestExample/value"
  }
/%}
Result:
{
  "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
}

Referenced JSON file

Reference any JSON file directly using $ref:

Code:
{% json-example
  value={
    "$ref": "../../openapi-files/json-example.json"
  }
/%}
Result:
{
  "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"
    ]
  }
}

With JSON pointer

Use a JSON pointer to display a specific part of a referenced JSON file:

Code:
{% json-example
  value={
    "$ref": "../../openapi-files/json-example.json#/value"
  }
/%}
Result:
{
  "id": 42,
  "username": "jdoe",
  "email": "jdoe@example.com",
  "isActive": true,
  "roles": [
    "admin",
    "editor"
  ]
}

Inline schema

Generate an example from an inline JSON schema definition:

Code:
{% json-example
  schema={
    "type": "object",
    "properties": {
      "eventId": { "type": "string", "format": "uuid" },
      "name": { "type": "string", "example": "Mermaid Treasure Hunt" },
      "dates": {
        "type": "array",
        "items": { "type": "string", "format": "date" }
      },
      "price": { "type": "number", "minimum": 0 }
    }
  }
/%}
Result:
{
  "eventId": "d6703cc8-9e79-415d-ac03-a4dc7f6ab43c",
  "name": "Mermaid Treasure Hunt",
  "dates": [
    "2019-08-24"
  ],
  "price": 0
}

Referenced schema

Generate an example from a schema defined in an OpenAPI description:

Code:
{% json-example
  schema={
    "$ref": "../../openapi-files/redocly-museum.yaml#/components/schemas/MuseumDailyHours"
  }
/%}
Result:
{
  "date": "2023-10-29",
  "timeOpen": "09:00",
  "timeClose": "18:00"
}

With read mode

Generate a response example that excludes writeOnly properties (like passwords):

Code:
{% json-example
  schema={
    "type": "object",
    "properties": {
      "id": { "type": "integer", "readOnly": true },
      "username": { "type": "string" },
      "password": { "type": "string", "writeOnly": true }
    }
  }
  mode="read"
/%}
Result:
{
  "id": 0,
  "username": "string"
}

With write mode

Generate a request example that excludes readOnly properties (like auto-generated IDs):

Code:
{% json-example
  schema={
    "type": "object",
    "properties": {
      "id": { "type": "integer", "readOnly": true },
      "username": { "type": "string" },
      "password": { "type": "string", "writeOnly": true }
    }
  }
  mode="write"
/%}
Result:
{
  "username": "string",
  "password": "string"
}

Array examples

Display or generate array examples:

Code:
{% json-example
  schema={
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "id": { "type": "integer" },
        "name": { "type": "string" }
      }
    },
    "minItems": 2
  }
/%}
Result:
[
  {
    "id": 0,
    "name": "string"
  },
  {
    "id": 0,
    "name": "string"
  }
]

Best practices

Use value for exact examples

When you need to display a specific, curated example (like in tutorials or guides), use the value attribute. This gives you full control over the displayed content.

Use schema for generated examples

When you want examples that stay in sync with your API schema definitions, use the schema attribute with a $ref. This ensures your documentation examples always match your API structure.

Use mode for request/response context

Use mode="write" when showing request body examples to hide server-generated fields like IDs. Use mode="read" when showing response examples to hide sensitive input fields like passwords.

Prefer references over inline definitions

When your examples or schemas are already defined in an OpenAPI description, use $ref to reference them. This keeps your documentation in sync with your API definition and reduces duplication.

Debug common issues

Example not rendering

If you're using schema, ensure the schema includes enough information to generate an example. The schema must include properties, items, allOf/anyOf/oneOf, or value keywords like example, enum, const, or default.

Empty object or array displayed

Schemas like { "type": "object" } without properties or { "type": "array" } without items produce empty results. Add property or item definitions to generate meaningful examples.

UI or console shows "Can't resolve $ref" error

The tag cannot access the reference that was passed in an attribute. Verify that the referenced example or schema exists and check the $ref value. The $ref value must include the filepath and pointer as a single string with a proper format (e.g., file.yaml#/path/to/item).

Both value and schema provided

If both value and schema are provided, value takes precedence and schema is ignored. Remove one of the attributes to avoid confusion.

Primitive schema provided

Schemas with primitive types like { "type": "string" } or { "type": "integer" } are not supported. The tag is designed for object and array examples. Wrap primitive values in an object or use value instead.

 
Next page