JSON
JSON is a way of writing structured information as plain text: named values, lists, numbers and words, nested as deep as needed.
In more detail
There are only a few pieces to it. A value has a name and a content; a content is a word, a number, a yes or no, a list of contents, or another set of named values. Everything else is built by nesting those.
Because it is text, it can be read by a person, kept in a file, put under version control and compared line by line. Because it is simple, every programming language turns its own data into it and back with one call.
What it does on a real document
The whole document is described in it before anything is drawn: a list of things to draw, and beside that list the typefaces, colours and pictures those things refer to by name.
Writing it by hand is perfectly possible for a first try, and that is what the examples on these pages are. In a real program it is built the way any other data is, and turned into text at the last moment.
Where it comes from, and why
It came out of the way one language already wrote its own data, and spread because it was the smallest thing that did the job. The full description of it fits on a single page.
What it replaced was heavier: a shape that carried tags around every value and needed a schema beside it to be read at all. Both are still in use, and an invoice standard often asks for the heavier one — which is why a finished document can carry it inside while the request that made it is written in this.
See it on a finished document
The rules behind this word, and the texts they are read from
Glossary
- standard
- A rule argued out in committee, published under a number anybody may buy and read, and identical for every firm claiming it. A claim to follow one can therefore be checked against the text. A way of working that merely spread because it worked is a habit of the trade: useful, widespread, and answerable to no text at all.
- font
- The drawing of every letter, digit and mark a document writes, held in a file of its own. A PDF carries the fonts it is set in inside itself, which is why it opens looking the same on a machine that has never had them. Leave them out and a reader puts another font in their place, and the layout moves.
- tagged PDF
- A PDF that carries the structure of its own text alongside the drawing: this is a heading, this is a table, this cell belongs to that column. It is what lets a reading aid, or a program pulling data back out, make sense of the page.
- request
- One call to the service: you send what the document should say, and get the document back. Your bill counts these calls, one for each document. The number of pages inside a document is never counted.