json-schema-validator-core 1.0.0

# JSON Schema Validator Core

[![Crates.io](https://img.shields.io/crates/v/json-schema-validator-core)](https://crates.io/crates/json-schema-validator-core)
[![Documentation](https://docs.rs/json-schema-validator-core/badge.svg)](https://docs.rs/json-schema-validator-core)
[![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](LICENSE)
[![Build Status](https://github.com/rust-core-libs/json-schema-validator-core/workflows/CI/badge.svg)](https://github.com/rust-core-libs/json-schema-validator-core/actions)

A lightning-fast JSON Schema validation library written in Rust with comprehensive error reporting and multi-language bindings support. Designed for high-performance applications requiring strict JSON validation with detailed, actionable error messages.

## Features

- **Lightning Fast** - Optimized Rust implementation with minimal allocations
- **Comprehensive Validation** - Full JSON Schema Draft 7 support (with Draft 4, 6, 2019-09, 2020-12 features)
- **Detailed Error Messages** - Rich error context with instance paths, schema paths, and custom messages
- **Custom Formats** - Extensible format validation system
- **Custom Keywords** - Support for custom validation keywords
- **Multi-Language Support** - C FFI and WebAssembly bindings
- **Memory Safe** - Built with Rust's safety guarantees
- **Zero Dependencies** - Core validation logic uses minimal external dependencies
- **Format Validation** - Built-in support for email, URI, date, datetime, IPv4, IPv6, UUID formats

## Quick Start

### Rust Usage

Add this to your `Cargo.toml`:

```toml
[dependencies]
json-schema-validator-core = "1.0.0"
```

Basic example:

```rust
use json_schema_validator_core::{JsonSchemaValidator, ValidationOptions};
use serde_json::json;

fn main() {
    let schema = json!({
        "type": "object",
        "properties": {
            "name": {"type": "string", "minLength": 1},
            "age": {"type": "integer", "minimum": 0, "maximum": 150},
            "email": {"type": "string", "format": "email"}
        },
        "required": ["name", "age"]
    });

    let instance = json!({
        "name": "John Doe",
        "age": 30,
        "email": "john@example.com"
    });

    let options = ValidationOptions::default();
    let validator = JsonSchemaValidator::new(schema, options).unwrap();
    
    if validator.is_valid(&instance) {
        println!("✅ Valid JSON!");
    } else {
        let errors = validator.validate(&instance);
        for error in errors {
            println!("❌ {}: {}", error.instance_path, error.message);
        }
    }
}
```

### Advanced Configuration

```rust
use json_schema_validator_core::{JsonSchemaValidator, ValidationOptions, SchemaDraft};
use std::collections::HashMap;

let mut custom_formats = HashMap::new();
custom_formats.insert("phone".to_string(), |s: &str| -> bool {
    s.len() >= 10 && s.chars().all(|c| c.is_ascii_digit() || c == '-' || c == ' ')
});

let options = ValidationOptions {
    draft: SchemaDraft::Draft7,
    custom_formats,
    short_circuit: false, // Collect all errors
    collect_annotations: true,
    ..Default::default()
};

let schema = json!({
    "type": "object",
    "properties": {
        "phone": {"type": "string", "format": "phone"}
    }
});

let validator = JsonSchemaValidator::new(schema, options).unwrap();
```

### C FFI Usage

Build the shared library:

```bash
cargo build --release
```

Use in C/C++:

```c
#include <stdio.h>
#include <stdlib.h>

extern char* validate_json_simple(const char* schema_json, const char* instance_json);
extern void free_string(char* ptr);

int main() {
    const char* schema = "{\"type\": \"string\", \"minLength\": 3}";
    const char* instance = "\"hi\"";
    
    char* errors = validate_json_simple(schema, instance);
    if (errors) {
        printf("Validation errors: %s\n", errors);
        free_string(errors);
    }
    
    return 0;
}
```

### WebAssembly Usage

```javascript
import init, { wasm_validate_json, wasm_is_valid } from './pkg/json_schema_validator_core.js';

async function validateJson() {
    await init();
    
    const schema = JSON.stringify({
        type: "object",
        properties: {
            name: { type: "string" },
            age: { type: "integer", minimum: 0 }
        },
        required: ["name"]
    });
    
    const instance = JSON.stringify({ name: "Alice", age: 25 });
    
    const isValid = wasm_is_valid(schema, instance);
    console.log("Is valid:", isValid);
    
    if (!isValid) {
        const errors = JSON.parse(wasm_validate_json(schema, instance));
        console.log("Errors:", errors);
    }
}
```

## Validation Features

### Type Validation
- `null`, `boolean`, `integer`, `number`, `string`, `array`, `object`
- Support for multiple types: `{"type": ["string", "null"]}`

### String Validation
- `minLength` / `maxLength` - Length constraints
- `pattern` - Regular expression matching
- `format` - Built-in format validation (email, uri, date, datetime, ipv4, ipv6, uuid)

### Number Validation
- `minimum` / `maximum` - Value constraints
- `exclusiveMinimum` / `exclusiveMaximum` - Exclusive bounds
- `multipleOf` - Divisibility constraints

### Array Validation
- `minItems` / `maxItems` - Length constraints
- `uniqueItems` - Uniqueness enforcement
- `items` - Item schema validation
- `additionalItems` - Additional item handling

### Object Validation
- `minProperties` / `maxProperties` - Property count constraints
- `required` - Required property enforcement
- `properties` - Property schema validation
- `additionalProperties` - Additional property handling
- `patternProperties` - Pattern-based property validation

### Generic Validation
- `enum` - Enumeration validation
- `const` - Constant value validation
- `allOf` / `anyOf` / `oneOf` - Schema composition
- `not` - Schema negation

## Error Structure

Each validation error provides detailed context:

```rust
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ValidationError {
    pub instance_path: String,    // JSONPointer to the invalid data
    pub schema_path: String,      // JSONPointer to the failing schema
    pub keyword: String,          // The failing keyword (e.g., "minLength")
    pub message: String,          // Human-readable error message
    pub instance_value: Option<Value>, // The invalid value
    pub schema_value: Option<Value>,   // The schema constraint
}
```

Example error output:

```json
[
  {
    "instance_path": "/user/age",
    "schema_path": "/properties/user/properties/age/minimum",
    "keyword": "minimum",
    "message": "Value -5 is less than minimum 0",
    "instance_value": -5,
    "schema_value": 0
  }
]
```

## Performance

Optimized for high-throughput applications:

- **Schema Compilation** - Pre-compile schemas for faster validation
- **Memory Efficiency** - Minimal allocations during validation
- **Early Exit** - Optional short-circuit mode for faster validation
- **Regex Caching** - Compiled regex patterns are cached

Benchmark results on a modern CPU:
- Simple object validation: ~2M validations/second
- Complex nested validation: ~500K validations/second
- Large array validation: ~1M items/second

## Schema Draft Support

| Feature | Draft 4 | Draft 6 | Draft 7 | 2019-09 | 2020-12 |
|---------|---------|---------|---------|---------|---------|
| Core Keywords | ✅ | ✅ | ✅ | ✅ | ✅ |
| Format Validation | ✅ | ✅ | ✅ | ✅ | ✅ |
| Schema Composition | ✅ | ✅ | ✅ | ✅ | ✅ |
| Conditional Schemas | ❌ | ❌ | ✅ | ✅ | ✅ |
| Annotations | ❌ | ❌ | ✅ | ✅ | ✅ |

## Multi-Language Bindings

### Planned Language Support

- **JavaScript/TypeScript** - WebAssembly bindings ✅
- **Python** - PyO3 bindings (planned)
- **Go** - CGO bindings (planned)
- **Java** - JNI bindings (planned)
- **C#/.NET** - P/Invoke bindings (planned)
- **Node.js** - Native addon (planned)

### FFI Safety

All exports are designed with safety in mind:

- Null pointer validation
- UTF-8 string validation
- Proper memory management
- Clear error handling
- Thread-safe operations

## Building

### Requirements

- Rust 1.70 or later
- Cargo

### Development Build

```bash
git clone https://github.com/rust-core-libs/json-schema-validator-core.git
cd json-schema-validator-core
cargo build
```

### Release Build

```bash
cargo build --release
```

### WebAssembly Build

```bash
wasm-pack build --target web
```

### Running Tests

```bash
cargo test
```

### Running Benchmarks

```bash
cargo bench
```

### Building Documentation

```bash
cargo doc --open
```

## Use Cases

Perfect for:

- **API Validation** - Validate incoming JSON requests
- **Configuration Validation** - Ensure config files are correct
- **Data Pipeline Validation** - Validate data transformations
- **Form Validation** - Client and server-side form validation
- **Message Queue Validation** - Validate message formats
- **Database Schema Validation** - Ensure data consistency
- **Microservices** - Service contract validation

## Examples

### REST API Validation

```rust
use json_schema_validator_core::{JsonSchemaValidator, ValidationOptions};

// Define API schema
let user_schema = json!({
    "type": "object",
    "properties": {
        "id": {"type": "integer", "minimum": 1},
        "username": {
            "type": "string", 
            "minLength": 3,
            "maxLength": 20,
            "pattern": "^[a-zA-Z0-9_]+$"
        },
        "email": {"type": "string", "format": "email"},
        "profile": {
            "type": "object",
            "properties": {
                "firstName": {"type": "string", "minLength": 1},
                "lastName": {"type": "string", "minLength": 1},
                "age": {"type": "integer", "minimum": 13, "maximum": 120}
            },
            "required": ["firstName", "lastName"]
        }
    },
    "required": ["username", "email"],
    "additionalProperties": false
});

let validator = JsonSchemaValidator::new(user_schema, ValidationOptions::default()).unwrap();

// Validate incoming requests
fn validate_user_request(data: &str) -> Result<(), Vec<ValidationError>> {
    let instance: Value = serde_json::from_str(data)?;
    let errors = validator.validate(&instance);
    if errors.is_empty() {
        Ok(())
    } else {
        Err(errors)
    }
}
```

### Configuration Validation

```rust
// Database configuration schema
let config_schema = json!({
    "type": "object",
    "properties": {
        "database": {
            "type": "object",
            "properties": {
                "host": {"type": "string", "format": "hostname"},
                "port": {"type": "integer", "minimum": 1, "maximum": 65535},
                "username": {"type": "string", "minLength": 1},
                "password": {"type": "string", "minLength": 8},
                "ssl": {"type": "boolean"}
            },
            "required": ["host", "port", "username", "password"]
        },
        "logging": {
            "type": "object",
            "properties": {
                "level": {"enum": ["error", "warn", "info", "debug", "trace"]},
                "format": {"enum": ["json", "text"]}
            }
        }
    },
    "required": ["database"]
});
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

### Development Setup

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Add tests for your changes
5. Ensure tests pass (`cargo test`)
6. Run benchmarks (`cargo bench`)
7. Commit your changes (`git commit -am 'Add amazing feature'`)
8. Push to the branch (`git push origin feature/amazing-feature`)
9. Open a Pull Request

### Code Style

- Follow standard Rust conventions
- Run `cargo fmt` before committing
- Run `cargo clippy` and fix any warnings
- Add tests for new functionality
- Update documentation as needed

## License

This project is licensed under either of

- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)

at your option.

## Changelog

### v1.0.0 (2025-09-20)

- Initial release
- Full JSON Schema Draft 7 support
- High-performance validation engine
- Comprehensive error reporting
- C FFI exports
- WebAssembly bindings
- Format validation (email, URI, date, datetime, IPv4, IPv6, UUID)
- Custom format and keyword support
- Extensive test suite

## Related Projects

- [jsonschema](https://crates.io/crates/jsonschema) - Another Rust JSON Schema validator
- [ajv](https://ajv.js.org/) - JavaScript JSON Schema validator
- [jsonschema](https://python-jsonschema.readthedocs.io/) - Python JSON Schema validation

## Acknowledgments

- JSON Schema specification maintainers
- The Rust community for excellent crates and tooling
- Contributors to the serde ecosystem

---

Built with Rust 🦀 for speed and safety.