---
slug: json-articles-how-they-work
title: "Articles as JSON: how every page here is built"
kind: guide
status: published
hash: f6b20303a62843bd8e7d9977e5ad8b1c667befdb642dbbae17bc57229cd29e47
created: 2026-10-05T01:35:42.530Z
updated: 2026-10-08T14:43:03.953Z
summary: "An article is one JSON object. The page, its Markdown and its machine copy are drawn from it; widgets show other articles, pieces of data, models and sources; any piece can be read, grepped and changed alone."
tags: ["json","widgets","ontology"]
above: []
below: ["[[example-house-14-cypress-lane]]", "[[example-person-dana-reyes]]", "[[every-ai-model-on-openrouter]]", "[[json-article-writing-skill]]"]
adjacent: []
nested: []
---
# Articles as JSON: how every page here is built

*An article is one JSON object. The page, its Markdown and its machine copy are drawn from it; widgets show other articles, pieces of data, models and sources; any piece can be read, grepped and changed alone.*

```widget
{
  "type": "note",
  "title": "Writing an article for the first time?",
  "text": "Read [[write-an-article]] first. It is one short page. This page is the full reference: every part, every widget, every call."
}
```

Every article on this site can now be one JSON object. You post the object; the site draws the page, the Markdown and the machine copy from it. Press **JSON** at the top of this page and you see the object this page is drawn from, whole. Press **Article** and you are back here.

The point is that the same object serves three readers at once: a person reading the page, a search engine reading the HTML, and a model reading `/a/<slug>.json`. Nothing is written into a page by hand, so nothing on a page can drift away from its data.

## The object

An article is a JSON object with a `slug` and a `title`. Everything else is optional. The schema is public at [/schemas/jarticle.json](/schemas/jarticle.json).

```widget
{
  "type": "jsonblock",
  "title": "the smallest article that works",
  "value": {
    "slug": "my-first-article",
    "title": "My first article",
    "body": "Hello. This is **Markdown**."
  }
}
```

The fields that matter:

| Field | What it holds |
| --- | --- |
| `slug` | the address, `/a/<slug>` |
| `title`, `summary` | the headline and the lead under it; the summary is also the text on this article's card when another article carries it |
| `kind` | what the article is about: person, house, company, procedure, model, place … any word; it shows as the badge above the title |
| `status` | `draft` (only the owner sees it) or `published` |
| `facts` | the data, nested as deep as you need |
| `card_fields` | which facts a card of this article shows |
| `ontology` | what sits above, below, beside and inside it |
| `body` | Markdown, or a list of blocks where a block is Markdown or a widget |
| `widgets` | widgets placed with `[[widget:<id>]]` |
| `sources` | each with its URL, its quote and the hashes the build adds |
| `comments` | what models said, each under its model's logo |

## Articles that carry each other

A house's article can show the person who lives there, and the person's article can show the house. Each one draws the other from the other's own object, so there is one copy of every fact. These two are invented examples:

```widget
{
  "type": "articles",
  "title": "Two articles that carry each other",
  "slugs": [
    "example-house-14-cypress-lane",
    "example-person-dana-reyes"
  ]
}
```

There are three ways to put one article inside another:

1. `![[slug]]` alone on a line: that article as a card. This is Obsidian's own embed syntax, so a vault of Markdown notes moves over as it is.
2. `![[slug#facts.work]]` alone on a line: one piece of that article, drawn as a JSON widget.
3. A widget block: `{"type":"article","slug":"…","relation":"lives here"}`.

`[[slug]]` and `[[slug|words]]` inside a sentence are plain links, also as in Obsidian.

## The ontology

Where an article sits is part of its JSON, not a list of links on the page:

```widget
{
  "type": "jsonblock",
  "title": "ontology",
  "value": {
    "ontology": {
      "above": [
        "vertical-insurance"
      ],
      "below": [
        "vehicle-damage-claim"
      ],
      "adjacent": [
        "bodily-injury-claim"
      ],
      "nested": [
        "police-report"
      ],
      "show_position": true
    }
  }
}
```

`nested` articles are drawn as cards at the end of the body. `show_position: true` also draws the box of what is above, below, beside and inside. Without it the page shows none of those links: they stay in the JSON for machines. That is why there is no "related articles" list on these pages.

Because every article is one stored object addressed by its slug, the number of articles has no ceiling but the store. A database of a hundred gigabytes can become a hundred thousand articles: one per row that matters, each pointing at the rows it relates to through `ontology` and `facts`.

## Every widget

Each widget is a JSON object with a `type`. These are drawn live on this page.

### JSON

A collapsible, coloured tree. Click a `{` to fold it. `value` holds the data, or `ref` points at a piece of any article (`"slug#facts.path"`, or `"#path"` for this one).

```widget
{
  "type": "jsonblock",
  "title": "a nested object",
  "value": {
    "permit": {
      "kind": "ADU",
      "fee_usd": 1240.5,
      "paid": true,
      "inspector": null,
      "steps": [
        "apply",
        "plan check",
        {
          "inspect": [
            "framing",
            "final"
          ]
        }
      ],
      "portal": "https://example.gov/permits"
    }
  }
}
```

### Article card

`{"type":"article","slug":"example-person-dana-reyes","relation":"resident"}`

```widget
{
  "type": "article",
  "slug": "example-person-dana-reyes",
  "relation": "resident"
}
```

### Model

`{"type":"model","id":"openai/gpt-5"}` draws a model from the live OpenRouter catalog: its company's logo, its name, its context window and its prices. `{"type":"models"}` draws every model, grouped by company; it has its own article, [[every-ai-model-on-openrouter|Every AI model on OpenRouter]].

```widget
{
  "type": "model",
  "id": "anthropic/claude-opus-4.1"
}
```

```widget
{
  "type": "model",
  "id": "google/gemini-2.5-pro"
}
```

### Comment

A model's comment, under its logo. The `comments` list of an article draws the same way at the bottom of the page. `POST /api/jarticles/<slug>/comments` with `{"model":"<openrouter id>","text":"…"}` adds one.

```widget
{
  "type": "comment",
  "model": "openai/gpt-5",
  "text": "This is an example comment written by hand to show the widget. No model was called to make this page."
}
```

### Source

Every item of `sources` is drawn as a source card at the end, with its hash. The build hashes the quote when the article is saved (`quote_sha256`). `POST /api/jarticles/<slug>/verify` fetches each URL, hashes the page that came back (`snapshot_sha256`) and checks the quote is in it (`quote_found`). A source can also be placed in the body:

```widget
{
  "type": "source",
  "source_type": "official_agency",
  "url": "https://www.bls.gov/cew/",
  "title": "Quarterly Census of Employment and Wages",
  "publisher": "U.S. Bureau of Labor Statistics",
  "quote": "The Quarterly Census of Employment and Wages (QCEW) program publishes a quarterly count of employment and wages reported by employers covering more than 95 percent of U.S. jobs"
}
```

### Quote, stat and note

```widget
{
  "type": "quote",
  "text": "Machine JSON is the canonical object; the article is a projection of it.",
  "cite": "the design decision this page follows"
}
```

```widget
{
  "type": "stat",
  "value": "351",
  "label": "procedures mapped across 70 paperwork verticals in the source workbook"
}
```

```widget
{
  "type": "note",
  "title": "Old widgets still work",
  "text": "Every widget of the old site draws here too: reddit, x, youtube, instagram, tiktok, facebook, linkedin, imessage, whatsapp, wikipedia, site_embed, caveat, thread, gallery."
}
```

## Editing a piece, not the whole article

You never have to send the whole article to change it.

**Read a piece**: `GET /api/jarticles/<slug>/at?path=facts.address.city` answers the value and that piece's own hash.

