Skip to main content

Crate forgedb_validation

Crate forgedb_validation 

Source
Expand description

ForgeDB Validation

The diagnostic vocabulary and reusable predicates that ForgeDB’s schema validation is built from, plus HTTP-status helpers.

§Overview

This crate provides:

The schema walk itself — the single validate_schema(&Schema) that applies these to a parsed AST — lives in forgedb-parser, which owns the AST (see the architecture note below for why it cannot live here).

§Architecture

The validation system is organized into several modules:

  • Core validation - Basic validation types and error reporting
  • HTTP validation - Validates HTTP-specific constructs (endpoints, status codes)
  • Status code mapping - Maps database operations to appropriate HTTP status codes

§Validation Pipeline

  1. Schema Parsing - Parse schema into AST (handled by forgedb-parser)
  2. Schema Validation - Validate schema structure and semantics
  3. Constraint Validation - Check constraint parameters and applicability
  4. HTTP Validation - Validate HTTP endpoints and status codes (if applicable)

Where the schema walk lives (epic #173 WS2b — DONE). The single positioned schema-validation authority is forgedb_parser::validate_schema, not a function in this crate. It has to live in forgedb-parser: it needs the Schema AST, and forgedb-parser already depends on forgedb-validation (for Position/ValidationError), so a reverse dependency would be a cycle. The three former implementations (the parser’s built-in checks, the CLI’s inline src/commands/validate.rs loops, and the validate_* helpers here) are consolidated into that one function; the CLI and the LSP both consume it.

This crate is the diagnostic vocabulary + reusable predicates that validate_schema builds on: ValidationError, Position, validate_field_name, validate_model_name, is_snake_case, is_pascal_case. The HttpValidator/StatusCodeMapper surface is a separate HTTP-status concern.

§Examples

§Schema Validation

use forgedb_validation::{ValidationError, Position};

// Create a validation error with position
let error = ValidationError::new("Field 'email' must have @email constraint")
    .with_position(Position::new(5, 12))
    .with_suggestion("Add @email constraint: email: string @email");

println!("Error at {}:{}: {}",
    error.position.unwrap().line,
    error.position.unwrap().column,
    error.message
);

§HTTP Validation

use forgedb_validation::HttpValidator;

// HttpValidator is a unit struct — call methods directly (no constructor)
let result = HttpValidator::validate_email("user@example.com");
assert!(result.is_ok());

let result = HttpValidator::validate_length("name", "hi", 1, 10);
assert!(result.is_ok());

§Status Code Mapping

use forgedb_validation::StatusCodeMapper;

// StatusCodeMapper is a unit struct — call methods as associated functions
let code = StatusCodeMapper::for_validation_error("not_found");
assert_eq!(code, 404);

assert!(StatusCodeMapper::is_success(200));
assert!(StatusCodeMapper::is_client_error(404));
assert!(StatusCodeMapper::is_server_error(500));

§Public API

§Core Types

§Key Methods

  • ValidationError::new() - Create a validation error
  • ValidationError::with_position() - Add position information
  • ValidationError::with_suggestion() - Add a suggestion for fixing the error
  • HttpValidator::validate_endpoint_path() - Validate HTTP endpoint path
  • StatusCodeMapper::get_status_code() - Get appropriate status code

§Validation Rules

§Schema Validation

  • Unique names: Model and struct names must be unique
  • Field types: Field types must be valid ForgeDB types
  • Primary keys: Each model must have exactly one primary key
  • Relations: Relation targets must reference existing models

§Constraint Validation

  • @unique: Can be applied to any field type
  • @email: Only for string fields
  • @min/@max: Only for numeric fields
  • @length: Only for string fields
  • @pattern: Only for string fields (regex validation)

§HTTP Validation

  • Endpoint paths: Must start with ‘/’, valid parameter syntax
  • Status codes: Must be valid HTTP status codes (200-599)
  • HTTP methods: Must be valid (GET, POST, PUT, DELETE, PATCH)

§Error Reporting

Validation errors include:

  • Message: Clear description of the error
  • Position: Line and column where error occurred
  • Suggestion: Helpful suggestion for fixing the error

Example error output:

Error at line 5, column 12: Field 'email' must have @email constraint
Suggestion: Add @email constraint: email: string @email

§See Also

Re-exports§

pub use http::HttpValidationError;
pub use http::HttpValidator;
pub use status::StatusCodeMapper;

Modules§

http
HTTP-specific validation extensions for Sprint 9
status
HTTP status code mapping for validation errors

Structs§

Position
Represents a position in the source code
ValidationError
Validation error with position information

Functions§

check_duplicate_fields
Check for duplicate field names in a collection
check_duplicate_models
Check for duplicate model names in a collection
is_pascal_case
Check if a string is in PascalCase format
is_snake_case
Check if a string is in snake_case format
to_pascal_case
Convert a string to PascalCase (for suggestions)
to_snake_case
Convert a string to snake_case (for suggestions)
validate_field_name
Validate field name follows snake_case convention
validate_model_name
Validate model name follows PascalCase convention

Type Aliases§

ValidationResult