forked from
stavola.xyz/mlf
A human-friendly DSL for ATProto Lexicons
Add mlf generation documentation
+150
-15
+29
-14
README.md
+29
-14
README.md
···
7
7
## What it looks like
8
8
9
9
```mlf
10
-
namespace com.example.post {
11
-
record post {
12
-
text: string constrained {
13
-
maxLength: 3000,
14
-
maxGraphemes: 300,
15
-
},
16
-
createdAt: Datetime,
17
-
reply?: replyRef,
18
-
}
19
-
20
-
alias replyRef = {
21
-
root: com.atproto.repo.strongRef,
22
-
parent: com.atproto.repo.strongRef,
23
-
};
10
+
record post {
11
+
text!: string constrained {
12
+
maxLength: 3000,
13
+
maxGraphemes: 300,
14
+
},
15
+
createdAt!: Datetime,
16
+
reply: replyRef,
24
17
}
18
+
19
+
def type replyRef = {
20
+
root!: com.atproto.repo.strongRef,
21
+
parent!: com.atproto.repo.strongRef,
22
+
};
25
23
```
26
24
27
25
## Getting started
···
68
66
```bash
69
67
mlf validate examples/app.bsky.feed.post.mlf record.json
70
68
```
69
+
70
+
### Convert JSON lexicons to MLF
71
+
72
+
Convert existing ATProto JSON lexicons to MLF format:
73
+
74
+
```bash
75
+
# Convert a single lexicon
76
+
mlf generate mlf -i my-lexicon.json -o ./
77
+
78
+
# Convert multiple lexicons
79
+
mlf generate mlf -i "dist/lexicons/**/*.json" -o src/lexicons/
80
+
```
81
+
82
+
This is useful for:
83
+
- Migrating existing JSON lexicons to the MLF format
84
+
- Learning MLF syntax by comparing JSON and MLF
85
+
- Working with lexicons from external sources
71
86
72
87
## Project layout
73
88
+18
SPEC.md
+18
SPEC.md
···
716
716
mlf generate lexicon --input "**/*.mlf" lexicons/*
717
717
mlf generate example --input "**/*.mlf" --count 5 examples/*
718
718
719
+
# Convert JSON lexicons to MLF
720
+
mlf generate mlf --input "lexicons/**/*.json" --output ./mlf/
721
+
719
722
# Validate lexicons
720
723
mlf validate <files|globs>
721
724
mlf validate "**/*.mlf"
···
726
729
# Validate a record against a lexicon
727
730
mlf check --input app.bsky.feed.post.mlf ./record.json
728
731
```
732
+
733
+
### JSON to MLF Conversion
734
+
735
+
The `mlf generate mlf` command converts ATProto JSON lexicons back to MLF format. This is useful for:
736
+
737
+
- **Migration**: Converting existing JSON lexicons to MLF
738
+
- **Interoperability**: Working with lexicons from external sources
739
+
- **Learning**: Seeing how JSON lexicons map to MLF syntax
740
+
- **Comparison**: Generating MLF from JSON to compare with hand-written MLF
741
+
742
+
The converter automatically:
743
+
- Converts format strings (did, datetime, handle) to prelude types (Did, Datetime, Handle)
744
+
- Properly formats required (`!`) and optional (default) fields
745
+
- Converts `namespace#name` references to `namespace.name` notation
746
+
- Generates clean, properly indented MLF with correct syntax
729
747
730
748
## Examples
731
749
+89
website/content/docs/cli.md
+89
website/content/docs/cli.md
···
235
235
236
236
---
237
237
238
+
### `mlf generate mlf`
239
+
240
+
Convert ATProto JSON lexicons back to MLF format.
241
+
242
+
```bash
243
+
mlf generate mlf --output <OUTPUT> [OPTIONS]
244
+
```
245
+
246
+
**Options:**
247
+
- `-i, --input <INPUT>` - Input JSON lexicon files (glob patterns supported, can be specified multiple times)
248
+
- `-o, --output <OUTPUT>` - Output directory (required)
249
+
250
+
**Examples:**
251
+
252
+
```bash
253
+
# Convert a single JSON lexicon to MLF
254
+
mlf generate mlf -i com.example.thread.json -o ./lexicons/
255
+
# Creates: lexicons/com/example/thread.mlf
256
+
257
+
# Convert multiple JSON lexicons
258
+
mlf generate mlf -i lexicon1.json -i lexicon2.json -o ./mlf/
259
+
260
+
# Convert using glob pattern
261
+
mlf generate mlf -i "dist/lexicons/**/*.json" -o ./src/
262
+
```
263
+
264
+
**Features:**
265
+
266
+
- **Smart type conversion** - Automatically converts format strings (did, datetime, handle) to prelude types (Did, Datetime, Handle)
267
+
- **Proper formatting** - Generates clean, properly indented MLF with correct syntax
268
+
- **Reference conversion** - Converts `namespace#name` refs to `namespace.name` notation
269
+
- **Complete coverage** - Supports records, queries, procedures, subscriptions, tokens, and type definitions
270
+
271
+
**Input format:**
272
+
273
+
The JSON lexicon must be a valid ATProto lexicon with:
274
+
- `lexicon: 1` version field
275
+
- `id` field containing the namespace
276
+
- `defs` object with type definitions
277
+
278
+
**Example:**
279
+
280
+
Given a JSON lexicon:
281
+
```json
282
+
{
283
+
"lexicon": 1,
284
+
"id": "com.example.thread",
285
+
"defs": {
286
+
"main": {
287
+
"type": "record",
288
+
"key": "tid",
289
+
"record": {
290
+
"type": "object",
291
+
"required": ["title", "createdAt"],
292
+
"properties": {
293
+
"title": {
294
+
"type": "string",
295
+
"maxLength": 200
296
+
},
297
+
"createdAt": {
298
+
"type": "string",
299
+
"format": "datetime"
300
+
}
301
+
}
302
+
}
303
+
}
304
+
}
305
+
}
306
+
```
307
+
308
+
Generates MLF:
309
+
```mlf
310
+
record main {
311
+
title!: string constrained {
312
+
maxLength: 200,
313
+
},
314
+
createdAt!: Datetime,
315
+
};
316
+
```
317
+
318
+
**Use cases:**
319
+
320
+
- **Migration** - Convert existing JSON lexicons to MLF format
321
+
- **Interoperability** - Work with lexicons from other tools or repositories
322
+
- **Comparison** - Generate MLF from JSON to compare with hand-written MLF
323
+
- **Learning** - See how JSON lexicons translate to MLF syntax
324
+
325
+
---
326
+
238
327
## Error Messages
239
328
240
329
MLF provides rich error messages with:
+14
-1
website/content/docs/getting-started.md
+14
-1
website/content/docs/getting-started.md
···
81
81
mlf validate thread.mlf record.json
82
82
```
83
83
84
+
## Convert JSON Lexicons to MLF
85
+
86
+
Already have ATProto JSON lexicons? Convert them to MLF format:
87
+
88
+
```bash
89
+
mlf generate mlf -i my-lexicon.json -o ./
90
+
```
91
+
92
+
This is useful for:
93
+
- Migrating existing lexicons to MLF
94
+
- Learning MLF syntax by seeing JSON conversions
95
+
- Working with lexicons from other sources
96
+
84
97
## Next Steps
85
98
86
-
- Read the [Syntax Guide](./syntax.md) to learn the MLF language
99
+
- Read the [Language Guide](./language-guide/) to learn the MLF language
87
100
- Check out the [CLI Reference](./cli.md) for all commands
88
101
- Try the [WASM API](./wasm.md) to use MLF in the browser