geronimo-iia/llm-wiki-skills/schema

Schema

Every wiki page has a type field. The type determines which JSON Schema validates the frontmatter, how fields are indexed, and what graph edges are declared.

For frontmatter field conventions, see the frontmatter skill.

Epistemic roles

The type field carries epistemic distinctions:

Classify by the source material's nature, not its topic. A blog post about academic research is article, not paper.

Built-in types

Shipped by llm-wiki spaces create:

One schema can serve multiple types (e.g. paper.json serves all 9 source types).

Type discovery

Types are discovered automatically from schemas/*.json files. Each schema declares which types it serves via x-wiki-types:

"x-wiki-types": {
  "paper": "Academic source — research papers, preprints",
  "article": "Editorial source — blog posts, news, essays"
}

Resolution order:

1. Scan schemas/*.json → collect x-wiki-types entries
2. Read [types.*] from wiki.toml (if any)
3. wiki.toml entry wins over discovered entry

Common case: no [types.*] in wiki.toml — types are fully discovered from schema files.

Keyword fields

String properties default to full-text analyzed indexing (BM25). Mark a property "x-keyword": true to index it as an exact-match keyword field:

{
  "properties": {
    "domain": {
      "type": "string",
      "x-keyword": true
    }
  }
}

Keyword fields:

• Indexed as STRING | STORED | FAST — exact match, no tokenization
• Appear in facet distributions (like type and status)
• FAST storage means facet counts carry no extra segment pass overhead
• Filtering is case-sensitive exact match — not partial-word

Use x-keyword: true for controlled vocabulary fields (states, categories, enums). Leave plain "type": "string" for free-text prose fields.

The built-in type and status fields use keyword indexing. tags uses keyword indexing on its array elements.

Field aliasing

Different types use different field names for the same role. The engine maps them via x-index-aliases in the schema:

"x-index-aliases": {
  "name": "title",
  "description": "summary",
  "when_to_use": "read_when"
}

Aliases affect indexing only — files on disk are never rewritten.

Graph edges

Each schema declares outgoing edges via x-graph-edges:

Body [[wiki-links]] get a generic links-to relation.

Constraints

• A default type must always exist in the registry. If no schema

declares it, the embedded base.json is used as fallback.

• A custom base.json must declare default in x-wiki-types.
• A custom base.json must require at least title and type

fields (superset is fine, but cannot drop them).

• Pages without a type field default to type: page, validated

against default.

• Pages with an unregistered type are validated against default.
• The default type cannot be removed.

List registered types

wiki_schema(action: "list")

[
  {
    "name": "concept",
    "description": "Synthesized knowledge — one concept per page",
    "schema_path": "schemas/concept.json"
  }
]

Inspect a type schema

wiki_schema(action: "show", type: "<type>")

Returns the full JSON Schema for the given type.

Get a frontmatter template

wiki_schema(action: "show", type: "<type>", template: true)

Returns a YAML frontmatter block with required fields filled with placeholder values.

Add a custom type

Drop a schema file into schemas/ with x-wiki-types for automatic discovery, or register explicitly:

wiki_schema(action: "add", type: "<type>", schema_path: "<path>")

A custom schema must be valid JSON Schema (Draft 2020-12) and should include x-wiki-types. The engine validates, copies it into schemas/, and confirms index resolution works.

Optionally add a body template at schemas/<type>.md — it will be used by wiki_content_new when creating pages of this type.

Remove a type

wiki_schema(action: "remove", type: "<type>")

The default type cannot be removed. Add delete: true to also modify/delete the schema file. Add delete_pages: true to delete page files from disk. Use dry_run: true to preview.

Validate schemas

wiki_schema(action: "validate")

Validates all schema files. Pass type: "<type>" to validate a single type. Checks: valid JSON Schema, x-wiki-types presence, alias resolution, base schema invariant (default type requires title and type), and full index compatibility.