About

API documentation drifts from reality when schema definitions are manually transcribed into Markdown. A single mistyped type field or a forgotten required constraint propagates confusion across every consumer of your API. This tool parses JSON Schema structures - including nested properties objects, allOf compositions, and OpenAPI-style component schemas - and produces pipe-aligned Markdown tables suitable for GitHub READMEs, Wikis, or static site generators. It handles dot-notation flattening for objects nested up to 10 levels deep. The output is deterministic: identical input always yields identical Markdown. Note: this tool assumes well-formed JSON. Malformed input (trailing commas, single-quoted keys) is rejected with a specific error location.

Formulas

The conversion follows a deterministic pipeline. First, the JSON input is parsed and classified by format. Then, a recursive extractor walks the schema tree producing flat rows.

parse(input) → classify(tree) → extract(schema) → align(rows) → markdown

Column width alignment uses the maximum character count per column across all rows including the header:

w_col = max(len(header_col), max_{row ∈ rows}(len(cell_row,col)))

Nested property paths use dot-notation flattening:

path = parent ⋅ "." ⋅ child

Where input is the raw JSON string, tree is the parsed JavaScript object, schema is the classified schema structure, rows is the array of extracted table rows, w_col is the computed width for each column, and markdown is the final output string. Pipe characters (|) within cell values are escaped as \| to prevent table corruption.

Reference Data

Schema Format	Detection Key	Extracted Columns	Nesting Support
JSON Schema draft-04	properties + type: "object"	Property, Type, Description, Default, Required	Recursive dot-notation
JSON Schema draft-06/07	$schema keyword	Property, Type, Description, Default, Required, Examples	Recursive dot-notation
OpenAPI 3.x Component	components.schemas	Property, Type, Format, Description, Required, Enum	$ref resolution (local)
Array of Descriptors	Root is Array	All unique keys become columns	Flat only
Simple Key-Value	Root is Object, no "properties"	Key, Value, Type (inferred)	One level
TypeScript-like Interface	properties with enum	Property, Type, Enum Values, Description	Recursive dot-notation
Mongoose Schema	Values contain type as constructor name	Field, Type, Required, Default, Ref	Nested subdocuments
Joi-like Descriptor	type + flags	Field, Type, Presence, Default, Rules	Keys children
Sequelize Model	Values with DataTypes or type object	Column, Type, AllowNull, Default, PrimaryKey	Flat
Custom Tabular JSON	Array of uniform objects	Dynamic from keys	Flat
GraphQL-like Type	fields array	Field, Type, Nullable, Description	Nested types
Protobuf-like	fields with id	ID, Field, Type, Rule, Description	Nested messages

Frequently Asked Questions

Nested objects under properties are recursively traversed. Each nested property is represented using dot-notation (e.g., address.street). The recursion depth is capped at 10 levels to prevent infinite loops from circular references. If a $ref points to a local definition under definitions or $defs, it is resolved inline.

Pipe characters (|) are the column delimiter in Markdown tables. The converter automatically escapes them as \| in all cell values, ensuring the table structure remains intact. Newline characters within values are replaced with <br> tags for multi-line cell support in GitHub-flavored Markdown.

No. Markdown parsers ignore whitespace padding inside table cells. The alignment is purely cosmetic for raw-text readability. You can toggle alignment off if you prefer compact output. The functional result in rendered HTML is identical either way.

Yes. Paste the full component object or just the schema portion. The tool detects the components.schemas structure and iterates over each named schema, producing one table per schema object. Local $ref references within the same document are resolved. External $ref URLs are not fetched; they appear as the raw reference string in the Type column.

If the schema includes a required array at the object level (per JSON Schema spec), matching property names receive a Yes in the Required column. If no required array exists, the column is omitted entirely to keep the table concise. Some formats (Mongoose, Sequelize) embed required: true inside each field definition, which is also detected.

The parser reports the exact character position and line number where parsing failed. Common issues include trailing commas (not valid JSON), single-quoted strings, and unquoted keys. The tool suggests the specific fix. It does not attempt to auto-correct malformed JSON, as silent correction could mask data errors in schema documentation.