**Grep**: `GET /api/jarticles/<slug>/grep?q=cypress` answers every key or value that matches, each with the path you would use to change it. `GET /api/jarticles/grep?q=…` searches every article.

**Patch**: `PATCH /api/jarticles/<slug>` with `if-match: <hash>` and a list of operations:

```widget
{
  "type": "jsonblock",
  "title": "PATCH body",
  "value": {
    "ops": [
      {
        "op": "set",
        "path": "facts.bedrooms",
        "value": 4
      },
      {
        "op": "merge",
        "path": "facts.address",
        "value": {
          "zip": "94941"
        }
      },
      {
        "op": "append",
        "path": "tags",
        "value": "marin"
      },
      {
        "op": "insert",
        "path": "body[2]",
        "value": "A new paragraph."
      },
      {
        "op": "move",
        "from": "facts.old",
        "path": "facts.archive.old"
      },
      {
        "op": "delete",
        "path": "facts.lot_sq_ft",
        "if_piece": "<sha256 of that piece from /at>"
      }
    ]
  }
}
```

If someone changed the article after you read it, the hash no longer matches and the write is refused with the current hash. Read again, apply again. `if_piece` does the same for one piece: the write goes through only if that piece is still what you read.

## The Obsidian commands

The Obsidian CLI is on the build's Mac. Its commands work on these articles through `POST /api/jarticles/cli` with `{"command": "...", "file": "<slug or title>", ...}`:

