https://github.com/michaelsolati/fbschema
A simple library to generate TypeScript definition files as well as Firestore rules based on a JSON Schema definition.
https://github.com/michaelsolati/fbschema
Last synced: 8 months ago
JSON representation
A simple library to generate TypeScript definition files as well as Firestore rules based on a JSON Schema definition.
- Host: GitHub
- URL: https://github.com/michaelsolati/fbschema
- Owner: MichaelSolati
- License: mit
- Created: 2020-12-13T01:08:13.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2025-08-18T17:22:50.000Z (10 months ago)
- Last Synced: 2025-09-17T21:05:39.047Z (9 months ago)
- Language: TypeScript
- Size: 263 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
# fbschema
[](https://www.npmjs.com/package/fbschema)
[](https://bundlephobia.com/result?p=fbschema)
[](https://github.com/MichaelSolati/fbschema/actions?query=workflow%3A%22Deploy+CI%22)
[](https://github.com/MichaelSolati/fbschema/actions?query=workflow%3A%22Lint+and+Test%22)
[](https://github.com/MichaelSolati/fbschema/stargazers)
[](https://github.com/MichaelSolati/fbschema/network/members)
✨ A simple library to generate **TypeScript definition files** as well as **Firestore rules** based on a [JSON Schema](https://json-schema.org/) definition.
## ✨ Features
- Generates **TypeScript interfaces** from JSON Schema files
- Generates **Firestore rules** from JSON Schema files with support for:
- Type validation (`string`, `number`, `integer`, `boolean`, `array`, `object`)
- Required field validation
- Enum value validation
- Number range validation (min/max, exclusive min/max)
- Multiple of validation for integers
- String length validation
- Collection-level access control (`read`, get, `list`, `write`,`create`, `update`, `delete`)
- Property-level validation for `create` and `update` operations based on the JSON Schema file object
## 📦 Installation
```bash
npm install fbschema
```
## 🚀 Usage
### 🛠 CLI
```bash
npx fbschema
```
The CLI will:
1️⃣ Take the current working directory and look for JSON Schema files in the `fbschema` subdirectory 📂
2️⃣ Generate TypeScript interfaces in a `types/fbschema` subdirectory ✍️
3️⃣ Generate Firestore rules in `firestore.rules` 🔒
4️⃣ Show detailed progress logs 📜
### 🏗 Programmatic Usage
```typescript
import fbschema from 'fbschema';
// ✅ Basic usage
await fbschema();
// 📂 With custom working directory
await fbschema({
path: './your-project',
});
// 📢 With logging options
await fbschema({
logs: true, // Enable logging
});
```
## 📁 Directory Structure
By default, the tool expects the following structure:
```txt
your-project/
├── fbschema/ # 📁 Your JSON Schema directory
│ └── *.json # 📜 Your JSON Schema files
├── types/
│ └── fbschema/ # 🏗 Generated TypeScript interfaces
│ ├── index.ts # 📌 Main entry point for the generated types
│ └── *.ts # 🔧 Generated TypeScript files
└── firestore.rules # 🔒 Generated Firestore security rules
```
## 🔒 Firestore Rules Generation
The library generates Firestore security rules based on your JSON Schema definitions. Here's an example of how to define rules in your schema:
```json
{
"title": "User",
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 2,
"maxLength": 50
},
"age": {
"type": "integer",
"minimum": 0,
"maximum": 120
},
"role": {
"type": "string",
"enum": ["admin", "user", "guest"]
}
},
"required": ["name", "age"],
"fbschema": {
"read": "request.auth != null",
"write": "request.auth != null && request.auth.token.admin == true",
"create": "request.auth != null",
"update": "request.auth != null && request.auth.uid == resource.data.userId"
}
}
```
This will generate rules that:
- Validate the data types and constraints
- Ensure required fields are present
- Enforce enum values
- Apply collection-level access control
- Handle create and update operations differently
> [!NOTE]
> The `fbschema` property is a custom extension to the JSON Schema specification. It's not part of the standard JSON Schema but is used by this library to define Firestore-specific security rules. All other properties in the schema follow the standard JSON Schema specification.
>
> Each rule in `fbschema` is a string containing any valid Firestore security rule expression. You can write any condition you want, and it will be directly inserted into the generated rules. If a rule is not specified, it defaults to `false` for security.
>
> The following rules are supported:
>
> - `read`: Controls read access to the collection (combines get and list)
> - `get`: Controls access to individual document reads
> - `list`: Controls access to collection queries
> - `write`: Controls write access to the collection (combines create, update, and delete)
> - `create`: Controls document creation
> - `update`: Controls document updates
> - `delete`: Controls document deletion
>
> Note that `read` and `write` are convenience rules that can be used to control multiple operations at once. If you specify both `read` and `get`/`list`, the more specific rule takes precedence. The same applies to `write` and `create`/`update`/`delete`.
## 📖 fbschema Meta-Schema
This project includes a meta-schema that you can use to validate your `fbschema` files and get autocompletion in supported editors like VS Code. The meta-schema ensures that your schema files adhere to the required structure, including the custom `fbschema` property.
To use the meta-schema, add the `$schema` property to your JSON schema files:
```json
{
"$schema": "https://raw.githubusercontent.com/MichaelSolati/fbschema/main/fbschema.json",
"title": "YourSchema",
"type": "object",
"properties": {
"...": "..."
},
"fbschema": {
"read": true,
"write": false
}
}
```
By adding the `$schema` property, your editor will provide autocompletion and validation for all standard JSON Schema properties as well as the custom `fbschema` rules, making it easier to write valid and secure Firestore rules.
## 🤝 Contributing
🛠 All code should pass tests and be well documented. Also, check out the [Commit Message Guidelines](CONTRIBUTING.md) before submitting your PR.
## ⚖️ License
📜 [MIT](LICENSE.md)