1. Schema Reference
Forge reads its schema from a markdown note, usually:
A-I/Forge/Schema/schema.md
The schema defines the structure Forge expects across the vault.
Linting, exports, repairs, normalization, dashboards, Bases, Dataview queries, and relationship indexes all become more reliable when this structure stays consistent.
You do not need a massive schema to get value from Forge.
Even a small schema can dramatically improve long-term vault consistency.
Required Note Structure
A Forge schema is a normal markdown note with:
- frontmatter
- a version field (inline or frontmatter — configured in Settings → Lint)
- a
# Contractheading - one fenced YAML block under that heading
Example:
---
type: reference
status: active
tags:
- tool/forge
created: 2026-07-21
updated: 2026-07-21
ai_private: false
review_cycle: never
---
version:: "1.0"
# Contract
```yaml
frontmatter:
required: []
optional: []
inline:
allowed: []
ontology:
relationships: {}
tag_rules:
require_namespace: true
unknown_tags: warning
severity: warning
allowed_namespaces: []
exempt_paths: []
```
Contract Structure
The schema contract has five required top-level sections. Each section has a clear ownership and purpose. Forge validates that all five are present before reading any contracts.
| Section | Purpose |
|---|---|
frontmatter | Required and optional frontmatter field contracts |
inline | Known inline metadata fields and conditional requirements |
ontology | Semantic relationship definitions between note types |
tag_rules | Tag namespace enforcement rules |
exempt_paths | Paths and glob patterns excluded from lint and shape validation |
frontmatter
Defines field contracts for YAML frontmatter blocks.
frontmatter:
required:
- name: type
type: enum
severity: error
values:
- concept
- skill
- reference
optional:
- name: related_domains
type: list
severity: warning
required entries are checked on every non-exempt note. optional entries are validated only when present.
Each entry supports:
| Key | Required | Meaning |
|---|---|---|
name | Yes | Frontmatter field name |
type | Yes | enum, string, boolean, date, list, or version |
severity | Yes | error, warning, or info |
values | Enum only | Allowed values |
values_meta | Optional | Semantic metadata per enum value — see below |
min_items | List only | Minimum array length |
unique | Optional | Boolean. Set true to require this field's value to be unique across scanned notes |
pattern | Optional | JavaScript regular expression string. Present values must match this pattern |
strict_parse | Date only | Enforce exact format matching |
description | Optional | Human-readable explanation |
lint_rules | Optional | Conditional or consistency rules |
values_meta
Enum fields can carry semantic metadata per value using values_meta. Forge uses this for stale review day calculations. Keys must match the values list.
- name: review_cycle
type: enum
severity: error
values:
- daily
- weekly
- biweekly
- monthly
- quarterly
- semiannual
- yearly
- never
values_meta:
daily: { days: 1 }
weekly: { days: 7 }
biweekly: { days: 14 }
monthly: { days: 30 }
quarterly: { days: 90 }
semiannual: { days: 182 }
yearly: { days: 365 }
never: { days: null }
If a value has no days entry or days: null, it is skipped during stale review.
Unique Fields
Use unique: true on any frontmatter field whose value must be globally unique across scanned notes.
frontmatter:
required:
- name: note_id
type: string
severity: error
unique: true
Forge does not assume a built-in unique field name. A field is checked for uniqueness only when the schema explicitly sets unique: true.
Only the boolean value true enables uniqueness; string values such as "true" are schema errors.
Pattern Fields
Use pattern on any frontmatter field whose value must match a schema-defined format. Optional fields are checked only when present.
frontmatter:
optional:
- name: note_id
type: string
severity: error
unique: true
pattern: "^kac-[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
Forge does not assume note_id or any other field name. Pattern validation only runs for fields declared in frontmatter.required or frontmatter.optional.
inline
Defines known inline metadata fields (key:: value format).
inline:
allowed:
- name: source
- name: version
- name: workout_name
required_when:
field: type
values:
- workout
severity: warning
Each entry requires at minimum name. Entries with required_when are conditionally required — Forge checks them only when the specified frontmatter field matches one of the listed values.
A key found in a note that is not in inline.allowed triggers an inline_undocumented info result.
ontology
Defines semantic relationships between note types.
ontology:
relationships:
informs:
description: "Shapes understanding, interpretation, reasoning, or decision-making."
direction: flexible
allowed_between:
- concept
- principle
- skill
template_heading: Informs
implements:
description: "Realizes a capability in practical application."
direction: directional
sources:
- procedure
- project
targets:
- capability
- method
template_heading: Implements
Each relationship entry requires:
| Key | Meaning |
|---|---|
description | Human-readable explanation of the relationship |
direction | flexible or directional |
allowed_between | For flexible relationships — types that may participate |
sources | For directional relationships — types that may declare the link |
targets | For directional relationships — types that may be linked to |
template_heading | Heading used in note bodies and generated templates |
direction: flexible and direction: directional are mutually exclusive. Flexible uses allowed_between. Directional uses sources and targets.
Template refinement uses template_heading and description when injecting relationship sections into generated templates.
tag_rules
Defines namespace enforcement for all tags.
tag_rules:
require_namespace: true
unknown_tags: warning
severity: warning
allowed_namespaces:
- topic
- tool
- practice
forbidden_namespaces:
- type
- status
- domain
| Key | Meaning |
|---|---|
require_namespace | Require all tags to have a namespace prefix |
unknown_tags | Severity for tags outside allowed_namespaces: error, warning, info, or off |
severity | Global severity for tag rule violations |
allowed_namespaces | Valid namespace prefixes |
forbidden_namespaces | Reserved strings that must not be used as tag namespaces; violations are always error |
forbidden_namespaces is typically used to protect strings that serve as frontmatter field names — using type/ or status/ as tag namespaces creates ambiguity in queries and exports.
exempt_paths
Lists vault-relative paths excluded from lint and shape validation passes.
exempt_paths:
- System/Forge
- Archive
- "**/_*.md"
- "**/*.excalidraw.md"
Accepts folder paths, specific file paths, or glob patterns. Folder paths exclude all notes below that folder. Glob patterns support * within one path segment and ** across folders.
Forge also automatically excludes its own system folder regardless of this list.
Conditional Lint Rules
Fields can include conditional rules using lint_rules.
frontmatter:
optional:
- name: project
type: string
severity: warning
lint_rules:
- rule: required_when
field: type
equals: [project]
severity: error
| Rule | Meaning |
|---|---|
required_when | Field must exist when another field matches a value |
forbidden_when | Field must not exist when another field matches a value |
tag_consistency | Field value should map to a matching tag namespace |
Schema Validation
After editing the schema, run:
Forge: Validate Schema
Forge validates the full contract structure recursively — all five required sections, their subsections, and each entry within them. When shape lint or export is enabled, relationship entries are also validated.
Fix schema issues before running Vault Lint.
Recommended Starting Point
Start small.
A simple schema with type, status, tags, and basic date fields is enough to begin improving consistency across the vault. You can expand the schema gradually over time.
See Starter Schema for a minimal working example.
