drivers.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "thermal-label suite manifest",
  "description": "Single source of truth for which repos make up the thermal-label suite. Consumed by scripts/pull-driver-docs.mjs, scripts/build-hardware-page.mjs, and .vitepress/config.ts.",
  "type": "object",
  "additionalProperties": false,
  "required": ["members"],
  "properties": {
    "$schema": { "type": "string" },
    "members": {
      "type": "array",
      "items": { "$ref": "#/$defs/member" }
    }
  },
  "$defs": {
    "member": {
      "type": "object",
      "additionalProperties": false,
      "required": ["name", "kind", "repo", "ref"],
      "properties": {
        "name": {
          "type": "string",
          "description": "Local repo / dest directory name (matches docs/<name>/)."
        },
        "kind": {
          "type": "string",
          "enum": ["driver", "protocol-core", "shared", "tool"]
        },
        "repo": {
          "type": "string",
          "pattern": "^[\\w.-]+/[\\w.-]+$",
          "description": "GitHub <org>/<repo>."
        },
        "ref": {
          "type": "string",
          "description": "git ref to clone for the public build (sibling checkouts override locally)."
        },
        "displayName": {
          "type": "string",
          "description": "Human-readable family label. Required for kind=driver."
        },
        "manufacturer": {
          "type": "string",
          "description": "Vendor / OEM string for JSON-LD. Required for kind=driver."
        },
        "pkg": {
          "type": "string",
          "pattern": "^@thermal-label/[\\w-]+-core$",
          "description": "npm package name of the driver's *-core package. Required for kind=driver."
        },
        "published": {
          "type": "boolean",
          "description": "Driver-only flag. Defaults to true. Set false to keep the driver in drivers.json (so the matrix sees its data/devices.json) without requiring its npm package to be installed yet — used while a new driver is incoming and not yet released."
        },
        "harness": {
          "type": "boolean",
          "description": "Driver-only flag. Defaults to false. Set true when the harness monorepo ships a `harness-<name>` app, released as a `harness-<name>-v*` tag on thermal-label/harness. scripts/pull-harness-bundles.mjs downloads the newest such release's zip and extracts it to docs/public/harness/<name>/, which VitePress serves at /harness/<name>/."
        },
        "enabled": {
          "type": "boolean",
          "description": "Defaults to true. Set false to fully exclude the member from every build step — docs pull, hardware pages, media catalogues, compatibility matrix, and site nav — while keeping its drivers.json entry (and any package.json dep) intact, so re-enabling is a single flag flip. Distinct from `published`, which still surfaces a driver in the matrix."
        },
        "requiredFiles": {
          "type": "array",
          "items": { "type": "string" }
        },
        "mediaDataFile": {
          "type": "string",
          "description": "Repo-relative path to a compiled media.json catalogue (paired with a media.json5 source). Pulled by scripts/pull-driver-docs.mjs into .aggregate/media/<name>.json and rendered by scripts/build-media-pages.mjs into docs/<name>/media.md. Most drivers use 'packages/core/data/media.json'; d1-core uses 'data/media.json'."
        },
        "mediaFragment": {
          "type": "string",
          "description": "Optional repo-relative path to a hand-authored markdown fragment that build-media-pages.mjs slot-includes into the generated media page (e.g. brother-ql's spool-switch pin map). Pulled along with docs/ in the normal docs sync."
        },
        "mediaFragmentPlacement": {
          "type": "string",
          "enum": ["before", "after"],
          "description": "Where to slot the mediaFragment relative to the generated catalogue tables. 'after' (default) suits reference fragments readers consult after browsing; 'before' suits warnings or framing callouts that should be seen first."
        },
        "mediaFilter": {
          "type": "object",
          "additionalProperties": false,
          "description": "Filter the entries surfaced on the generated media page without changing the underlying catalogue. Useful when a driver's compiled media.json merges in shared catalogues that have their own page (e.g. labelwriter merges d1-core's tape entries at compile time; surface those on /d1-core/media instead).",
          "properties": {
            "excludeTypes": {
              "type": "array",
              "items": { "type": "string" },
              "description": "Drop entries whose `type` field matches any value in the list."
            }
          }
        }
      },
      "allOf": [
        {
          "if": { "properties": { "kind": { "const": "driver" } }, "required": ["kind"] },
          "then": { "required": ["displayName", "manufacturer", "pkg"] }
        }
      ]
    }
  }
}