devsnips
Search docs, APIs, guides…

machine-readable

Schemas

src/data/devsnips/docs/machine-readable/schemas.md

Schemas for every machine-readable surface beyond the registry and per-resource metadata. All of these are generated (or CLI-managed); none are hand-edited.

Specialized indexes — agents/resources/indexes/*.json

Three files: components-index.json, sections-index.json, templates-index.json. Generated from the same in-memory family set as the master registry by scripts/tooling/indexing/build_resource_indexes.py; the generator refuses to write when the master's cross-validation reports a problem. Output is deterministic: families/variants sorted by path, fixed key order, no timestamps.

Index header

{
  "version": "1.0",
  "type": "component",
  "description": "Reusable UI building blocks (components) across all technologies. Generated from library/<Tech>/Components/.",
  "generatedBy": "scripts/tooling/indexing/build_resource_indexes.py",
  "masterIndex": "snippets-index.json",
  "pathConvention": "Paths are tech-first WITHOUT the `library/` prefix…",
  "stats": {
    "families": <int>,
    "resources": <int>,
    "installable": <int>,
    "byTechnology": { "React": <int>, "Tailwind CSS": <int>, "Vanilla HTML/CSS/JS": <int> }
  },
  "families": [ /* … */ ]
}

stats values are live; read them from the current file, never quote them.

Family and variant entries

Family entry: name, path, tech, type, category, variantsCount, variants[].

Variant entry (only fields backed by real data; empty optionals are omitted entirely):

Field Meaning
id The canonical CLI-resolvable id — the registry path without the trailing slash. npx devsnips add <id>.
name Display name.
type component / section / template.
path Registry path with trailing slash; on-disk location is library/<path>.
description Optional.
files Optional. The manifest.
tags / features / styles Optional.
install The exact npx devsnips add <id> command — present only when the CLI would find installable files. No install field = nothing installable.

Path convention is identical to the master (tech-first, no library/ prefix).

Validation

python scripts/tooling/indexing/validate_indexes.py

Fails loudly on: stale entries (indexed path missing on disk), missing resources (disk leaf absent from the index), duplicate ids/paths, wrong type vs parent index, wrong family variantsCount, family/variant path-prefix mismatches, sort-order violations, master↔specialized count mismatches, and JSON parse errors. Exit 0 means the indexes match the repository.

Project config — devsnips/config.json

Written and maintained by the CLI in user projects. Schema version 1:

{
  "version": 1,
  "project": {},
  "resources": [
    { "path": "Vanilla/Components/Buttons/split-button",
      "technology": "Vanilla HTML/CSS/JS",
      "installedAt": "2026-09-11T23:26:00.000Z" }
  ]
}
Field Meaning Stability
version Config schema version, currently 1. Bumped only by a CLI schema change.
project Reserved for project metadata; the CLI never writes to it and preserves it verbatim. User-shaped.
resources[].path Canonical registry path of the installed resource. Stable identity.
resources[].technology Registry technology string. Stable.
resources[].installedAt ISO-8601 install timestamp. Set once at install.

CLI-managed: atomically written, never destructively replaced, records de-duplicated, records written only after files are on disk. Full contract: Configuration.

What does not exist

Do not build integrations against these; they are not implemented:

  • No HTTP/API endpoints — surfaces are files.
  • MCP server exists (integrations/mcp/, read-only stdio) — not an API; see agents/resources/mcp.md.
  • No query DSL or server-side filtering — filtering is done client-side on the JSON.
  • No per-resource webhook or update feed — watch the repository or re-fetch the registry.

Schemas as Markdown