{"$schema":"https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json","id":"generators-json","path":"/generators/json","type":"module","module":"generators-json","title":"JSON","introducedIn":null,"sourceLink":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The `json` generator writes each source file as a JSON document: a tree of\nits headings, each with its metadata, signature or type, Markdown and code\nexamples, in a format a published JSON schema describes. Use it when a program\nneeds your API as data, such as an editor integration, a linter or a site of\nyour own.\n\nTo load every document from one file, add the\n[JSON bundle](https://doc-kit.nodejs.org/generators/json-all) (`json-all`).\n[Debug JSON](https://doc-kit.nodejs.org/generators/json-simple)\n(`json-simple`) is a different format: a dump of the API entries behind every\noutput, for debugging the pipeline.","summary":"The `json` generator writes each source file as a JSON document: a tree of its headings, each with its metadata, signature or type, Markdown and code examples, in a format a published JSON schema describes. Use it when a program needs your API as data, such as an editor integration, a linter or a site of your own.","examples":[],"children":[{"kind":"section","id":"usage","name":"Usage","title":"Usage","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"```bash\nnpx @doc-kit/cli generate -t json -i \"doc/api/*.md\" -o out\n```\n\nThe documents keep the input's directory layout, from where the glob starts:\n`doc/api/fs.md` becomes `out/fs.json`, and `doc/api/guides/streams.md` becomes\n`out/guides/streams.json`.","summary":"The documents keep the input's directory layout, from where the glob starts: `doc/api/fs.md` becomes `out/fs.json`, and `doc/api/guides/streams.md` becomes `out/guides/streams.json`.","examples":[{"language":"bash","displayName":null,"code":"npx @doc-kit/cli generate -t json -i \"doc/api/*.md\" -o out"}],"children":[]},{"kind":"section","id":"configuring","name":"Configuring","title":"Configuring","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"* `schemaURL` {string} The URL every document carries in `$schema`.\n  `{schemaVersion}` is the schema's version (see\n  [templates](https://doc-kit.nodejs.org/configuration#generator-options) for\n  the others). **Default:**\n  `'https://doc-kit.nodejs.org/schemas/api-doc/{schemaVersion}.json'`.\n\nIt also reads the\n[global options](https://doc-kit.nodejs.org/configuration#global-options)\n`output`, `minify`, and `repository` and `ref`, which `sourceLink.url` points\ninto. Without a `repository`, `sourceLink.url` is `null`.","summary":"It also reads the global options `output`, `minify`, and `repository` and `ref`, which `sourceLink.url` points into. Without a `repository`, `sourceLink.url` is `null`.","examples":[],"children":[]},{"kind":"section","id":"the-document","name":"The document","title":"The document","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"```json displayName=\"out/fs.json\"\n{\n  \"$schema\": \"https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json\",\n  \"id\": \"fs\",\n  \"path\": \"/fs\",\n  \"type\": \"module\",\n  \"module\": \"fs\",\n  \"title\": \"File system\",\n  \"introducedIn\": \"v0.10.0\",\n  \"sourceLink\": {\n    \"path\": \"lib/fs.js\",\n    \"url\": \"https://github.com/nodejs/node/blob/HEAD/lib/fs.js\"\n  },\n  \"stability\": { \"index\": \"2\", \"description\": \"Stable\" },\n  \"added\": [],\n  \"deprecated\": [],\n  \"removed\": [],\n  \"napiVersion\": [],\n  \"changes\": [],\n  \"description\": \"The `node:fs` module enables interacting with the file system in a\\nway modeled on standard POSIX functions.\\n\\n…\",\n  \"summary\": \"The `node:fs` module enables interacting with the file system in a way modeled on standard POSIX functions.\",\n  \"examples\": [],\n  \"children\": []\n}\n```\n\nA document stands for a source file and its title heading. Besides the\n[fields every entry has](#fields-every-entry-has), it carries these, most from\nthe file's [page metadata](https://doc-kit.nodejs.org/writing-docs#page-metadata):\n\n| Field          | Type             | Holds                                                                                                                      |\n| -------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------- |\n| `$schema`      | `string`         | The URL of the schema the document conforms to, from `schemaURL`. Its last path segment is the schema version.             |\n| `id`           | `string`         | The file's path in the input tree, slugged: `fs`, `guides-streams`.                                                        |\n| `path`         | `string`         | The file's path in the input tree, without extension: `/fs`.                                                               |\n| `type`         | `string`         | The file's `type=` directive: `module` (the default), `misc` or `global`.                                                  |\n| `module`       | `string \\| null` | The `name=` directive. Without one, the `id` of a `module` document, and `null` for the others.                            |\n| `introducedIn` | `string \\| null` | The `introduced_in=` directive.                                                                                            |\n| `sourceLink`   | `object \\| null` | The `source_link=` directive: `path`, as authored, and `url`, the file on GitHub at `ref` (`null` without a `repository`). |\n| `children`     | `Node[]`         | The file's other headings, as [nodes](#nodes) nested by depth, in document order.                                          |","summary":"A document stands for a source file and its title heading. Besides the fields every entry has, it carries these, most from the file's page metadata:","examples":[{"language":"json","displayName":"out/fs.json","code":"{\n  \"$schema\": \"https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json\",\n  \"id\": \"fs\",\n  \"path\": \"/fs\",\n  \"type\": \"module\",\n  \"module\": \"fs\",\n  \"title\": \"File system\",\n  \"introducedIn\": \"v0.10.0\",\n  \"sourceLink\": {\n    \"path\": \"lib/fs.js\",\n    \"url\": \"https://github.com/nodejs/node/blob/HEAD/lib/fs.js\"\n  },\n  \"stability\": { \"index\": \"2\", \"description\": \"Stable\" },\n  \"added\": [],\n  \"deprecated\": [],\n  \"removed\": [],\n  \"napiVersion\": [],\n  \"changes\": [],\n  \"description\": \"The `node:fs` module enables interacting with the file system in a\\nway modeled on standard POSIX functions.\\n\\n…\",\n  \"summary\": \"The `node:fs` module enables interacting with the file system in a way modeled on standard POSIX functions.\",\n  \"examples\": [],\n  \"children\": []\n}"}],"children":[{"kind":"section","id":"fields-every-entry-has","name":"Fields every entry has","title":"Fields every entry has","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The document and every node carry:\n\n| Field                            | Type             | Holds                                                                                                                                                                                                                                                                           |\n| -------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `title`                          | `string`         | The heading text as authored, inline Markdown included.                                                                                                                                                                                                                         |\n| `stability`                      | `object \\| null` | The stability index: `index`, as authored (`\"1.1\"`), and `description`, the Markdown after it.                                                                                                                                                                                  |\n| `added`, `deprecated`, `removed` | `string[]`       | Versions, as authored.                                                                                                                                                                                                                                                          |\n| `napiVersion`                    | `number[]`       | The Node-API versions the entry is available in.                                                                                                                                                                                                                                |\n| `changes`                        | `object[]`       | The change history, one record per change: `versions`, `prUrl`, `commit` and `description`.                                                                                                                                                                                     |\n| `description`                    | `string`         | The body as Markdown (MDX, from MDX sources): everything under the heading except its metadata, its stability index and the typed list a signature or type was taken from. Reference links are inlined, and links to `.md` files point to the `.html` pages, as on the website. |\n| `summary`                        | `string`         | A one-paragraph summary: the `llm_description` when there is one, else the first paragraph on one line, with links reduced to their text.                                                                                                                                       |\n| `examples`                       | `object[]`       | The fenced code blocks of the body, as `language`, `displayName` and `code`. They stay in `description` too.                                                                                                                                                                    |\n\nEvery field is always present: what a source doesn't declare is `null`, an\nempty string or an empty array.","summary":"The document and every node carry:","examples":[],"children":[]}]},{"kind":"section","id":"nodes","name":"Nodes","title":"Nodes","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"A node is a heading below the title. Its `kind` says what the heading\ndocuments\n([how headings are classified](https://doc-kit.nodejs.org/writing-docs#how-headings-are-classified))\nand decides which further fields the node has:\n\n| `kind`         | Heading                                        | Further fields    |\n| -------------- | ---------------------------------------------- | ----------------- |\n| `section`      | Anything else: prose, `DEP0005: …`, `--flag`   | none              |\n| `class`        | `` Class: `net.Server` ``                      | `extends`         |\n| `constructor`  | `` `new Agent([options])` ``                   | `signature`       |\n| `method`       | `` `fs.readFile(path[, options], callback)` `` | `signature`       |\n| `staticMethod` | `` Static method: `Buffer.from(string)` ``     | `signature`       |\n| `property`     | `` `buf.length` ``                             | `type`, `default` |\n| `event`        | `` Event: `'close'` ``                         | `parameters`      |\n\nEvery node also carries:\n\n| Field        | Type             | Holds                                                                                                                             |\n| ------------ | ---------------- | --------------------------------------------------------------------------------------------------------------------------------- |\n| `id`         | `string`         | The heading's slug, unique within the document. It's the heading's anchor on the website.                                         |\n| `name`       | `string`         | The bare identifier: `readFile`, `Server`, `close`. A section's heading text. A `name=` directive under the heading overrides it. |\n| `scope`      | `string`         | `global` for headings typed `global` and in `global` documents, `module` otherwise.                                               |\n| `overloadOf` | `string \\| null` | On the second and later of consecutive sibling headings documenting the same callable, the `id` of the first.                     |\n| `children`   | `Node[]`         | The headings nested under this one.                                                                                               |","summary":"A node is a heading below the title. Its `kind` says what the heading documents (how headings are classified) and decides which further fields the node has:","examples":[],"children":[]},{"kind":"section","id":"signatures-and-types","name":"Signatures and types","title":"Signatures and types","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The further fields come from the heading and the\n[typed list](https://doc-kit.nodejs.org/writing-docs#parameters-return-values-and-defaults)\nunder it:\n\n| Field        | On                                       | Holds                                                                                                                                                                |\n| ------------ | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `signature`  | constructors, methods and static methods | `parameters`, every parameter the heading declares, in order, and `returns`, the `Returns:` item or `null`. A parameter the list doesn't describe has a `null` type. |\n| `extends`    | classes                                  | The type of the `Extends:` item, else the `extends` in the heading (`` Class: `Foo extends Bar` ``), else `null`.                                                    |\n| `type`       | properties                               | The type of the `Type:` item. Its description goes first in the node's `description`.                                                                                |\n| `default`    | properties                               | The default of the `Type:` item.                                                                                                                                     |\n| `parameters` | events                                   | The arguments the listeners receive.                                                                                                                                 |\n\nA parameter has a `name`, without `...`, a `type`, a `description`, and:\n\n* `default`: the value as authored, without its code span, or `null`.\n* `optional`: `true` when the parameter is bracketed in the heading or has a\n  default.\n* `rest`: `true` when it's declared as `...args`.\n* `properties`: its nested items, such as the properties of an options object\n  or the arguments of a callback, each a parameter too.\n\nA type has `text`, the annotation as a TypeScript type on one line, with `|`\nbetween union members, and `links`, the names in it that resolved to\ndocumentation, with their offsets in `text` (see\n[Types that link themselves](https://doc-kit.nodejs.org/writing-docs#types-that-link-themselves)).\nA type the source doesn't document is `null`, never guessed.\n\nFor example, this method:\n\n```markdown displayName=\"doc/api/fs.md\"\n## `fsPromises.readFile(path[, options])`\n\n- `path` {string|URL} The file to read.\n- `options` {Object}\n  - `encoding` {string|null} **Default:** `null`.\n- Returns: {Promise} Fulfills with the contents of the file.\n\nReads the entire contents of a file.\n```\n\nhas `Reads the entire contents of a file.` as its `description`, and this\n`signature` (each type's `links` shortened to `[]`):\n\n```json\n{\n  \"parameters\": [\n    {\n      \"name\": \"path\",\n      \"type\": { \"text\": \"string | URL\", \"links\": [] },\n      \"description\": \"The file to read.\",\n      \"default\": null,\n      \"optional\": false,\n      \"rest\": false,\n      \"properties\": []\n    },\n    {\n      \"name\": \"options\",\n      \"type\": { \"text\": \"Object\", \"links\": [] },\n      \"description\": \"\",\n      \"default\": null,\n      \"optional\": true,\n      \"rest\": false,\n      \"properties\": [\n        {\n          \"name\": \"encoding\",\n          \"type\": { \"text\": \"string | null\", \"links\": [] },\n          \"description\": \"\",\n          \"default\": \"null\",\n          \"optional\": true,\n          \"rest\": false,\n          \"properties\": []\n        }\n      ]\n    }\n  ],\n  \"returns\": {\n    \"type\": { \"text\": \"Promise\", \"links\": [] },\n    \"description\": \"Fulfills with the contents of the file.\"\n  }\n}\n```\n\nEach `links` array lists its type's names with where they point and their\noffsets, such as\n`{ \"name\": \"URL\", \"href\": \"https://developer.mozilla.org/docs/Web/API/URL\", \"start\": 9, \"end\": 12 }`\nfor `URL` in `string | URL`.","summary":"The further fields come from the heading and the typed list under it:","examples":[{"language":"markdown","displayName":"doc/api/fs.md","code":"## `fsPromises.readFile(path[, options])`\n\n- `path` {string|URL} The file to read.\n- `options` {Object}\n  - `encoding` {string|null} **Default:** `null`.\n- Returns: {Promise} Fulfills with the contents of the file.\n\nReads the entire contents of a file."},{"language":"json","displayName":null,"code":"{\n  \"parameters\": [\n    {\n      \"name\": \"path\",\n      \"type\": { \"text\": \"string | URL\", \"links\": [] },\n      \"description\": \"The file to read.\",\n      \"default\": null,\n      \"optional\": false,\n      \"rest\": false,\n      \"properties\": []\n    },\n    {\n      \"name\": \"options\",\n      \"type\": { \"text\": \"Object\", \"links\": [] },\n      \"description\": \"\",\n      \"default\": null,\n      \"optional\": true,\n      \"rest\": false,\n      \"properties\": [\n        {\n          \"name\": \"encoding\",\n          \"type\": { \"text\": \"string | null\", \"links\": [] },\n          \"description\": \"\",\n          \"default\": \"null\",\n          \"optional\": true,\n          \"rest\": false,\n          \"properties\": []\n        }\n      ]\n    }\n  ],\n  \"returns\": {\n    \"type\": { \"text\": \"Promise\", \"links\": [] },\n    \"description\": \"Fulfills with the contents of the file.\"\n  }\n}"}],"children":[]},{"kind":"section","id":"using-the-schema","name":"Using the schema","title":"Using the schema","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Every document's `$schema` points to the version of the schema it conforms to,\nsuch as `https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json`. The schema\nalso ships in `@doc-kit/core` as `@doc-kit/core/generators/json/schema.json`,\nwith TypeScript types generated from it:\n\n```ts displayName=\"list-methods.ts\"\nimport { readFile } from 'node:fs/promises';\n\nimport type {\n  Document,\n  Node,\n} from '@doc-kit/core/generators/json/generated/schema';\n\nconst fs: Document = JSON.parse(await readFile('out/fs.json', 'utf-8'));\n\nconst listMethods = (nodes: Array<Node>): void => {\n  for (const node of nodes) {\n    if (node.kind === 'method') {\n      console.log(\n        node.name,\n        node.signature.parameters.map(p => p.name)\n      );\n    }\n\n    listMethods(node.children);\n  }\n};\n\nlistMethods(fs.children);\n```","summary":"Every document's `$schema` points to the version of the schema it conforms to, such as `https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json`. The schema also ships in `@doc-kit/core` as `@doc-kit/core/generators/json/schema.json`, with TypeScript types generated from it:","examples":[{"language":"ts","displayName":"list-methods.ts","code":"import { readFile } from 'node:fs/promises';\n\nimport type {\n  Document,\n  Node,\n} from '@doc-kit/core/generators/json/generated/schema';\n\nconst fs: Document = JSON.parse(await readFile('out/fs.json', 'utf-8'));\n\nconst listMethods = (nodes: Array<Node>): void => {\n  for (const node of nodes) {\n    if (node.kind === 'method') {\n      console.log(\n        node.name,\n        node.signature.parameters.map(p => p.name)\n      );\n    }\n\n    listMethods(node.children);\n  }\n};\n\nlistMethods(fs.children);"}],"children":[{"kind":"section","id":"changing-the-schema","name":"Changing the schema","title":"Changing the schema","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"For doc-kit contributors: `schema.json` is the source of truth for the format.\nWhen you change it, bump the version in its `$id`, in `SCHEMA_VERSION` in\n`constants.mjs`, and in the `$id` of the JSON bundle's schema and its\nreference to this one, all together. Then regenerate the types with\n`node scripts/generate-json-types.mjs`. The tests fail while the versions\ndisagree or the committed types are stale.","summary":"For doc-kit contributors: `schema.json` is the source of truth for the format. When you change it, bump the version in its `$id`, in `SCHEMA_VERSION` in `constants.mjs`, and in the `$id` of the JSON bundle's schema and its reference to this one, all together. Then regenerate the types with `node scripts/generate-json-types.mjs`. The tests fail while the versions disagree or the committed types are stale.","examples":[],"children":[]}]}]}