Barazo lexicon schemas and TypeScript types
barazo.forum
📝 docs: rewrite README with comprehensive schema reference (#9)
Restructure README to lead with what the package provides,
add a schema reference table for all lexicon IDs, and expand
code examples to cover all four record types and Zod schemas.
authored by
Guido X Jansen
and committed by
GitHub
e29093c3
af27d21b
+54
-54
+54
-54
README.md
+54
-54
README.md
···
1
-
# @barazo-forum/lexicons
1
+
# Barazo Lexicons
2
2
3
-
AT Protocol lexicon schemas and generated TypeScript types for the Barazo forum platform. Defines the `forum.barazo.*` namespace with record types for topics, replies, reactions, and user preferences.
3
+
AT Protocol lexicon schemas and generated TypeScript types for the Barazo forum platform.
4
4
5
-
**Status:** Alpha -- All MVP lexicon schemas defined, published to GitHub Packages
5
+
6
6
7
7
## What is this?
8
8
9
-
Lexicons are AT Protocol schemas that define the data model for Barazo forums. They specify what a topic, reply, reaction, and user preferences record looks like in the AT Protocol ecosystem. These schemas are the contract between the user's PDS (Personal Data Server) and the Barazo AppView, ensuring all forum data is portable and interoperable.
9
+
[Lexicons](https://atproto.com/specs/lexicon) are the schema language of the AT Protocol. They define how data is structured, validated, and exchanged across the decentralized network. Every record stored on a user's PDS (Personal Data Server) must conform to a lexicon schema.
10
10
11
-
This package provides:
11
+
This package defines the `forum.barazo.*` namespace -- the data contract between a user's PDS and any Barazo AppView. Because the schemas live on the protocol layer, all forum data (topics, replies, reactions, preferences) is portable: users own their data and can move between AppViews without loss.
12
+
13
+
The package provides:
14
+
12
15
- JSON lexicon schema files (the source of truth)
13
16
- Generated TypeScript types with type guards and validators
14
17
- Zod validation schemas for runtime input validation
15
-
- Lexicon IDs as constants
18
+
- Lexicon ID constants
16
19
17
-
## Installation
18
-
19
-
For npm consumers outside the workspace, configure GitHub Packages access in `.npmrc`:
20
-
21
-
```
22
-
@barazo-forum:registry=https://npm.pkg.github.com
23
-
```
24
-
25
-
Then install:
26
-
27
-
```bash
28
-
pnpm add @barazo-forum/lexicons
29
-
```
20
+
## Lexicon Schemas
30
21
31
-
For workspace consumers (`barazo-api`, `barazo-web`): already linked via pnpm workspace.
22
+
| Lexicon ID | Description | Key |
23
+
|---|---|---|
24
+
| `forum.barazo.topic.post` | Forum topic with title, markdown content, community, category, tags, and optional self-labels | `tid` |
25
+
| `forum.barazo.topic.reply` | Threaded reply to a topic or another reply, with root and parent references | `tid` |
26
+
| `forum.barazo.interaction.reaction` | Reaction to a topic or reply (e.g., like, heart), scoped to a community's configured set | `tid` |
27
+
| `forum.barazo.actor.preferences` | User-level moderation and safety preferences: maturity filter, muted words, blocked/muted accounts, cross-post defaults | `literal:self` |
28
+
| `forum.barazo.authForumAccess` | OAuth permission set granting repo access to all Barazo record collections | -- |
29
+
| `forum.barazo.defs` | Shared type definitions (reserved for future reusable types) | -- |
32
30
33
-
## Usage
31
+
## Package Exports
34
32
35
33
### Generated Types
36
34
37
35
```typescript
38
-
import { ForumBarazoTopicPost } from "@barazo-forum/lexicons";
36
+
import {
37
+
ForumBarazoTopicPost,
38
+
ForumBarazoTopicReply,
39
+
ForumBarazoInteractionReaction,
40
+
ForumBarazoActorPreferences,
41
+
} from "@barazo-forum/lexicons";
39
42
40
-
// Type for a topic post record
43
+
// Record type
41
44
type Post = ForumBarazoTopicPost.Record;
42
45
43
46
// Type guard
···
45
48
console.log(record.title);
46
49
}
47
50
48
-
// Validate against lexicon schema
51
+
// Lexicon validation
49
52
const result = ForumBarazoTopicPost.validateRecord(record);
50
53
```
51
54
52
-
### Zod Validation
55
+
### Zod Validation Schemas
53
56
54
57
```typescript
55
-
import { topicPostSchema } from "@barazo-forum/lexicons";
58
+
import {
59
+
topicPostSchema,
60
+
topicReplySchema,
61
+
reactionSchema,
62
+
actorPreferencesSchema,
63
+
} from "@barazo-forum/lexicons";
56
64
57
65
const result = topicPostSchema.safeParse(input);
58
66
if (result.success) {
···
60
68
}
61
69
```
62
70
63
-
### Lexicon IDs
71
+
### Lexicon ID Constants
64
72
65
73
```typescript
66
74
import { LEXICON_IDS, ids } from "@barazo-forum/lexicons";
67
75
68
-
LEXICON_IDS.TopicPost // "forum.barazo.topic.post"
69
-
ids.ForumBarazoTopicPost // "forum.barazo.topic.post"
76
+
LEXICON_IDS.TopicPost // "forum.barazo.topic.post"
77
+
LEXICON_IDS.TopicReply // "forum.barazo.topic.reply"
78
+
LEXICON_IDS.Reaction // "forum.barazo.interaction.reaction"
79
+
LEXICON_IDS.ActorPreferences // "forum.barazo.actor.preferences"
80
+
LEXICON_IDS.AuthForumAccess // "forum.barazo.authForumAccess"
70
81
```
71
82
72
83
### Raw Lexicon Schemas
···
76
87
// Array of LexiconDoc objects for all forum.barazo.* schemas
77
88
```
78
89
79
-
### Permission Set (OAuth Scopes)
90
+
## Installation
80
91
81
-
The package includes a permission set lexicon for AT Protocol OAuth. When the protocol's permission set system is fully deployed, clients will request `include:forum.barazo.authForumAccess` as an OAuth scope instead of `transition:generic`.
92
+
Configure GitHub Packages access in `.npmrc`:
82
93
83
-
```typescript
84
-
import { LEXICON_IDS } from "@barazo-forum/lexicons";
85
-
86
-
LEXICON_IDS.AuthForumAccess // "forum.barazo.authForumAccess"
87
94
```
88
-
89
-
The permission set declares `repo` access for all four record collections. Blob permissions (for future media attachments) must be requested separately per the AT Protocol spec.
90
-
91
-
## Record Types
95
+
@barazo-forum:registry=https://npm.pkg.github.com
96
+
```
92
97
93
-
| Lexicon ID | Description | Key Type |
94
-
|------------|-------------|----------|
95
-
| `forum.barazo.topic.post` | Forum topic/thread (title, content, community, category, tags, labels) | `tid` |
96
-
| `forum.barazo.topic.reply` | Reply to a topic (content, root ref, parent ref, community) | `tid` |
97
-
| `forum.barazo.interaction.reaction` | Reaction to content (subject ref, type, community) | `tid` |
98
-
| `forum.barazo.actor.preferences` | User preferences singleton (maturity level, muted words, blocked DIDs, cross-post defaults) | `literal:self` |
98
+
Then install:
99
99
100
-
## Permission Set
100
+
```bash
101
+
pnpm add @barazo-forum/lexicons
102
+
```
101
103
102
-
| Lexicon ID | Description |
103
-
|------------|-------------|
104
-
| `forum.barazo.authForumAccess` | OAuth permission set granting repo access to all Barazo record collections |
104
+
Workspace consumers (`barazo-api`, `barazo-web`) are already linked via pnpm workspace.
105
105
106
106
## Development
107
107
108
108
```bash
109
109
pnpm install
110
-
pnpm test # Run tests
110
+
pnpm test # Run tests (74 tests across 3 suites)
111
111
pnpm build # Compile TypeScript
112
112
pnpm generate # Regenerate types from lexicon JSON
113
113
pnpm lint # Lint
···
116
116
117
117
## Related Repositories
118
118
119
-
- **[barazo-api](https://github.com/barazo-forum/barazo-api)** -- Backend (AGPL-3.0)
120
-
- **[barazo-web](https://github.com/barazo-forum/barazo-web)** -- Frontend (MIT)
121
-
- **[barazo-deploy](https://github.com/barazo-forum/barazo-deploy)** -- Deployment templates (MIT)
122
-
- **[Organization](https://github.com/barazo-forum)** -- All repos
119
+
- [barazo-api](https://github.com/barazo-forum/barazo-api) -- AppView backend (AGPL-3.0)
120
+
- [barazo-web](https://github.com/barazo-forum/barazo-web) -- Forum frontend (MIT)
121
+
- [barazo-deploy](https://github.com/barazo-forum/barazo-deploy) -- Docker Compose deployment templates (MIT)
122
+
- [barazo-forum](https://github.com/barazo-forum) -- GitHub organization
123
123
124
124
## License
125
125