Schema

Every SwarmVault workspace carries a root markdown file named swarmvault.schema.md.

This file is the vault-specific instruction layer. It tells SwarmVault how this vault should be organized without introducing a separate schema DSL or extra config block.

What It Controls

Use swarmvault.schema.md to define:

  • naming rules for generated pages
  • concept and entity categories
  • expected relationship types
  • grounding and citation rules
  • exclusions and scope boundaries

Lifecycle

  • swarmvault init creates a default swarmvault.schema.md
  • swarmvault compile reads the schema and uses it to guide provider analysis
  • swarmvault query reads the same schema so answers follow the vault's own structure and grounding rules
  • generated pages record a schema_hash in frontmatter
  • swarmvault lint marks generated pages stale when the schema changes

Project Layering

If swarmvault.config.json defines projects, SwarmVault can also load project-specific schema files.

The effective schema for a page becomes:

  1. the root swarmvault.schema.md
  2. the project schema for the page's resolved project, if any

Project schemas are appended after the root schema, so they act as the more specific instruction layer.

This affects:

  • compile prompts for project-scoped pages
  • query prompts when retrieved context includes project-scoped pages
  • schema_hash values written to generated pages
  • incremental invalidation in state/compile-state.json

Pages with mixed-project source coverage stay global and use the root schema only.

Example

# SwarmVault Schema

## Purpose

This vault tracks research on local-first AI tools and agent workflows.

## Naming Rules

- Prefer singular concept names
- Use product names for tool entities

## Categories

- Concepts: workflow, architecture, evaluation, deployment
- Entities: product, company, person, repository, dataset

## Grounding Rules

- Prefer source-backed claims over inferred summaries
- Call out uncertainty explicitly
- Do not invent citations

Notes

  • swarmvault.schema.md is the canonical filename
  • project schemas are optional and configured through projects.<id>.schemaPath
  • ## Categories entries can become category/<slug> tags on generated pages
  • The schema is markdown guidance in the current release, not a structured config format