Skip to content

Check a text asset's syntax

POST
/assets/{id}/lint

Runs a quick syntax and style check on the asset’s stored file and returns what it found. The checker is chosen by the file extension recorded for the asset: JSON for .json and .jsonc, YAML for .yaml and .yml, and Markdown for .md, .markdown and .mdx.

The checks are light. JSON gets one strict parse that reports the first syntax error; comments in .jsonc files are reported as errors, and content after the first value is reported except a stray closing ] or }. YAML is parsed document by document: duplicate keys are all reported, and the first other parse error ends the check. Markdown gets a few style rules: trailing spaces or tabs, prose lines that start with a tab, # headings with no space after the marks, lines longer than 120 bytes, and a code fence that’s never closed. Nothing checks what the content means, runs it, or validates .mdx components, so a clean result doesn’t make the file valid for any particular use.

Only the first 4 MiB of the file is read. A larger file is checked as if it ended there, without warning, so the result can show errors the whole file doesn’t have, such as JSON that seems to end early, or miss problems after the cut.

When the asset has no recorded extension, the answer is linter: "none" and skipped: true with no diagnostics, and the file isn’t read. Any other extension the server has no checker for also gives skipped: true, after the file has been read, with an empty diagnostics list. The extension is matched without its leading dot and ignoring case; the asset’s type and the file’s actual contents don’t change which checker runs.

You need to be signed in. An asset that doesn’t exist, is deleted or has no file recorded answers 404. When the file is read and storage reports it missing, the answer is also 404; other errors while fetching or reading it answer 500. The check runs while you wait, nothing is cached and nothing is saved.

id
required
string format: uuid

The asset’s id.

What the check found.

object
linter
required

The checker that ran: json, yaml or markdown, or none when none did.

string
skipped
required

true when no checker ran because the extension is missing or isn’t one the server checks. With a supported extension, a file that’s empty or only white space is still checked: it comes back with no findings and skipped: false.

boolean
diagnostics

The findings, in the order the checker produced them; empty when there are none. Left out when the asset has no recorded extension.

Array<object>
object
line
required

The line, counting from 1. For YAML it’s the line the parser names, or 1 when it names none.

integer
>= 1
col
required

The column, counting from 1. Columns count bytes, so they drift on lines with non-ASCII text. YAML findings always use column 1, a JSON syntax error is placed just after the byte that caused it, and a JSON error without a position, such as a file that ends early, is placed at line 1, column 1.

integer
>= 1
end_line

The line where the finding ends, for the Markdown rules that mark a span; left out otherwise.

integer
nullable >= 1
end_col

The column just past the end of the span, counting bytes from 1; left out when there’s no span.

integer
nullable >= 1
severity
required

error for JSON and YAML problems and an unclosed code fence; warning or info for the other Markdown rules.

string
Allowed values: info warning error
message
required

What’s wrong, in words. Parser messages can quote the text they stopped at.

string
source
required

The checker that produced it: json, yaml or markdown.

string

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed