Schema Reference¶
All data files are validated against JSON Schema (Draft 2020-12). Schemas live in schemas/.
lessons.schema.json¶
Validates data/lessons.json — the source of truth for all lesson records.
Schema ID: https://github.com/joeblackwaslike/lessons-learned/schemas/lessons.schema.json
Top-level¶
| Field | Type | Required | Description |
|---|---|---|---|
type |
"lessons-learned-store" |
✓ | Discriminator |
version |
1 |
✓ | Schema version |
lessons |
Lesson[] |
✓ | Array of lesson records |
Lesson record¶
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
id |
string |
✓ | Pattern: ^[0-9A-Z]{26}$ |
ULID — collision-free, sortable by creation time |
slug |
string |
✓ | Pattern: ^[a-z0-9]+(-[a-z0-9]+)*-[a-z0-9]{4}$ |
kebab-case + 4-char random suffix |
summary |
string |
✓ | Max 120 chars | One-line description; fallback injection text |
problem |
string |
✓ | — | Root cause explanation |
solution |
string |
✓ | — | Concrete fix |
injection |
string |
✓ | — | Pre-rendered markdown for hook injection |
triggers |
Triggers |
✓ | See below | What activates this lesson |
priority |
integer |
✓ | 1–10 | Higher wins budget conflicts |
confidence |
number |
✓ | 0.0–1.0 | Below minConfidence → excluded from manifest |
needsReview |
boolean |
— | Default: false |
Excluded from manifest when true |
tags |
string[] |
✓ | Pattern: ^[a-z]+:[a-z0-9._-]+$ |
category:value taxonomy |
sourceSessionIds |
string[] |
— | Default: [] |
Session provenance (up to 5) |
occurrenceCount |
integer |
— | Min: 0 | Times pattern detected by scanner |
createdAt |
string |
✓ | ISO 8601 | Creation timestamp |
updatedAt |
string |
✓ | ISO 8601 | Last update timestamp |
contentHash |
string |
✓ | Pattern: ^sha256:[a-f0-9]{64}$ |
Dedup hash of problem + solution + triggers |
Triggers object¶
| Field | Type | Required | Description |
|---|---|---|---|
toolNames |
string[] |
✓ | Must include at least one. Values: Bash, Read, Edit, Write, Glob |
commandPatterns |
string[] |
— | Regex patterns matched against Bash command string |
pathPatterns |
string[] |
— | Glob/regex patterns matched against file paths |
contentPatterns |
string[] |
— | Reserved for future use |
manifest.schema.json¶
Validates data/lesson-manifest.json — the pre-compiled runtime index read by the injection hook.
Schema ID: https://github.com/joeblackwaslike/lessons-learned/schemas/manifest.schema.json
Do not edit directly
lesson-manifest.json is generated by node scripts/lessons.mjs build. Edit lessons.json and rebuild instead.
Top-level¶
| Field | Type | Required | Description |
|---|---|---|---|
type |
"lessons-learned-manifest" |
✓ | Discriminator |
version |
1 |
✓ | Schema version |
generatedAt |
string |
✓ | ISO 8601 build timestamp |
config |
object |
✓ | Config snapshot at build time |
lessons |
object |
✓ | Lessons keyed by ULID |
Config snapshot¶
The manifest embeds a snapshot of injection-relevant config fields so the hook never needs to read config.json:
| Field | Type |
|---|---|
injectionBudgetBytes |
integer |
maxLessonsPerInjection |
integer |
minConfidence |
number |
minPriority |
integer |
compactionReinjectionThreshold |
integer |
Manifest lesson record¶
| Field | Type | Required | Description |
|---|---|---|---|
slug |
string |
✓ | For logging and dedup claim filenames |
priority |
integer |
✓ | For sort-time access |
toolNames |
string[] |
✓ | First-pass filter before regex matching |
commandRegexSources |
RegexSource[] |
— | Pre-compiled command pattern sources |
pathRegexSources |
RegexSource[] |
— | Pre-compiled path pattern sources (globs converted at build time) |
tags |
string[] |
— | For tag-based scoring |
injection |
string |
✓ | Pre-rendered markdown — the only content read during injection |
summary |
string |
✓ | Fallback if injection exceeds remaining budget |
RegexSource object¶
Regex patterns are stored as { source, flags } pairs rather than regex strings because RegExp is not JSON-serializable. The hook reconstructs them with new RegExp(source, flags).
| Field | Type | Required | Description |
|---|---|---|---|
source |
string |
✓ | Regex source string |
flags |
string |
— | Regex flags (default: "") |
config.schema.json¶
Validates data/config.json.
Schema ID: https://github.com/joeblackwaslike/lessons-learned/schemas/config.schema.json
See the Configuration Reference for full field documentation. The schema enforces:
| Field | Type | Min | Max | Default |
|---|---|---|---|---|
injectionBudgetBytes |
integer |
256 | — | 4096 |
maxLessonsPerInjection |
integer |
1 | 10 | 3 |
minConfidence |
number |
0.0 | 1.0 | 0.5 |
minPriority |
integer |
1 | 10 | 1 |
compactionReinjectionThreshold |
integer |
1 | 10 | 7 |
autoScanIntervalHours |
integer |
1 | — | 24 |
maxCandidatesPerScan |
integer |
1 | — | 50 |
IDE validation¶
All data files include a $schema field pointing to the relevant schema. VS Code and other JSON-aware editors will validate the file on save and provide autocomplete for fields.