atproto_sdl

Alpha, pre-release. Grammar, CLI flags, and printed output are all subject to change; expect breaking changes between 0.x releases.

A Prisma/GraphQL-inspired schema language for atproto lexicons (“Lexicon SDL”), parsing to and printing from atproto_lexicon’s AST. The printer is total: every AST construct has a spelling, so lexicon JSON round-trips through SDL with zero exception files.

/// A forum-style shelf entry.
record shelfEntry @key(tid) {
  title: String! @len(1, 200)
  tags: [String @len(max: 64)] @max(10)
  createdAt: Datetime!
}

query listReleases(q: String, limit: Int = 25 @range(1, 100)): releasePage
  throws NotFound | Expired

Authoring sugar, expanding at compile time to plain inline lexicon JSON (never a $ref, never a new def):

scalar Text64 = String @len(max: 640) @graphemes(max: 64)
values Grade = "M" | "NM" | "VG+"

record entry {
  ...dev.example.crate.defs#releaseDisplay
  title: Text64!
  mediaGrade: String @known(Grade)
}

Cross-file spreads and sugar references resolve during tree-wide compilation (atproto_sdl.parse_all, or the CLI, which registers every file in the tree).

Installation

gleam add atproto_sdl

Usage

CLI, converting a tree of .sdl/.json files to the other format (NSID derives from the file path; --to json|sdl restricts direction):

gleam run -m atproto_sdl -- <src-dir> <out-dir> [--to json|sdl]

Library:

import atproto_sdl
import atproto_lexicon/encoding

let assert Ok(doc) = atproto_sdl.parse(source, "com.example.thing")
let sdl_text = atproto_sdl.print(doc)
let json_text = encoding.to_json_string(doc)

Tree-wide, for ... spreads and dotted sugar refs that cross files:

import atproto_sdl

let results = atproto_sdl.parse_all(sdl_sources, json_docs)

Architecture

Text -> lexer -> parser (intermediate tree) -> lower -> ast.LexiconDoc -> printer -> text.

Corpus status: 38/38 at-record lexicons and 25/25 vendored corpus files round-trip decode -> print -> parse, print-idempotent (gleam test).