From records to a readable table
JSON is how data arrives from APIs, logs and test runs, but a wall of braces is hard to review in a pull request or an incident report. A Markdown table shows the same records as rows that GitHub, GitLab, Bitbucket, Jira, Obsidian, Notion and most static-site generators render nicely. The output follows GitHub Flavored Markdown (GFM) table syntax and is padded so it also lines up as plain text, with CJK characters and emoji measured at their visual width.
If your data is already CSV, use CSV to Markdown table; both converters share the same table writer.
Which shapes work
- An array of objects is the usual case: each object is a row. Columns are the union of all keys in the order they are first seen, so a key that only appears in the tenth record still gets a column, and rows without it get an empty cell.
- A single object becomes a one-row table.
- An array of plain values such as
[3, 5, 8]becomes a singlevaluecolumn. - An array of arrays becomes columns named
column_1,column_2… since there are no keys.
Mixing shapes, such as an object next to a number in the same array, is reported as an error at the item that breaks the pattern.
Nested values
With Flatten nested objects on (the default), {"user": {"name": "Ada", "team": {"id": 7}}} produces the columns user.name and user.team.id. Arrays are not spread over columns, because their length differs from row to row; they appear as inline JSON in a code span, for example ["admin","beta"] wrapped in backticks.
Turn flattening off to keep each top-level field in one column, with nested objects written as compact inline JSON code. That keeps wide documents to a manageable number of columns. If a value itself contains backticks, a longer backtick fence is used so the code span still closes correctly.
Alignment and escaping
Alignment controls the delimiter row. Auto right-aligns columns whose values are all JSON numbers (--:), which keeps digits lined up, and leaves text columns at the renderer’s default. Left, Center and Right force one alignment for every column with :--, :-: or --:.
Text is escaped so no value can break the table: | becomes \|, a backslash becomes \\, and line breaks become <br> because a table row must stay on one line. Numbers are written with their original spelling, so 1.50 does not turn into 1.5. Booleans appear as true and false.
Markdown has no notion of null, so null, a missing key and an empty string all render as an empty cell. If that distinction matters, keep the JSON next to the table or convert with JSON to CSV for a spreadsheet instead.
Examples
Benchmark results for a README
The numeric columns are right-aligned, the pipe inside a note is escaped, and the missing note for json-std is an empty cell.
[
{ "library": "fast-json", "ops_per_sec": 182340, "p99_ms": 0.42, "notes": "SIMD | AVX2" },
{ "library": "json-std", "ops_per_sec": 91210, "p99_ms": 1.10 },
{ "library": "tiny-json", "ops_per_sec": 45880, "p99_ms": 2.75, "notes": "no deps" }
]| library | ops_per_sec | p99_ms | notes |
| --------- | ----------: | -----: | ------------ |
| fast-json | 182340 | 0.42 | SIMD \| AVX2 |
| json-std | 91210 | 1.10 | |
| tiny-json | 45880 | 2.75 | no deps |
Nested API records, flattened
service.name and service.region become their own columns, while the tags arrays stay inline as JSON code.
[
{ "id": "inc-311", "service": { "name": "checkout", "region": "eu-west-1" }, "severity": 2, "tags": ["payments"] },
{ "id": "inc-312", "service": { "name": "search", "region": "us-east-1" }, "severity": 3, "tags": [] }
]| id | service.name | service.region | severity | tags |
| ------- | ------------ | -------------- | -------: | -------------- |
| inc-311 | checkout | eu-west-1 | 2 | `["payments"]` |
| inc-312 | search | us-east-1 | 3 | `[]` |
Centered, without flattening
Each nested rules object stays in a single column as inline JSON, and every column is centered.
[
{ "flag": "new-checkout", "enabled": true, "rules": { "country": ["SG", "MY"] } },
{ "flag": "dark-mode", "enabled": false, "rules": {} }
]| flag | enabled | rules |
| :----------: | :-----: | :-----------------------: |
| new-checkout | true | `{"country":["SG","MY"]}` |
| dark-mode | false | `{}` |
Common errors and how to fix them
| Error | Cause | Fix |
|---|---|---|
Expected every row to be an object, but found a number | The array mixes objects with plain values, so there is no consistent set of columns. | Make every item an object, or wrap the plain values as {“value”: …}. |
Expected an array of rows or an object, but the JSON is a string | The input is a single JSON value rather than records. | Paste the array or object that holds the records. |
The array is empty, so there are no rows to put in a table | The input is [] — perhaps a filtered API response that matched nothing. | Check the source data; an empty table cannot be written without at least one row. |
Trailing comma before '}'Explained | The JSON itself is invalid: a comma follows the last property, as often happens after hand-editing. | Remove the comma on the reported line, or run the input through the JSON validator first. |
Frequently asked questions
Will the table render on GitHub?
Yes. The output is standard GitHub Flavored Markdown table syntax, which GitHub, GitLab and most Markdown renderers support.
How are columns ordered?
In the order keys first appear across the records. Turn on Sort keys in the toolbar of the JSON formatter first if you want them alphabetical.
Why does a column show JSON in backticks?
That value is an array, or an object while flattening is off. Markdown cells hold one line of text, so nested data is shown as compact inline JSON code.
Can I get HTML instead?
Convert the JSON to CSV and then use CSV to HTML table, or render this Markdown with the Markdown to HTML converter.