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.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The asset’s id.
Responses
Section titled “ Responses ”What the check found.
object
The checker that ran: json, yaml or markdown, or none when
none did.
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.
The findings, in the order the checker produced them; empty when there are none. Left out when the asset has no recorded extension.
object
The line, counting from 1. For YAML it’s the line the parser names, or 1 when it names none.
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.
The line where the finding ends, for the Markdown rules that mark a span; left out otherwise.
The column just past the end of the span, counting bytes from 1; left out when there’s no span.
error for JSON and YAML problems and an unclosed code fence; warning or info for the other Markdown rules.
What’s wrong, in words. Parser messages can quote the text they stopped at.
The checker that produced it: json, yaml or markdown.
Authentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Resource not found
object
Human-readable error summary
Example
the request could not be completed