Lexicon Migrations #7

New issue

Closed

opened 2026-02-22 22:51:00 +00:00 by Grandiras · 0 comments

Grandiras commented

2026-02-22 22:51:00 +00:00

Owner

Lexicon Migrations

Support automatically updating lexicon entries when the model changes. Allows for easier iteration over lexicons during development and when adding new features.

Current State

The atproto-lexgen tool already supports bidirectional codegen (C# to Lexicon JSON and Lexicon JSON to C#), and LexiconDocument has a Revision field. But there is no migration/diff tracking yet.

Implementation Plan

1. `lexicon diff` command

Compare the current assembly types against previously-generated Lexicon JSON files:

Detect added/removed/changed properties
Detect added/removed definitions
Report breaking vs non-breaking changes

2. Schema evolution validation

Enforce AT Protocol Lexicon evolution rules:

Only optional fields can be added
Fields cannot be removed or renamed
Types cannot change
Breaking changes require a new NSID

3. Automatic revision bumping

When a non-breaking change is detected, auto-increment the revision field in the Lexicon JSON.

4. Migration report

Generate a human-readable migration report showing what changed between versions.

References

Lexicon Evolution spec
Similar to goat lex diffing/linting in the reference TS SDK

## Lexicon Migrations Support automatically updating lexicon entries when the model changes. Allows for easier iteration over lexicons during development and when adding new features. ### Current State The `atproto-lexgen` tool already supports bidirectional codegen (C# to Lexicon JSON and Lexicon JSON to C#), and `LexiconDocument` has a `Revision` field. But there is no migration/diff tracking yet. ### Implementation Plan #### 1. `lexicon diff` command Compare the current assembly types against previously-generated Lexicon JSON files: - Detect added/removed/changed properties - Detect added/removed definitions - Report breaking vs non-breaking changes #### 2. Schema evolution validation Enforce AT Protocol Lexicon evolution rules: - Only optional fields can be added - Fields cannot be removed or renamed - Types cannot change - Breaking changes require a new NSID #### 3. Automatic revision bumping When a non-breaking change is detected, auto-increment the `revision` field in the Lexicon JSON. #### 4. Migration report Generate a human-readable migration report showing what changed between versions. ### References - [Lexicon Evolution spec](https://atproto.com/specs/lexicon#lexicon-evolution) - Similar to `goat lex` diffing/linting in the reference TS SDK