| Command | What it does |
| --- | --- |
| `files` | every article, light |
| `read` | one article whole (`format: "md"` for Markdown) |
| `create` | a new article (`name`, `content`, or a whole `object`; `overwrite` to replace) |
| `append`, `prepend` | add a block to the body (`content` is Markdown or a widget's JSON) |
| `move`, `rename` | change the slug and rewrite every link to it in every other article |
| `delete` | remove it |
| `links`, `backlinks`, `unresolved` | what it links to, what links to it, links to articles that do not exist yet |
| `outline` | its headings |
| `search`, `grep` | text search, or a regular expression with paths |
| `property:read`, `property:set`, `property:remove`, `properties` | read or change one path, like Obsidian's properties |
| `tags` | every tag and how many articles use it |
| `patch` | the operations above |

## The look: every variable

Nothing on the page sets its own colour, size, width or border. Each value comes from one theme object, and each value becomes a CSS variable. The theme is at [/article-theme.json](/article-theme.json). Change any value with `PATCH /api/jarticles/theme` and `{"ops":[{"op":"set","path":"color.accent","value":"#8a3ffc"}]}` (with the theme's hash in `if-match`), and every article changes at once. `color_dark` is the same palette when the reader's system is dark.

```widget
{
  "type": "theme"
}
```

## The ending of every article

Every article page ends with the same line, so any reader, person or model, can look at the JSON or the Markdown the page is drawn from. The addresses are the same for every article; only the slug changes. No key is needed to read them.

```widget
{
  "type": "jsonblock",
  "title": "the ending, as every article carries it",
  "value": {
    "ending": {
      "label": "View the source of this page",
      "json": "/a/<slug>/json",
      "markdown": "/a/<slug>/md",
      "same_as": {
        "json": "/a/<slug>.json",
        "markdown": "/a/<slug>.md"
      },
      "also": [
        "/schemas/jarticle.json",
        "/article-theme.json"
      ],
      "hash": "sha256 of the object, first 16 characters"
    }
  }
}
```

```widget
{
  "type": "group",
  "title": "The ending of every article · 2 calls",
  "items": [
    {
      "type": "jsonblock",
      "title": "this page's JSON, by the ending (no key)",
      "value": {
        "what": "this page's JSON, by the ending (no key)",
        "method": "GET",
        "url": "https://miscsubjects.com/a/json-articles-how-they-work/json",
        "headers": {}
      }
    },
    {
      "type": "jsonblock",
      "title": "this page's Markdown, by the ending (no key)",
      "value": {
        "what": "this page's Markdown, by the ending (no key)",
        "method": "GET",
        "url": "https://miscsubjects.com/a/json-articles-how-they-work/md",
        "headers": {}
      }
    }
  ]
}
```

## Every call, whole

Each call below is one object: the method, the full address, every header and the body. The key is never written into a page. The header holds the command that prints it on the Mac (`cat /Users/cyrusmassoumi/.misc-sheets-key`); the shell fills it in when the call is run. Where a call needs the article's current hash, the header holds the command that reads it. Calls that change something are shown against `my-first-article`, the smallest article, never against this page.

### Reading, with no key

```widget
{
  "type": "group",
  "title": "Reading, with no key · 7 calls",
  "items": [
    {
      "type": "jsonblock",
      "title": "the page",
      "value": {
        "what": "the page",
        "method": "GET",
        "url": "https://miscsubjects.com/a/json-articles-how-they-work",
        "headers": {}
      }
    },
    {
      "type": "jsonblock",
      "title": "the object, its hash and every call that reads or changes it",
      "value": {
        "what": "the object, its hash and every call that reads or changes it",
        "method": "GET",
        "url": "https://miscsubjects.com/a/json-articles-how-they-work.json",
        "headers": {}
      }
    },
    {
      "type": "jsonblock",
      "title": "the Markdown",
      "value": {
        "what": "the Markdown",
        "method": "GET",
        "url": "https://miscsubjects.com/a/json-articles-how-they-work.md",
        "headers": {}
      }
    },
    {
      "type": "jsonblock",
      "title": "the object, by the ending",
      "value": {
        "what": "the object, by the ending",
        "method": "GET",
        "url": "https://miscsubjects.com/a/json-articles-how-they-work/json",
        "headers": {}
      }
    },
    {
      "type": "jsonblock",
      "title": "the Markdown, by the ending",
      "value": {
        "what": "the Markdown, by the ending",
        "method": "GET",
        "url": "https://miscsubjects.com/a/json-articles-how-they-work/md",
        "headers": {}
      }
    },
    {
      "type": "jsonblock",
      "title": "the schema every article follows",
      "value": {
        "what": "the schema every article follows",
        "method": "GET",
        "url": "https://miscsubjects.com/schemas/jarticle.json",
        "headers": {}
      }
    },
    {
      "type": "jsonblock",
      "title": "every variable the pages are drawn with",
      "value": {
        "what": "every variable the pages are drawn with",
        "method": "GET",
        "url": "https://miscsubjects.com/article-theme.json",
        "headers": {}
      }
    }
  ]
}
```

### Reading, with the key

```widget
{
  "type": "group",
  "title": "Reading, with no key · 9 calls",
  "items": [
    {
      "type": "jsonblock",
      "title": "every article, light (q filters)",
      "value": {
        "what": "every article, light (q filters)",
        "method": "GET",
        "url": "https://miscsubjects.com/api/jarticles?q=json",
        "headers": {
          "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)"
        }
      }
    },
    {
      "type": "jsonblock",
      "title": "one article whole, with its hash, drafts too",
      "value": {
        "what": "one article whole, with its hash, drafts too",
        "method": "GET",
        "url": "https://miscsubjects.com/api/jarticles/json-articles-how-they-work",
        "headers": {
          "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)"
        }
      }
    },
    {
      "type": "jsonblock",
      "title": "one piece and that piece's own hash",
      "value": {
        "what": "one piece and that piece's own hash",
        "method": "GET",
        "url": "https://miscsubjects.com/api/jarticles/json-articles-how-they-work/at?path=facts.addresses",
        "headers": {
          "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)"
        }
      }
    },
    {
      "type": "jsonblock",
      "title": "grep one article: every key or value that matches, with the path to change it",
      "value": {
        "what": "grep one article: every key or value that matches, with the path to change it",
        "method": "GET",
        "url": "https://miscsubjects.com/api/jarticles/json-articles-how-they-work/grep?q=widget",
        "headers": {
          "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)"
        }
      }
    },
    {
      "type": "jsonblock",
      "title": "grep every article",
      "value": {
        "what": "grep every article",
        "method": "GET",
        "url": "https://miscsubjects.com/api/jarticles/grep?q=widget",
        "headers": {
          "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)"
        }
      }
    },
    {
      "type": "jsonblock",
      "title": "the OpenRouter catalog the model widgets draw from",
      "value": {
        "what": "the OpenRouter catalog the model widgets draw from",
        "method": "GET",
        "url": "https://miscsubjects.com/api/jarticles/models",
        "headers": {
          "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)"
        }
      }
    },
    {
      "type": "jsonblock",
      "title": "the schema, through the API",
      "value": {
        "what": "the schema, through the API",
        "method": "GET",
        "url": "https://miscsubjects.com/api/jarticles/schema",
        "headers": {
          "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)"
        }
      }
    },
    {
      "type": "jsonblock",
      "title": "the theme and its hash",
      "value": {
        "what": "the theme and its hash",
        "method": "GET",
        "url": "https://miscsubjects.com/api/jarticles/theme",
        "headers": {
          "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)"
        }
      }
    },
    {
      "type": "jsonblock",
      "title": "the structured block contract",
      "value": {
        "what": "the structured block contract",
        "method": "GET",
        "url": "https://miscsubjects.com/api/blocks/contract",
        "headers": {
          "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)"
        }
      }
    }
  ]
}
```

### Creating and changing

```widget
{
  "type": "group",
  "title": "Reading, with no key · 8 calls",
  "items": [
    {
      "type": "jsonblock",
      "title": "create an article (409 if the slug exists)",
      "value": {
        "what": "create an article (409 if the slug exists)",
        "method": "POST",
        "url": "https://miscsubjects.com/api/jarticles",
        "headers": {
          "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)",
          "content-type": "application/json"
        },
        "body": {
          "slug": "my-first-article",
          "title": "My first article",
          "body": "Hello. This is **Markdown**."
        }
      }
    },
    {
      "type": "jsonblock",
      "title": "change pieces: set, merge, delete, append, insert, move",
      "value": {
        "what": "change pieces: set, merge, delete, append, insert, move",
        "method": "PATCH",
        "url": "https://miscsubjects.com/api/jarticles/my-first-article",
        "headers": {
          "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)",
          "content-type": "application/json",
          "if-match": "$(curl -sS -H 'x-sheets-key: $(cat /Users/cyrusmassoumi/.misc-sheets-key)' https://miscsubjects.com/api/jarticles/my-first-article | node -p \"JSON.parse(require('fs').readFileSync(0)).hash\")"
        },
        "body": {
          "ops": [
            {
              "op": "set",
              "path": "facts.bedrooms",
              "value": 4
            },
            {
              "op": "merge",
              "path": "facts.address",
              "value": {
                "zip": "94941"
              }
            },
            {
              "op": "append",
              "path": "tags",
              "value": "marin"
            },
            {
              "op": "insert",
              "path": "body[2]",
              "value": "A new paragraph."
            },
            {
              "op": "move",
              "from": "facts.old",
              "path": "facts.archive.old"
            },
            {
              "op": "delete",
              "path": "facts.lot_sq_ft",
              "if_piece": "<sha256 of that piece from /at>"
            }
          ]
        }
      }
    },
    {
      "type": "jsonblock",
      "title": "replace the whole object",
      "value": {
        "what": "replace the whole object",
        "method": "PUT",
        "url": "https://miscsubjects.com/api/jarticles/my-first-article",
        "headers": {
          "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)",
          "content-type": "application/json",
          "if-match": "$(curl -sS -H 'x-sheets-key: $(cat /Users/cyrusmassoumi/.misc-sheets-key)' https://miscsubjects.com/api/jarticles/my-first-article | node -p \"JSON.parse(require('fs').readFileSync(0)).hash\")"
        },
        "body": {
          "slug": "my-first-article",
          "title": "My first article, replaced",
          "body": "Replaced."
        }
      }
    },
    {
      "type": "jsonblock",
      "title": "remove an article",
      "value": {
        "what": "remove an article",
        "method": "DELETE",
        "url": "https://miscsubjects.com/api/jarticles/my-first-article",
        "headers": {
          "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)",
          "content-type": "application/json",
          "if-match": "$(curl -sS -H 'x-sheets-key: $(cat /Users/cyrusmassoumi/.misc-sheets-key)' https://miscsubjects.com/api/jarticles/my-first-article | node -p \"JSON.parse(require('fs').readFileSync(0)).hash\")"
        }
      }
    },
    {
      "type": "jsonblock",
      "title": "fetch every source, hash what came back, check each quote is in it",
      "value": {
        "what": "fetch every source, hash what came back, check each quote is in it",
        "method": "POST",
        "url": "https://miscsubjects.com/api/jarticles/my-first-article/verify",
        "headers": {
          "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)",
          "content-type": "application/json"
        },
        "body": {}
      }
    },
    {
      "type": "jsonblock",
      "title": "add a model's comment (this calls no model; it files the text given)",
      "value": {
        "what": "add a model's comment (this calls no model; it files the text given)",
        "method": "POST",
        "url": "https://miscsubjects.com/api/jarticles/my-first-article/comments",
        "headers": {
          "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)",
          "content-type": "application/json"
        },
        "body": {
          "model": "openai/gpt-5",
          "text": "The comment text, written by hand."
        }
      }
    },
    {
      "type": "jsonblock",
      "title": "change the look: PATCH one variable",
      "value": {
        "what": "change the look: PATCH one variable",
        "method": "PATCH",
        "url": "https://miscsubjects.com/api/jarticles/theme",
        "headers": {
          "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)",
          "content-type": "application/json",
          "if-match": "$(curl -sS -H 'x-sheets-key: $(cat /Users/cyrusmassoumi/.misc-sheets-key)' https://miscsubjects.com/api/jarticles/theme | node -p \"JSON.parse(require('fs').readFileSync(0)).hash\")"
        },
        "body": {
          "ops": [
            {
              "op": "set",
              "path": "theme.color.accent",
              "value": "#1a5fb4"
            }
          ]
        }
      }
    },
    {
      "type": "jsonblock",
      "title": "append an item to a caveat or thread widget",
      "value": {
        "what": "append an item to a caveat or thread widget",
        "method": "POST",
        "url": "https://miscsubjects.com/api/articles/json-articles-how-they-work/widgets/<widget id>",
        "headers": {
          "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)",
          "content-type": "application/json"
        },
        "body": {
          "text": "The item's text.",
          "by": "who wrote it",
          "reply_to": "<item id, optional>"
        }
      }
    }
  ]
}
```

### The Obsidian commands

Every command is the same call with a different body: `POST /api/jarticles/cli`. `file` is a slug or a title.

```widget
{
  "type": "group",
  "title": "Reading, with no key · 21 calls",
  "items": [
    {
      "type": "jsonblock",
      "title": "cli: files",
      "value": {
        "what": "cli: files",
        "method": "POST",
        "url": "https://miscsubjects.com/api/jarticles/cli",
        "headers": {
          "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)",
          "content-type": "application/json"
        },
        "body": {
          "command": "files"
        }
      }
    },
    {
      "type": "jsonblock",
      "title": "cli: read",
      "value": {
        "what": "cli: read",
        "method": "POST",
        "url": "https://miscsubjects.com/api/jarticles/cli",
        "headers": {
          "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)",
          "content-type": "application/json"
        },
        "body": {
          "command": "read",
          "file": "my-first-article",
          "format": "md"
        }
      }
    },
    {
      "type": "jsonblock",
      "title": "cli: create",
      "value": {
        "what": "cli: create",
        "method": "POST",
        "url": "https://miscsubjects.com/api/jarticles/cli",
        "headers": {
          "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)",
          "content-type": "application/json"
        },
        "body": {
          "command": "create",
          "name": "my-second-article",
          "content": "Hello."
        }
      }
    },
    {
      "type": "jsonblock",
      "title": "cli: create",
      "value": {
        "what": "cli: create",
        "method": "POST",
        "url": "https://miscsubjects.com/api/jarticles/cli",
        "headers": {
          "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)",
          "content-type": "application/json"
        },
        "body": {
          "command": "create",
          "object": {
            "slug": "my-third-article",
            "title": "My third article",
            "body": "Hello."
          },
          "overwrite": false
        }
      }
    },
    {
      "type": "jsonblock",
      "title": "cli: append",
      "value": {
        "what": "cli: append",
        "method": "POST",
        "url": "https://miscsubjects.com/api/jarticles/cli",
        "headers": {
          "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)",
          "content-type": "application/json"
        },
        "body": {
          "command": "append",
          "file": "my-first-article",
          "content": "A paragraph added at the end."
        }
      }
    },
    {
      "type": "jsonblock",
      "title": "cli: prepend",
      "value": {
        "what": "cli: prepend",
        "method": "POST",
        "url": "https://miscsubjects.com/api/jarticles/cli",
        "headers": {
          "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)",
          "content-type": "application/json"
        },
        "body": {
          "command": "prepend",
          "file": "my-first-article",
          "content": {
            "type": "stat",
            "value": "1",
            "label": "an example stat"
          }
        }
      }
    },
    {
      "type": "jsonblock",
      "title": "cli: delete",
      "value": {
        "what": "cli: delete",
        "method": "POST",
        "url": "https://miscsubjects.com/api/jarticles/cli",
        "headers": {
          "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)",
          "content-type": "application/json"
        },
        "body": {
          "command": "delete",
          "file": "my-second-article"
        }
      }
    },
    {
      "type": "jsonblock",
      "title": "cli: move",
      "value": {
        "what": "cli: move",
        "method": "POST",
        "url": "https://miscsubjects.com/api/jarticles/cli",
        "headers": {
          "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)",
          "content-type": "application/json"
        },
        "body": {
          "command": "move",
          "file": "my-third-article",
          "to": "my-fourth-article"
        }
      }
    },
    {
      "type": "jsonblock",
      "title": "cli: rename",
      "value": {
        "what": "cli: rename",
        "method": "POST",
        "url": "https://miscsubjects.com/api/jarticles/cli",
        "headers": {
          "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)",
          "content-type": "application/json"
        },
        "body": {
          "command": "rename",
          "file": "my-fourth-article",
          "name": "my-fifth-article"
        }
      }
    },
    {
      "type": "jsonblock",
      "title": "cli: links",
      "value": {
        "what": "cli: links",
        "method": "POST",
        "url": "https://miscsubjects.com/api/jarticles/cli",
        "headers": {
          "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)",
          "content-type": "application/json"
        },
        "body": {
          "command": "links",
          "file": "json-articles-how-they-work"
        }
      }
    },
    {
      "type": "jsonblock",
      "title": "cli: backlinks",
      "value": {
        "what": "cli: backlinks",
        "method": "POST",
        "url": "https://miscsubjects.com/api/jarticles/cli",
        "headers": {
          "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)",
          "content-type": "application/json"
        },
        "body": {
          "command": "backlinks",
          "file": "json-articles-how-they-work"
        }
      }
    },
    {
      "type": "jsonblock",
      "title": "cli: unresolved",
      "value": {
        "what": "cli: unresolved",
        "method": "POST",
        "url": "https://miscsubjects.com/api/jarticles/cli",
        "headers": {
          "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)",
          "content-type": "application/json"
        },
        "body": {
          "command": "unresolved"
        }
      }
    },
    {
      "type": "jsonblock",
      "title": "cli: outline",
      "value": {
        "what": "cli: outline",
        "method": "POST",
        "url": "https://miscsubjects.com/api/jarticles/cli",
        "headers": {
          "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)",
          "content-type": "application/json"
        },
        "body": {
          "command": "outline",
          "file": "json-articles-how-they-work"
        }
      }
    },
    {
      "type": "jsonblock",
      "title": "cli: search",
      "value": {
        "what": "cli: search",
        "method": "POST",
        "url": "https://miscsubjects.com/api/jarticles/cli",
        "headers": {
          "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)",
          "content-type": "application/json"
        },
        "body": {
          "command": "search",
          "query": "widget"
        }
      }
    },
    {
      "type": "jsonblock",
      "title": "cli: grep",
      "value": {
        "what": "cli: grep",
        "method": "POST",
        "url": "https://miscsubjects.com/api/jarticles/cli",
        "headers": {
          "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)",
          "content-type": "application/json"
        },
        "body": {
          "command": "grep",
          "file": "json-articles-how-they-work",
          "pattern": "widget"
        }
      }
    },
    {
      "type": "jsonblock",
      "title": "cli: property:read",
      "value": {
        "what": "cli: property:read",
        "method": "POST",
        "url": "https://miscsubjects.com/api/jarticles/cli",
        "headers": {
          "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)",
          "content-type": "application/json"
        },
        "body": {
          "command": "property:read",
          "file": "my-first-article",
          "name": "facts.bedrooms"
        }
      }
    },
    {
      "type": "jsonblock",
      "title": "cli: property:set",
      "value": {
        "what": "cli: property:set",
        "method": "POST",
        "url": "https://miscsubjects.com/api/jarticles/cli",
        "headers": {
          "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)",
          "content-type": "application/json"
        },
        "body": {
          "command": "property:set",
          "file": "my-first-article",
          "name": "facts.bedrooms",
          "value": "4"
        }
      }
    },
    {
      "type": "jsonblock",
      "title": "cli: property:remove",
      "value": {
        "what": "cli: property:remove",
        "method": "POST",
        "url": "https://miscsubjects.com/api/jarticles/cli",
        "headers": {
          "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)",
          "content-type": "application/json"
        },
        "body": {
          "command": "property:remove",
          "file": "my-first-article",
          "name": "facts.bedrooms"
        }
      }
    },
    {
      "type": "jsonblock",
      "title": "cli: properties",
      "value": {
        "what": "cli: properties",
        "method": "POST",
        "url": "https://miscsubjects.com/api/jarticles/cli",
        "headers": {
          "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)",
          "content-type": "application/json"
        },
        "body": {
          "command": "properties",
          "file": "my-first-article"
        }
      }
    },
    {
      "type": "jsonblock",
      "title": "cli: tags",
      "value": {
        "what": "cli: tags",
        "method": "POST",
        "url": "https://miscsubjects.com/api/jarticles/cli",
        "headers": {
          "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)",
          "content-type": "application/json"
        },
        "body": {
          "command": "tags"
        }
      }
    },
    {
      "type": "jsonblock",
      "title": "cli: patch",
      "value": {
        "what": "cli: patch",
        "method": "POST",
        "url": "https://miscsubjects.com/api/jarticles/cli",
        "headers": {
          "x-sheets-key": "$(cat /Users/cyrusmassoumi/.misc-sheets-key)",
          "content-type": "application/json"
        },
        "body": {
          "command": "patch",
          "file": "my-first-article",
          "ops": [
            {
              "op": "set",
              "path": "summary",
              "value": "One sentence."
            }
          ]
        }
      }
    }
  ]
}
```

## Every part of an article

An article has seven parts, in this order on the page. Each is shown here as the JSON that makes it and, where it can be drawn alone, as the thing the page draws.

### 1. The header

The badge is `kind`; the small words are the first three `tags`; then `title`, `summary` (the lead), and the byline built from `byline`, the posted and updated dates, and `model`. `hero` is the image above it all. A draft says so in the byline.

```widget
{
  "type": "jsonblock",
  "title": "the header fields",
  "value": {
    "hero": "https://miscsubjects.com/img/gen/example.jpg",
    "kind": "guide",
    "tags": [
      "json",
      "widgets",
      "ontology"
    ],
    "title": "Articles as JSON: how every page here is built",
    "summary": "The lead under the title; also the text of this article's card elsewhere.",
    "byline": "optional",
    "model": "anthropic/claude-opus-5.5",
    "status": "published"
  }
}
```

### 2. The body

`body` is a Markdown string or a list of blocks. A block is a Markdown string, `{"md":"…"}`, or a widget object. The marks inside Markdown:

```widget
{
  "type": "jsonblock",
  "title": "every mark the body understands",
  "value": {
    "**x**": "bold",
    "*x*": "italic",
    "`x`": "code",
    "[words](https://…)": "a link",
    "[[slug]] / [[slug|words]]": "a link to another article",
    "![[slug]] alone on a line": "that article as a card",
    "![[slug#facts.a.b]] alone on a line": "one piece of that article as a JSON widget",
    "[[widget:<id or n>]] alone on a line": "widgets[n] or the widget with that id",
    "```widget {json} ```": "a widget written inside a Markdown string",
    "## x / ### x": "headings",
    "> x": "a quote",
    "- x / 1. x": "list items",
    "| a | b |": "a table"
  }
}
```

### 3. The widgets

`widgets` is a list; each is placed with `[[widget:<id or n>]]` on a line of the body, and the ones never placed are drawn after the body. Every widget type follows in the next section.

### 4. The structured blocks

`blocks` is a list of blocks of the contract `miscsubjects/blocks/1`. They are drawn after the body and the widgets. There are four kinds. The nine content blocks are drawn at the end of this page, just above the sources. The other three are shown here as JSON, because drawing one means reading or acting on a real object.

```widget
{
  "type": "jsonblock",
  "title": "the four kinds",
  "value": {
    "schema": "miscsubjects/blocks/1",
    "version": 1,
    "kinds": {
      "content": {
        "types": [
          "paragraph",
          "heading",
          "list",
          "checklist",
          "code",
          "quote",
          "image",
          "table",
          "divider"
        ],
        "about": "words and layout; renders, never acts"
      },
      "proposal": {
        "about": "an operation that has not run",
        "fields": [
          "op",
          "input",
          "adapter?",
          "binding",
          "state",
          "execution_id",
          "object_ref",
          "receipt_ref"
        ]
      },
      "object": {
        "about": "a reference to a real application object",
        "fields": [
          "ref.id",
          "component",
          "object (state read live)",
          "ops"
        ]
      },
      "receipt": {
        "about": "immutable record of one invocation",
        "fields": [
          "execution_id",
          "ledger_refs"
        ]
      }
    },
    "states": [
      "proposed",
      "pending",
      "succeeded",
      "failed",
      "uncertain",
      "refused",
      "unavailable",
      "invalid"
    ],
    "sync_states": [
      "current",
      "stale",
      "pending",
      "uncertain",
      "failed",
      "unavailable"
    ],
    "statuses": [
      "active",
      "completed",
      "archived",
      "cancelled",
      "deleted",
      "unavailable"
    ]
  }
}
```

```widget
{
  "type": "jsonblock",
  "title": "a proposal block",
  "value": {
    "kind": "proposal",
    "v": 1,
    "op": "task.create",
    "input": {
      "title": "An example task"
    },
    "adapter": null,
    "binding": null,
    "state": "proposed",
    "execution_id": null,
    "object_ref": null,
    "receipt_ref": null
  }
}
```

```widget
{
  "type": "jsonblock",
  "title": "an object block",
  "value": {
    "kind": "object",
    "v": 1,
    "ref": {
      "id": "<the object's canonical id>"
    },
    "component": "task",
    "ops": [
      "task.complete",
      "task.update"
    ]
  }
}
```

```widget
{
  "type": "jsonblock",
  "title": "a receipt block",
  "value": {
    "kind": "receipt",
    "v": 1,
    "execution_id": "<the execution's id>",
    "ledger_refs": [
      "<ledger row id>"
    ]
  }
}
```

The tags a model may write, each turned into the same proposal block as the JSON form above:

```widget
{
  "type": "jsonblock",
  "title": "the 17 tags",
  "value": {
    "TASK": "task.create · title",
    "REMINDER": "task.create · title · apple_reminders",
    "NOTE": "note.create · title · apple_notes",
    "EVENT": "event.create · title",
    "INVITE": "invitation.create · title",
    "BOOKING": "booking.create · slot · calendly",
    "CONTACT": "contact.create · name",
    "PRODUCT": "product.create · title",
    "THREAD": "thread.create · title",
    "TERMINAL": "terminal.run · command",
    "ALFRED": "alfred.trigger · trigger",
    "MAIL": "mail.compose · body · apple_mail",
    "SHORTCUT": "shortcut.run · name · apple_shortcuts",
    "TRELLO-CARD": "card.create · name · trello",
    "TODOIST": "task.create · content · todoist",
    "NOTION-PAGE": "page.create · title · notion",
    "LINEAR-ISSUE": "issue.create · title · linear",
    "written_as": "[TASK]title: …[/TASK]"
  }
}
```

### 5. The nested articles and the position box

`ontology.nested` articles are drawn as cards at the end of the content; `show_position: true` draws the box of what is above, below, beside and inside.

```widget
{
  "type": "position"
}
```

### 6. The sources and the comments

The sources are drawn as a swipeable row of cards under the content, each with the hash of its quote and of the page it came from. The comments are drawn last, under each model's logo. Both are lists of objects:

```widget
{
  "type": "jsonblock",
  "title": "a source, whole",
  "value": {
    "id": "s1",
    "url": "https://www.bls.gov/cew/",
    "title": "Quarterly Census of Employment and Wages",
    "publisher": "U.S. Bureau of Labor Statistics",
    "source_type": "official_agency",
    "date": "2025",
    "quote": "the exact words on the page that support a fact",
    "quote_sha256": "set by the build from quote",
    "http_status": 200,
    "snapshot_sha256": "set by verify: the hash of the page as fetched",
    "snapshot_bytes": 111943,
    "quote_found": true,
    "verified_at": "2026-10-05T01:35:49.087Z"
  }
}
```

```widget
{
  "type": "jsonblock",
  "title": "a comment, whole",
  "value": {
    "model": "openai/gpt-5",
    "by": "optional",
    "text": "The comment text.",
    "at": "2026-10-08T00:00:00Z",
    "reply_to": "optional id of the comment it answers"
  }
}
```

### 7. The ending

The footer: the ending described at the top of this page, and the first 16 characters of the object's hash.

## Every widget, written and drawn

Each widget below appears twice: first as the JSON that makes it, then as the page draws it. The examples are invented for this page; none of the people, posts or links is real, and the addresses are example.com.

### Data widgets

```widget
{
  "type": "example",
  "title": "json, from a value",
  "widget": {
    "type": "json",
    "title": "a value written in place",
    "value": {
      "any": "json",
      "nested": {
        "as": [
          "deep",
          "as",
          "needed"
        ]
      }
    },
    "open_depth": 2
  }
}
```

```widget
{
  "type": "example",
  "title": "json, from a piece of this article",
  "widget": {
    "type": "json",
    "title": "this article's addresses",
    "ref": "#facts.addresses",
    "open_depth": 1
  }
}
```

```widget
{
  "type": "example",
  "title": "json, from a piece of another article",
  "widget": {
    "type": "json",
    "title": "a piece of another article",
    "ref": "example-house-14-cypress-lane#facts",
    "open_depth": 1
  }
}
```

```widget
{
  "type": "example",
  "title": "article",
  "widget": {
    "type": "article",
    "slug": "example-person-dana-reyes",
    "relation": "resident",
    "fields": [
      "facts"
    ]
  }
}
```

```widget
{
  "type": "example",
  "title": "articles",
  "widget": {
    "type": "articles",
    "title": "several cards",
    "slugs": [
      "example-house-14-cypress-lane",
      "example-person-dana-reyes"
    ]
  }
}
```

```widget
{
  "type": "example",
  "title": "model",
  "widget": {
    "type": "model",
    "id": "openai/gpt-5"
  }
}
```

```widget
{
  "type": "example",
  "title": "comment",
  "widget": {
    "type": "comment",
    "model": "openai/gpt-5",
    "text": "An example comment, written by hand to show the widget. No model was called."
  }
}
```

```widget
{
  "type": "example",
  "title": "theme",
  "widget": {
    "type": "theme"
  }
}
```

### Text widgets

```widget
{
  "type": "example",
  "title": "quote",
  "widget": {
    "type": "quote",
    "text": "An example quotation.",
    "cite": "an example citation"
  }
}
```

```widget
{
  "type": "example",
  "title": "stat",
  "widget": {
    "type": "stat",
    "value": "42",
    "label": "an example figure with its label"
  }
}
```

```widget
{
  "type": "example",
  "title": "note",
  "widget": {
    "type": "note",
    "title": "An example note",
    "text": "The note's **Markdown** text."
  }
}
```

```widget
{
  "type": "example",
  "title": "card",
  "widget": {
    "type": "card",
    "title": "An example card",
    "text": "The card's text.",
    "footer": "the card's footer"
  }
}
```

```widget
{
  "type": "example",
  "title": "checklist",
  "widget": {
    "type": "checklist",
    "title": "An example checklist",
    "items": [
      {
        "text": "a finished item",
        "done": true
      },
      {
        "text": "an open item",
        "done": false
      }
    ]
  }
}
```

```widget
{
  "type": "example",
  "title": "terminal",
  "widget": {
    "type": "terminal",
    "title": "an example terminal",
    "lang": "bash",
    "code": "curl -sS https://miscsubjects.com/a/json-articles-how-they-work/json",
    "command": "echo done",
    "output": "done",
    "caption": "the command and what it printed"
  }
}
```

```widget
{
  "type": "example",
  "title": "image",
  "widget": {
    "type": "image",
    "src": "https://miscsubjects.com/brand/og.png",
    "alt": "the site's card image",
    "caption": "an example image with its caption"
  }
}
```

```widget
{
  "type": "example",
  "title": "gallery",
  "widget": {
    "type": "gallery",
    "images": [
      {
        "url": "https://miscsubjects.com/brand/og.png",
        "alt": "the site's card image",
        "caption": "the first image"
      },
      {
        "url": "https://miscsubjects.com/brand/og.png",
        "caption": "the second image"
      }
    ]
  }
}
```

### Expanding widgets

Shut until opened, and grown only by appending an item with the call shown above.

```widget
{
  "type": "example",
  "title": "caveat",
  "widget": {
    "type": "caveat",
    "id": "caveat-example",
    "title": "An example caveat",
    "items": [
      {
        "id": "1",
        "text": "The first limit.",
        "by": "example",
        "at": "2026-10-08"
      }
    ]
  }
}
```

```widget
{
  "type": "example",
  "title": "thread",
  "widget": {
    "type": "thread",
    "id": "thread-example",
    "title": "An example thread",
    "items": [
      {
        "id": "1",
        "text": "A first message.",
        "by": "example",
        "at": "2026-10-08",
        "items": [
          {
            "id": "1.1",
            "text": "A reply to #1."
          }
        ]
      }
    ]
  }
}
```

### Messages

```widget
{
  "type": "example",
  "title": "imessage",
  "widget": {
    "type": "imessage",
    "contact": "Example Contact",
    "subtitle": "iMessage",
    "messages": [
      {
        "from": "them",
        "text": "An example message received."
      },
      {
        "from": "me",
        "text": "An example reply."
      }
    ]
  }
}
```

```widget
{
  "type": "example",
  "title": "whatsapp",
  "widget": {
    "type": "whatsapp",
    "chat_name": "Example Chat",
    "subtitle": "online",
    "messages": [
      {
        "from": "them",
        "text": "An example message received.",
        "time": "9:41"
      },
      {
        "from": "me",
        "text": "An example reply.",
        "time": "9:42"
      }
    ]
  }
}
```

### Social posts

```widget
{
  "type": "example",
  "title": "x",
  "widget": {
    "type": "x",
    "url": "https://example.com/x",
    "author": "Example Author",
    "handle": "@example",
    "text": "An example post."
  }
}
```

```widget
{
  "type": "example",
  "title": "reddit",
  "widget": {
    "type": "reddit",
    "url": "https://example.com/reddit",
    "author": "u/example",
    "title": "An example thread title",
    "text": "An example post body."
  }
}
```

```widget
{
  "type": "example",
  "title": "youtube",
  "widget": {
    "type": "youtube",
    "url": "https://example.com/youtube",
    "title": "An example video",
    "channel": "Example Channel",
    "description": "An example description."
  }
}
```

```widget
{
  "type": "example",
  "title": "instagram",
  "widget": {
    "type": "instagram",
    "url": "https://example.com/instagram",
    "handle": "@example",
    "caption": "An example caption.",
    "images": [
      "https://miscsubjects.com/brand/og.png"
    ]
  }
}
```

```widget
{
  "type": "example",
  "title": "tiktok",
  "widget": {
    "type": "tiktok",
    "url": "https://example.com/tiktok",
    "handle": "@example",
    "text": "An example caption."
  }
}
```

```widget
{
  "type": "example",
  "title": "facebook",
  "widget": {
    "type": "facebook",
    "url": "https://example.com/facebook",
    "handle": "Example Page",
    "text": "An example post."
  }
}
```

```widget
{
  "type": "example",
  "title": "linkedin",
  "widget": {
    "type": "linkedin",
    "url": "https://example.com/linkedin",
    "author": "Example Author",
    "author_title": "Example Title",
    "company": "Example Co",
    "text": "An example post."
  }
}
```

### Reference widgets

```widget
{
  "type": "example",
  "title": "wikipedia",
  "widget": {
    "type": "wikipedia",
    "url": "https://en.wikipedia.org/wiki/Example",
    "title": "Example",
    "body": "An example excerpt.",
    "infobox": {
      "field": "value"
    }
  }
}
```

```widget
{
  "type": "example",
  "title": "site_embed",
  "widget": {
    "type": "site_embed",
    "site": "example",
    "institution": "Example Institution",
    "url": "https://example.com/",
    "title": "An example page",
    "body": "An example excerpt.",
    "date": "2026-10-08"
  }
}
```

```widget
{
  "type": "example",
  "title": "source",
  "widget": {
    "type": "source",
    "source_type": "official_agency",
    "url": "https://example.com/source",
    "title": "An example source",
    "publisher": "example.com",
    "quote": "An example quotation from the source."
  }
}
```

### Source cards, one for each kind of source

A `source` widget, and any widget whose `type` is one of these words, is drawn as the card of that kind. Each card is shown with its JSON.

```widget
{
  "type": "group",
  "title": "Source cards, one for each kind of source",
  "items": [
    {
      "type": "example",
      "title": "source card: x",
      "widget": {
        "type": "x",
        "url": "https://example.com/x",
        "title": "An example x card",
        "publisher": "example.com",
        "quote": "An example quotation. This is not a real x."
      }
    },
    {
      "type": "example",
      "title": "source card: reddit",
      "widget": {
        "type": "reddit",
        "url": "https://example.com/reddit",
        "title": "An example reddit card",
        "publisher": "example.com",
        "quote": "An example quotation. This is not a real reddit."
      }
    },
    {
      "type": "example",
      "title": "source card: instagram",
      "widget": {
        "type": "instagram",
        "url": "https://example.com/instagram",
        "title": "An example instagram card",
        "publisher": "example.com",
        "quote": "An example quotation. This is not a real instagram."
      }
    },
    {
      "type": "example",
      "title": "source card: youtube",
      "widget": {
        "type": "youtube",
        "url": "https://example.com/youtube",
        "title": "An example youtube card",
        "publisher": "example.com",
        "quote": "An example quotation. This is not a real youtube."
      }
    },
    {
      "type": "example",
      "title": "source card: pubmed",
      "widget": {
        "type": "pubmed",
        "url": "https://example.com/pubmed",
        "title": "An example pubmed card",
        "publisher": "example.com",
        "quote": "An example quotation. This is not a real pubmed."
      }
    },
    {
      "type": "example",
      "title": "source card: clinical_trial",
      "widget": {
        "type": "clinical_trial",
        "url": "https://example.com/clinical_trial",
        "title": "An example clinical trial card",
        "publisher": "example.com",
        "quote": "An example quotation. This is not a real clinical trial."
      }
    },
    {
      "type": "example",
      "title": "source card: review",
      "widget": {
        "type": "review",
        "url": "https://example.com/review",
        "title": "An example review card",
        "publisher": "example.com",
        "quote": "An example quotation. This is not a real review."
      }
    },
    {
      "type": "example",
      "title": "source card: medical",
      "widget": {
        "type": "medical",
        "url": "https://example.com/medical",
        "title": "An example medical card",
        "publisher": "example.com",
        "quote": "An example quotation. This is not a real medical."
      }
    },
    {
      "type": "example",
      "title": "source card: statement",
      "widget": {
        "type": "statement",
        "url": "https://example.com/statement",
        "title": "An example statement card",
        "publisher": "example.com",
        "quote": "An example quotation. This is not a real statement."
      }
    },
    {
      "type": "example",
      "title": "source card: press",
      "widget": {
        "type": "press",
        "url": "https://example.com/press",
        "title": "An example press card",
        "publisher": "example.com",
        "quote": "An example quotation. This is not a real press."
      }
    },
    {
      "type": "example",
      "title": "source card: disclosure",
      "widget": {
        "type": "disclosure",
        "url": "https://example.com/disclosure",
        "title": "An example disclosure card",
        "publisher": "example.com",
        "quote": "An example quotation. This is not a real disclosure."
      }
    },
    {
      "type": "example",
      "title": "source card: gov",
      "widget": {
        "type": "gov",
        "url": "https://example.com/gov",
        "title": "An example gov card",
        "publisher": "example.com",
        "quote": "An example quotation. This is not a real gov."
      }
    },
    {
      "type": "example",
      "title": "source card: dictionary",
      "widget": {
        "type": "dictionary",
        "url": "https://example.com/dictionary",
        "title": "An example dictionary card",
        "publisher": "example.com",
        "quote": "An example quotation. This is not a real dictionary."
      }
    },
    {
      "type": "example",
      "title": "source card: book",
      "widget": {
        "type": "book",
        "url": "https://example.com/book",
        "title": "An example book card",
        "publisher": "example.com",
        "quote": "An example quotation. This is not a real book."
      }
    },
    {
      "type": "example",
      "title": "source card: encyclopedia",
      "widget": {
        "type": "encyclopedia",
        "url": "https://example.com/encyclopedia",
        "title": "An example encyclopedia card",
        "publisher": "example.com",
        "quote": "An example quotation. This is not a real encyclopedia."
      }
    },
    {
      "type": "example",
      "title": "source card: wikipedia",
      "widget": {
        "type": "wikipedia",
        "url": "https://example.com/wikipedia",
        "title": "An example wikipedia card",
        "publisher": "example.com",
        "quote": "An example quotation. This is not a real wikipedia."
      }
    },
    {
      "type": "example",
      "title": "source card: hackernews",
      "widget": {
        "type": "hackernews",
        "url": "https://example.com/hackernews",
        "title": "An example hackernews card",
        "publisher": "example.com",
        "quote": "An example quotation. This is not a real hackernews."
      }
    },
    {
      "type": "example",
      "title": "source card: news",
      "widget": {
        "type": "news",
        "url": "https://example.com/news",
        "title": "An example news card",
        "publisher": "example.com",
        "quote": "An example quotation. This is not a real news."
      }
    },
    {
      "type": "example",
      "title": "source card: nyt",
      "widget": {
        "type": "nyt",
        "url": "https://example.com/nyt",
        "title": "An example nyt card",
        "publisher": "example.com",
        "quote": "An example quotation. This is not a real nyt."
      }
    },
    {
      "type": "example",
      "title": "source card: business",
      "widget": {
        "type": "business",
        "url": "https://example.com/business",
        "title": "An example business card",
        "publisher": "example.com",
        "quote": "An example quotation. This is not a real business."
      }
    },
    {
      "type": "example",
      "title": "source card: email",
      "widget": {
        "type": "email",
        "url": "https://example.com/email",
        "title": "An example email card",
        "publisher": "example.com",
        "quote": "An example quotation. This is not a real email."
      }
    },
    {
      "type": "example",
      "title": "source card: letter",
      "widget": {
        "type": "letter",
        "url": "https://example.com/letter",
        "title": "An example letter card",
        "publisher": "example.com",
        "quote": "An example quotation. This is not a real letter."
      }
    },
    {
      "type": "example",
      "title": "source card: github",
      "widget": {
        "type": "github",
        "url": "https://example.com/github",
        "title": "An example github card",
        "publisher": "example.com",
        "quote": "An example quotation. This is not a real github."
      }
    },
    {
      "type": "example",
      "title": "source card: stackoverflow",
      "widget": {
        "type": "stackoverflow",
        "url": "https://example.com/stackoverflow",
        "title": "An example stackoverflow card",
        "publisher": "example.com",
        "quote": "An example quotation. This is not a real stackoverflow."
      }
    },
    {
      "type": "example",
      "title": "source card: arxiv",
      "widget": {
        "type": "arxiv",
        "url": "https://example.com/arxiv",
        "title": "An example arxiv card",
        "publisher": "example.com",
        "quote": "An example quotation. This is not a real arxiv."
      }
    },
    {
      "type": "example",
      "title": "source card: discord",
      "widget": {
        "type": "discord",
        "url": "https://example.com/discord",
        "title": "An example discord card",
        "publisher": "example.com",
        "quote": "An example quotation. This is not a real discord."
      }
    },
    {
      "type": "example",
      "title": "source card: anecdotal",
      "widget": {
        "type": "anecdotal",
        "url": "https://example.com/anecdotal",
        "title": "An example anecdotal card",
        "publisher": "example.com",
        "quote": "An example quotation. This is not a real anecdotal."
      }
    },
    {
      "type": "example",
      "title": "source card: receipt",
      "widget": {
        "type": "receipt",
        "url": "https://example.com/receipt",
        "title": "An example receipt card",
        "publisher": "example.com",
        "quote": "An example quotation. This is not a real receipt."
      }
    },
    {
      "type": "example",
      "title": "source card: live_surface",
      "widget": {
        "type": "live_surface",
        "url": "https://example.com/live_surface",
        "title": "An example live surface card",
        "publisher": "example.com",
        "quote": "An example quotation. This is not a real live surface."
      }
    },
    {
      "type": "example",
      "title": "source card: endpoint",
      "widget": {
        "type": "endpoint",
        "url": "https://example.com/endpoint",
        "title": "An example endpoint card",
        "publisher": "example.com",
        "quote": "An example quotation. This is not a real endpoint."
      }
    },
    {
      "type": "example",
      "title": "source card: api",
      "widget": {
        "type": "api",
        "url": "https://example.com/api",
        "title": "An example api card",
        "publisher": "example.com",
        "quote": "An example quotation. This is not a real api."
      }
    }
  ]
}
```

```widget
{
  "type": "jsonblock",
  "title": "aliases: these words draw the same cards",
  "value": {
    "twitter": "x",
    "tweet": "x",
    "ig": "instagram",
    "yt": "youtube",
    "hn": "hackernews",
    "gh": "github",
    "imsg": "imessage",
    "imessages": "imessage",
    "wa": "whatsapp",
    "callout": "note",
    "caveats": "caveat",
    "todo": "checklist",
    "code": "terminal",
    "codeblock": "terminal",
    "code_block": "terminal",
    "img": "image"
  }
}
```

### Structured content blocks

The nine content blocks, drawn from this article's `blocks` list at the very end of the content, just above the sources.

## Styling, whole

Nothing on a page is styled by hand. The JSON of an article, at `/a/<slug>/json`, now carries a `styling` object: the style scope, the rule for widgets, and the whole theme, so the object alone is enough to draw the page again. Every variable of the theme is also drawn, with its value, by the theme widget further up this page.

```widget
{
  "type": "jsonblock",
  "title": "the styling object inside every article's JSON",
  "value": {
    "styling": {
      "scope": "shared",
      "how": "no value on the page is set by hand: each comes from this theme, and each theme value becomes the CSS variable named beside it. PATCH https://miscsubjects.com/api/jarticles/theme changes them.",
      "widget_style": {
        "what": "every widget may carry style: {…}; these are the only keys it reads",
        "rotate": "degrees, a number",
        "offset_x": "pixels, a number",
        "offset_y": "pixels, a number",
        "pulse": "true to pulse"
      },
      "theme": "every variable, grouped: see GET /article-theme.json"
    }
  }
}
```

```widget
{
  "type": "jsonblock",
  "title": "a widget with style, the JSON",
  "value": {
    "type": "stat",
    "value": "7",
    "label": "an example stat, turned 3 degrees, moved 8 pixels right and pulsing",
    "style": {
      "rotate": 3,
      "offset_x": 8,
      "offset_y": 0,
      "pulse": true
    }
  }
}
```

```widget
{
  "type": "stat",
  "value": "7",
  "label": "an example stat, turned 3 degrees, moved 8 pixels right and pulsing",
  "style": {
    "rotate": 3,
    "offset_x": 8,
    "offset_y": 0,
    "pulse": true
  }
}
```

```widget
{
  "type": "jsonblock",
  "title": "the article-level style field",
  "value": {
    "style_scope": "shared"
  }
}
```

## What the JSON view is

The **JSON** switch at the top of a page, and the address `/a/<slug>#json`, show the whole object: every field, every block of the body, every widget, every source, the hash, the calls that read and change it and the styling. It is printed in full, not folded, with a copy button, and it is the same text `/a/<slug>/json` answers. `/a/<slug>/md` answers the Markdown. Both work for every article: JSON articles, procedures, the recovered articles and the archived pages (an archived page that was never stored as an object answers its page and its text in the JSON).

## Counting views and words

Every article page tells the build once per browser tab that it was read (`POST /api/view`, body `{"slug":"…"}`); the count is kept in the table `ms.article_views` and shown in the byline. A word count is the words of the article's prose; widgets and facts are data and are not counted. The list at [/articles](/articles) sorts by most viewed, most sourced, most claims, longest, shortest, A to Z, newest and oldest, and filters by kind.

## The machine surface

Every article answers at three addresses with no key:

- `/a/<slug>`: the page
- `/a/<slug>.json`: the object, its hash, and every call that reads or changes it, whole
- `/a/<slug>.md`: the Markdown

The owner's calls live under `/api/jarticles` and take the build key in the header `x-sheets-key`:

| Call | What it does |
| --- | --- |
| `GET /api/jarticles` | every article, light (`?q=` filters) |
| `POST /api/jarticles` | create one |
| `GET /api/jarticles/<slug>` | one whole, with its hash |
| `PUT /api/jarticles/<slug>` | replace it (`if-match`) |
| `PATCH /api/jarticles/<slug>` | change pieces (`if-match`) |
| `DELETE /api/jarticles/<slug>` | remove it (`if-match`) |
| `GET /api/jarticles/<slug>/at?path=` | one piece and its hash |
| `GET /api/jarticles/<slug>/grep?q=` | matches with paths |
| `POST /api/jarticles/<slug>/verify` | fetch and hash every source |
| `POST /api/jarticles/<slug>/comments` | add a model's comment |
| `POST /api/jarticles/cli` | the Obsidian commands |
| `GET` / `PATCH /api/jarticles/theme` | the look |
| `GET /api/jarticles/models` | the OpenRouter catalog the model widgets use |
| `GET /api/jarticles/schema` | the schema |

## The procedure pages

The paperwork procedures on the map at [/procedures](/procedures) are drawn in this same frame now: the same bordered page, the same theme, the same Article and JSON switch, without the lists of links.

## The skill

Models that write these articles are given one skill: [[json-article-writing-skill|the skill for writing JSON articles]]. Its Markdown copy at /a/json-article-writing-skill.md is the skill file itself.

## Facts

```json
{
  "schema": "jarticle/1",
  "addresses": {
    "page": "/a/<slug>",
    "object": "/a/<slug>.json",
    "markdown": "/a/<slug>.md",
    "schema": "/schemas/jarticle.json",
    "theme": "/article-theme.json",
    "api": "/api/jarticles"
  },
  "widget_types": [
    "json",
    "article",
    "articles",
    "model",
    "models",
    "comment",
    "theme",
    "position",
    "source",
    "quote",
    "stat",
    "note",
    "card",
    "checklist",
    "terminal",
    "image",
    "gallery",
    "caveat",
    "thread",
    "wikipedia",
    "site_embed",
    "reddit",
    "x",
    "youtube",
    "instagram",
    "tiktok",
    "facebook",
    "linkedin",
    "imessage",
    "whatsapp",
    "pubmed",
    "clinical_trial",
    "review",
    "medical",
    "statement",
    "press",
    "disclosure",
    "gov",
    "dictionary",
    "book",
    "encyclopedia",
    "hackernews",
    "news",
    "nyt",
    "business",
    "email",
    "letter",
    "github",
    "stackoverflow",
    "arxiv",
    "discord",
    "anecdotal",
    "receipt",
    "live_surface",
    "endpoint",
    "api"
  ],
  "patch_ops": [
    "set",
    "merge",
    "delete",
    "append",
    "insert",
    "move"
  ],
  "storage": "one object per article in the build's store (Supabase), state/objects/jarticle/<slug>.json",
  "endings": {
    "json": "/a/<slug>/json",
    "markdown": "/a/<slug>/md"
  },
  "blocks": {
    "schema": "miscsubjects/blocks/1",
    "kinds": [
      "content",
      "proposal",
      "object",
      "receipt"
    ],
    "content_types": [
      "paragraph",
      "heading",
      "list",
      "checklist",
      "code",
      "quote",
      "image",
      "table",
      "divider"
    ]
  },
  "counting": {
    "views": "POST /api/view {\"slug\"} once per browser tab; table ms.article_views",
    "words": "the words of the Markdown blocks of the body"
  }
}
```

## Sources

1. [Quarterly Census of Employment and Wages](https://www.bls.gov/cew/) — “The Quarterly Census of Employment and Wages (QCEW) program publishes a quarterly count of employment and wages reported by employers covering more than 95 percent of U.S. jobs” (sha256 c62f144c9934e10d)
2. [OpenRouter models API](https://openrouter.ai/api/v1/models)
3. [Embed files](https://help.obsidian.md/embeds) — “Embed a note” (sha256 3e88ea4c5a924a3f)

---

**below:** [[example-house-14-cypress-lane]], [[example-person-dana-reyes]], [[every-ai-model-on-openrouter]], [[json-article-writing-skill]]