JSON Schema to Markdown

one table per object · follows $ref · constraints, defaults, examples · updated 25 August 2026

A JSON Schema is already the specification — what it is not is readable. This walks the schema and emits Markdown: a section per object, a table row per field, with its type, whether it is required, every constraint that applies, the default and the description. $ref pointers inside the document are followed, so a $defs-heavy schema comes out as a set of linked sections rather than a maze of pointers you have to hold in your head.

How to document a schema

1. Paste the schema, or drop a .json file onto the left pane.
2. Pick the top heading level to match where the output is going — ## for a section inside an existing README, # for a standalone page.
3. Turn off the Constraints and Default columns for a narrow table that reads well on a docs site; leave them on for a reference page that has to be complete.
4. Copy the Markdown into your README, wiki or docs generator. The anchors are GitHub-style slugs, so the cross-links between sections work as-is on GitHub, GitLab and most static site generators.

What ends up in each column

• Type — the declared type, or what the schema implies: array of X for an items schema, a link for a $ref or a nested object, and A | B for oneOf and anyOf. allOf joins with +, because that is what it means.
• Required — read from the enclosing object's required array, not from the field. This is the distinction schemas get wrong most often: required lives on the parent, so moving a property between objects silently changes whether it is mandatory.
• Constraints — every bound in one cell: minimum, maximum, the exclusive variants, multipleOf, lengths, item and property counts, pattern, format, uniqueItems, enum values, const, and additionalProperties: false. readOnly, writeOnly and deprecated show up here too.
• Default — the literal default, JSON-encoded, so "" and null are distinguishable from an absent default.
• Description — description, falling back to title, with the first entry from examples appended when that option is on.

How $ref is handled

A pointer into the same document — #/$defs/Profile, #/definitions/Address, or any other JSON Pointer — is resolved and rendered as its own section, with the field's Type cell linking to it. That is what keeps the output readable: expanding every reference inline duplicates the same table wherever a type is reused, and a recursive schema (a comment with replies, a tree node) would never terminate.

A $ref that points outside the document cannot be resolved here, and rather than rendering it as an empty object the pointer is printed literally and counted in the status line. Run the schema through Bundle $refs first to inline the external ones, then come back.

Definitions that nothing references are still part of the contract, so they are emitted at the end marked (unreferenced). If your $defs block is a shared library and most of it is irrelevant to this document, tick Skip unreferenced $defs.

Markdown table escaping

A pipe character ends a table cell and a newline ends the row, so a description containing either would silently break the table. Both are neutralised: pipes are backslash-escaped and newlines collapse to spaces. A multi-paragraph description therefore becomes one long line, which is the price of putting it in a table at all — if your descriptions are prose, generate the docs with the constraint columns off so there is room for them.

FAQ

Related JSON tools