An ecosystem for generating realistic JSON data using declarative schema definitions. This repository contains both the core library and command-line tool for working with JGD (JSON Generator Definition) schemas.
The core Rust library that powers JSON data generation. See jgd-rs README for detailed documentation, API reference, and usage examples.
A command-line interface for generating JSON data from JGD schema files.
The JavaScript library that powers JSON data generation. See jgd.js README for detailed documentation, API reference, and usage examples.
JGD (JSON Generator Definition) is a declarative schema format for generating realistic fake JSON data. It allows you to:
- Define complex data structures with relationships
- Generate deterministic or random data sets
- Create cross-references between entities
- Use faker patterns for realistic data
- Support multiple locales and languages
- Generate arrays with flexible counts
- Create optional fields with probability control
JGD schemas are JSON documents that describe how to generate data. Here's the basic structure:
{
"$format": "jgd/v1",
"version": "1.0.0",
"seed": 42,
"defaultLocale": "EN",
"root": {
"fields": {
"id": "${ulid}",
"name": "${name.name}",
"email": "${internet.safeEmail}",
"age": {
"number": {
"min": 18,
"max": 65,
"integer": true
}
}
}
}
}The repository includes a comprehensive JSON Schema for validation:
This schema can be used with any JSON Schema validator or IDE that supports schema validation to ensure your JGD files are correctly formatted.
You can reference the schema directly in your JGD files for IDE support:
{
"$schema": "https://raw.githubusercontent.com/lvendrame/jgd-rs/refs/heads/main/schema/jgd.schema.json",
"$format": "jgd/v1",
"version": "1.0.0",
...
}Add to your Cargo.toml:
[dependencies]
jgd-rs = "0.1.0"Generate data in your Rust code:
use jgd_rs::generate_jgd_from_str;
let schema = r#"{
"$format": "jgd/v1",
"version": "1.0.0",
"root": {
"fields": {
"name": "${name.firstName}",
"email": "${internet.safeEmail}"
}
}
}"#;
let json_data = generate_jgd_from_str(schema);
println!("{}", serde_json::to_string_pretty(&json_data).unwrap());Build and run the CLI tool:
# Build the project
cargo build --release
# Run with a schema file
./target/release/jgd-rs-cli path/to/schema.jgd- Root Mode: Generate a single entity (object or array)
- Entities Mode: Generate multiple named entities with relationships
- Primitives: Strings, numbers, booleans, null
- Template Strings:
"${faker.pattern}"for dynamic data - Number Generation: Min/max ranges with integer/float support
- Arrays: Variable or fixed-count collections
- Optional Fields: Probability-based field inclusion
- Cross-references: Link data between entities
- Nested Objects: Complex hierarchical structures
Over 100+ faker patterns across categories:
- Address: Cities, countries, coordinates, postal codes
- Names: First/last names, titles, full names
- Internet: Emails, domains, IPs, user agents
- Company: Business names, buzzwords, industries
- Lorem: Words, sentences, paragraphs
- Time/Date: Timestamps, durations, date ranges
- Finance: Credit cards, currencies, banking codes
- And many more...
$format: Always "jgd/v1"version: User-defined schema version- Either
rootORentities(mutually exclusive)
seed: Random seed for deterministic generationdefaultLocale: Locale for faker data (EN, FR_FR, DE_DE, etc.)
{
"$format": "jgd/v1",
"version": "1.0.0",
"root": {
"fields": {
"id": "${ulid}",
"name": "${name.name}",
"email": "${internet.safeEmail}",
"age": {
"number": {
"min": 18,
"max": 65,
"integer": true
}
},
"active": true
}
}
}{
"$format": "jgd/v1",
"version": "1.0.0",
"entities": {
"users": {
"count": 5,
"fields": {
"id": "${ulid}",
"name": "${name.name}",
"email": "${internet.safeEmail}"
}
},
"posts": {
"count": [10, 20],
"fields": {
"id": "${uuid.v4}",
"authorId": {
"ref": "users.id"
},
"title": "${lorem.sentence(3,8)}",
"content": "${lorem.paragraphs(2,4)}"
}
}
}
}The repository includes several example schema files:
single-object-root.jgd- Simple single object generationarray-object-root.jgd- Array of objects generationranged-array-object-root.jgd- Variable count arraysuser-post-entities.jgd- Multi-entity relationships
# Build all components
cargo build
# Build with optimizations
cargo build --release
# Run tests
cargo test
# Run specific component
cargo run --bin jgd-rs-cli -- examples/single-object-root.jgdjgd-rs/
├── jgd-rs/ # Core library
│ ├── src/ # Library source code
│ ├── examples/ # Example JGD schema files
│ ├── schema/ # JSON Schema definition
│ └── README.md # Detailed library documentation
├── jgd-rs-cli/ # Command-line tool
│ └── src/ # CLI source code
└── README.md # This file
Generate locale-specific data with these supported locales:
EN- English (default)FR_FR- French (France)DE_DE- German (Germany)IT_IT- Italian (Italy)PT_BR- Portuguese (Brazil)JA_JP- Japanese (Japan)AR_SA- Arabic (Saudi Arabia)CY_GB- Welsh (Great Britain)
- Library Documentation - Complete API reference and usage guide
- JSON Schema - Formal schema definition for validation
- Examples - Sample JGD schema files
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
This project is licensed under the MIT License - see the LICENSE file for details.
For the best development experience, use an IDE that supports JSON Schema validation:
- VS Code: Install a JSON Schema extension
- IntelliJ IDEA: Built-in JSON Schema support
- Vim/Neovim: Use a JSON Schema plugin
Add the schema reference to your JGD files:
{
"$schema": "https://raw.githubusercontent.com/lvendrame/jgd-rs/refs/heads/main/jgd-rs/schema/jgd.schema.json",
"$format": "jgd/v1",
...
}You can validate your JGD schemas using online JSON Schema validators:
Just paste the schema URL and your JGD content.