desertthunder.dev
learn and share notes on atproto (wip) 馃
malfestio.stormlightlabs.org/
readability
solid
axum
atproto
srs
1# Lexicon Schemas
2
3This directory contains the Lexicon definitions for the malfestio's public records.
4
5## Protocol + Lexicon Strategy
6
7- "Artifacts" are publishable records (ATProto Lexicon).
8- "Learning state" is private (local DB + your backend sync; not public records).
9- Records are distributed and hard to migrate globally; keep mutable/private state out.
10- Lexicon evolution rules strongly encourage forward-compatible extensibility.
11
12### Namespace + NSID conventions
13
14- `org.stormlightlabs.malfestio.note`
15- `org.stormlightlabs.malfestio.card`
16- `org.stormlightlabs.malfestio.deck`
17- `org.stormlightlabs.malfestio.source.article`
18- `org.stormlightlabs.malfestio.source.lecture`
19- `org.stormlightlabs.malfestio.collection`
20- `org.stormlightlabs.malfestio.thread.comment`
21
22### Lexicon basics
23
24- Lexicon defines record types + XRPC endpoints; JSON-schema-like constraints.
25- Use "optional fields" heavily; avoid enums that will calcify the product too early.
26- Versioning: add fields, don't rename; never rely on being able to rewrite history.
27
28### Schema boundaries (important)
29
30- **Public share layer**:
31 - decks, cards, notes, collections, comments
32- **Private layer**:
33 - review schedule, lapses, grades, per-card performance, streaks
34
35## Publishing Lexicons to AT Protocol Network
36
37### Prerequisites
38
39**Goat CLI**: Install the official AT Protocol CLI tool
40
41```bash
42# macOS
43brew install goat
44```
45
46### Publishing Workflow
47
481. **Validate schemas locally**:
49
50 ```bash
51 goat lexicon lint lexicons/
52 ```
53
542. **Check DNS configuration**:
55
56 ```bash
57 goat lexicon check-dns org.stormlightlabs.malfestio.card
58 ```
59
603. **Publish to network**:
61
62 ```bash
63 goat lexicon publish lexicons/org/stormlightlabs/malfestio/
64 ```
65
66### PDS Validation Modes
67
68AT Protocol PDSs support three lexicon validation modes:
69
701. **Explicit validation required**: Record must validate against schema; fails if PDS doesn't know the lexicon
71 - This is the current mode causing `Lexicon not found` errors
72 - Requires publishing lexicons or using optimistic validation
73
742. **Optimistic validation** (default): Validates if PDS knows the schema, allows creation if unknown
75 - Most flexible for custom lexicons during development
76 - Set via `validate: undefined` in create/update record calls
77
783. **Explicit no validation**: Skips validation even if PDS knows the schema
79 - Set via `validate: false` in create/update record calls
80
81### Version Updates
82
83When updating lexicon schemas:
84
851. **Minor Updates** (additive only):
86 - Add new optional fields
87 - Update descriptions
88 - Add new `knownValues` (don't remove old ones)
89 - Document version with timestamp (use `date +%s` to get Unix timestamp)
90 - Note in changelog: `// Updated: 1735862400 (2026-01-02)`
91
922. **Breaking Changes** (avoid if possible):
93 - Create new lexicon with new NSID (e.g., `org.stormlightlabs.malfestio.cardV2`)
94 - Maintain both versions during migration period
95 - Update code to support both old and new schemas
96 - Document migration path
97
983. **Republishing**:
99
100 ```bash
101 goat lexicon lint lexicons/
102 goat lexicon publish lexicons/org/stormlightlabs/malfestio/
103 ```
104
105## Evolution Rules
106
1071. **Additive Changes Only**: You can add new optional fields to existing records.
1082. **No Renaming**: Do not rename fields.
109 If a semantic change is needed, add a new field and deprecate the old one.
1103. **No Type Changes**: Once published, a field's type is fixed.
1114. **Version by Copying**: If a breaking change is absolutely required, create a new Lexicon with a new major version or a new name (e.g., `org.stormlightlabs.malfestio.noteV2`).