Barazo lexicon schemas and TypeScript types
barazo.forum
Merge pull request #10 from barazo-forum/docs/standardize-readme
Standardize README to match org-wide template
authored by
Guido X Jansen
and committed by
GitHub
d652db8b
e29093c3
+62
-21
+62
-21
README.md
+62
-21
README.md
···
1
+
<div align="center">
2
+
3
+
<picture>
4
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/barazo-forum/.github/main/assets/logo-dark.svg">
5
+
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/barazo-forum/.github/main/assets/logo-light.svg">
6
+
<img alt="Barazo Logo" src="https://raw.githubusercontent.com/barazo-forum/.github/main/assets/logo-dark.svg" width="120">
7
+
</picture>
8
+
1
9
# Barazo Lexicons
2
10
3
-
AT Protocol lexicon schemas and generated TypeScript types for the Barazo forum platform.
11
+
**AT Protocol lexicon schemas and generated TypeScript types for the `forum.barazo.*` namespace.**
12
+
13
+
[]()
14
+
[](https://opensource.org/licenses/MIT)
15
+
[](https://github.com/barazo-forum/barazo-lexicons/actions/workflows/ci.yml)
16
+
[](https://nodejs.org/)
17
+
[](https://www.typescriptlang.org/)
4
18
5
-
19
+
</div>
6
20
7
-
## What is this?
21
+
---
22
+
23
+
## Overview
8
24
9
25
[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
26
11
27
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
28
13
-
The package provides:
14
-
15
-
- JSON lexicon schema files (the source of truth)
16
-
- Generated TypeScript types with type guards and validators
17
-
- Zod validation schemas for runtime input validation
18
-
- Lexicon ID constants
29
+
---
19
30
20
31
## Lexicon Schemas
21
32
···
28
39
| `forum.barazo.authForumAccess` | OAuth permission set granting repo access to all Barazo record collections | -- |
29
40
| `forum.barazo.defs` | Shared type definitions (reserved for future reusable types) | -- |
30
41
42
+
---
43
+
31
44
## Package Exports
32
45
33
-
### Generated Types
46
+
**Generated Types:**
34
47
35
48
```typescript
36
49
import {
···
52
65
const result = ForumBarazoTopicPost.validateRecord(record);
53
66
```
54
67
55
-
### Zod Validation Schemas
68
+
**Zod Validation Schemas:**
56
69
57
70
```typescript
58
71
import {
···
68
81
}
69
82
```
70
83
71
-
### Lexicon ID Constants
84
+
**Lexicon ID Constants:**
72
85
73
86
```typescript
74
87
import { LEXICON_IDS, ids } from "@barazo-forum/lexicons";
···
80
93
LEXICON_IDS.AuthForumAccess // "forum.barazo.authForumAccess"
81
94
```
82
95
83
-
### Raw Lexicon Schemas
96
+
**Raw Lexicon Schemas:**
84
97
85
98
```typescript
86
99
import { schemas } from "@barazo-forum/lexicons";
87
100
// Array of LexiconDoc objects for all forum.barazo.* schemas
88
101
```
89
102
90
-
## Installation
103
+
---
104
+
105
+
## Quick Start
106
+
107
+
**Prerequisites:** Node.js 24 LTS, pnpm.
91
108
92
109
Configure GitHub Packages access in `.npmrc`:
93
110
···
95
112
@barazo-forum:registry=https://npm.pkg.github.com
96
113
```
97
114
98
-
Then install:
115
+
Install:
99
116
100
117
```bash
101
118
pnpm add @barazo-forum/lexicons
···
103
120
104
121
Workspace consumers (`barazo-api`, `barazo-web`) are already linked via pnpm workspace.
105
122
123
+
---
124
+
106
125
## Development
107
126
108
127
```bash
109
128
pnpm install
110
-
pnpm test # Run tests (74 tests across 3 suites)
129
+
pnpm test # Run tests
111
130
pnpm build # Compile TypeScript
112
131
pnpm generate # Regenerate types from lexicon JSON
113
132
pnpm lint # Lint
114
133
pnpm typecheck # Type check
115
134
```
116
135
136
+
See [CONTRIBUTING.md](https://github.com/barazo-forum/.github/blob/main/CONTRIBUTING.md) for branching strategy, commit format, and code review process.
137
+
138
+
---
139
+
117
140
## Related Repositories
118
141
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
142
+
| Repository | Description | License |
143
+
|------------|-------------|---------|
144
+
| [barazo-api](https://github.com/barazo-forum/barazo-api) | AppView backend (Fastify, firehose, REST API) | AGPL-3.0 |
145
+
| [barazo-web](https://github.com/barazo-forum/barazo-web) | Forum frontend (Next.js, Tailwind) | MIT |
146
+
| [barazo-deploy](https://github.com/barazo-forum/barazo-deploy) | Docker Compose deployment templates | MIT |
147
+
| [barazo-website](https://github.com/barazo-forum/barazo-website) | Marketing + documentation site | MIT |
148
+
149
+
---
150
+
151
+
## Community
152
+
153
+
- **Website:** [barazo.forum](https://barazo.forum)
154
+
- **Discussions:** [GitHub Discussions](https://github.com/orgs/barazo-forum/discussions)
155
+
- **Issues:** [Report bugs](https://github.com/barazo-forum/barazo-lexicons/issues)
156
+
157
+
---
123
158
124
159
## License
125
160
126
-
MIT
161
+
**MIT** -- Protocol schemas should be freely usable by anyone building on the AT Protocol.
162
+
163
+
See [LICENSE](LICENSE) for full terms.
164
+
165
+
---
166
+
167
+
(c) 2026 Barazo