avrotize 3.0.2__py3-none-any.whl → 3.1.1__py3-none-any.whl

avrotize/validate.py

@@ -0,0 +1,242 @@
+"""Validates JSON instances against Avro or JSON Structure schemas.
+
+This module provides a unified interface for validating JSON data against
+both Avro schemas and JSON Structure schemas.
+"""
+
+import json
+import os
+from typing import Any, Dict, List, Tuple
+
+from avrotize.avrovalidator import AvroValidator, AvroValidationError, validate_json_against_avro
+
+# JSON Structure SDK for validation
+try:
+    from json_structure import SchemaValidator as JStructSchemaValidator
+    from json_structure import InstanceValidator as JStructInstanceValidator
+    HAS_JSTRUCT_SDK = True
+except ImportError:
+    HAS_JSTRUCT_SDK = False
+
+
+class ValidationResult:
+    """Result of validating a JSON instance against a schema."""
+
+    def __init__(self, is_valid: bool, errors: List[str] = None, instance_path: str = None):
+        self.is_valid = is_valid
+        self.errors = errors or []
+        self.instance_path = instance_path
+
+    def __str__(self) -> str:
+        if self.is_valid:
+            return f"✓ Valid" + (f": {self.instance_path}" if self.instance_path else "")
+        else:
+            prefix = f"{self.instance_path}: " if self.instance_path else ""
+            return f"✗ Invalid: {prefix}" + "; ".join(self.errors)
+
+    def __repr__(self) -> str:
+        return f"ValidationResult(is_valid={self.is_valid}, errors={self.errors})"
+
+
+def detect_schema_type(schema: Dict[str, Any]) -> str:
+    """Detects whether a schema is Avro or JSON Structure.
+
+    Args:
+        schema: The parsed schema object
+
+    Returns:
+        'avro' or 'jstruct' or 'unknown'
+    """
+    # JSON Structure schemas have $schema and $id
+    if '$schema' in schema and 'json-structure' in schema.get('$schema', ''):
+        return 'jstruct'
+
+    # Avro schemas have 'type' at root and may have 'namespace', 'fields', etc.
+    if 'type' in schema:
+        schema_type = schema.get('type')
+        # Check for Avro record, enum, array, map, or primitive
+        if schema_type in ('record', 'enum', 'fixed', 'array', 'map'):
+            return 'avro'
+        if schema_type in ('null', 'boolean', 'int', 'long', 'float', 'double', 'bytes', 'string'):
+            return 'avro'
+        # JSON Structure object type
+        if schema_type == 'object' and 'properties' in schema:
+            return 'jstruct'
+
+    # Check if it's a union (list)
+    if isinstance(schema, list):
+        return 'avro'
+
+    return 'unknown'
+
+
+def validate_instance(
+    instance: Any,
+    schema: Dict[str, Any],
+    schema_type: str = None
+) -> ValidationResult:
+    """Validates a JSON instance against a schema.
+
+    Args:
+        instance: The JSON value to validate
+        schema: The schema (Avro or JSON Structure)
+        schema_type: 'avro' or 'jstruct', auto-detected if not provided
+
+    Returns:
+        ValidationResult with validation status and any errors
+    """
+    if schema_type is None:
+        schema_type = detect_schema_type(schema)
+
+    if schema_type == 'avro':
+        errors = validate_json_against_avro(instance, schema)
+        return ValidationResult(is_valid=len(errors) == 0, errors=errors)
+
+    elif schema_type == 'jstruct':
+        if not HAS_JSTRUCT_SDK:
+            return ValidationResult(
+                is_valid=False,
+                errors=["JSON Structure SDK not installed. Install with: pip install json-structure"]
+            )
+        try:
+            validator = JStructInstanceValidator(schema)
+            errors = validator.validate(instance)
+            return ValidationResult(is_valid=len(errors) == 0, errors=errors if errors else [])
+        except Exception as e:
+            return ValidationResult(is_valid=False, errors=[str(e)])
+
+    else:
+        return ValidationResult(
+            is_valid=False,
+            errors=[f"Unknown schema type. Cannot auto-detect schema format."]
+        )
+
+
+def validate_file(
+    instance_file: str,
+    schema_file: str,
+    schema_type: str = None
+) -> List[ValidationResult]:
+    """Validates JSON instance file(s) against a schema file.
+
+    Args:
+        instance_file: Path to JSON file (single object, array, or JSONL)
+        schema_file: Path to schema file (.avsc or .jstruct.json)
+        schema_type: 'avro' or 'jstruct', auto-detected if not provided
+
+    Returns:
+        List of ValidationResult for each instance in the file
+    """
+    # Load schema
+    with open(schema_file, 'r', encoding='utf-8') as f:
+        schema = json.load(f)
+
+    # Auto-detect schema type from file extension if not provided
+    if schema_type is None:
+        if schema_file.endswith('.avsc'):
+            schema_type = 'avro'
+        elif schema_file.endswith('.jstruct.json') or schema_file.endswith('.jstruct'):
+            schema_type = 'jstruct'
+        else:
+            schema_type = detect_schema_type(schema)
+
+    # Load instances
+    with open(instance_file, 'r', encoding='utf-8') as f:
+        content = f.read().strip()
+
+    instances = []
+    instance_paths = []
+
+    # Try as JSON array or object
+    try:
+        data = json.loads(content)
+        if isinstance(data, list):
+            instances = data
+            instance_paths = [f"{instance_file}[{i}]" for i in range(len(data))]
+        else:
+            instances = [data]
+            instance_paths = [instance_file]
+    except json.JSONDecodeError:
+        # Try as JSONL
+        for i, line in enumerate(content.split('\n')):
+            line = line.strip()
+            if line:
+                try:
+                    instances.append(json.loads(line))
+                    instance_paths.append(f"{instance_file}:{i+1}")
+                except json.JSONDecodeError:
+                    pass
+
+    # Validate each instance
+    results = []
+    for instance, path in zip(instances, instance_paths):
+        result = validate_instance(instance, schema, schema_type)
+        result.instance_path = path
+        results.append(result)
+
+    return results
+
+
+def validate_json_instances(
+    input_files: List[str],
+    schema_file: str,
+    schema_type: str = None,
+    verbose: bool = False
+) -> Tuple[int, int]:
+    """Validates multiple JSON instance files against a schema.
+
+    Args:
+        input_files: List of JSON file paths to validate
+        schema_file: Path to schema file
+        schema_type: 'avro' or 'jstruct', auto-detected if not provided
+        verbose: Whether to print validation results
+
+    Returns:
+        Tuple of (valid_count, invalid_count)
+    """
+    valid_count = 0
+    invalid_count = 0
+
+    for input_file in input_files:
+        results = validate_file(input_file, schema_file, schema_type)
+        for result in results:
+            if result.is_valid:
+                valid_count += 1
+                if verbose:
+                    print(result)
+            else:
+                invalid_count += 1
+                if verbose:
+                    print(result)
+
+    return valid_count, invalid_count
+
+
+# Command entry point for avrotize CLI
+def validate(
+    input: List[str],
+    schema: str,
+    schema_type: str = None,
+    quiet: bool = False
+) -> None:
+    """Validates JSON instances against an Avro or JSON Structure schema.
+
+    Args:
+        input: List of JSON files to validate
+        schema: Path to schema file (.avsc or .jstruct.json)
+        schema_type: Schema type ('avro' or 'jstruct'), auto-detected if not provided
+        quiet: Suppress output, exit with code 0 if valid, 1 if invalid
+    """
+    valid_count, invalid_count = validate_json_instances(
+        input_files=input,
+        schema_file=schema,
+        schema_type=schema_type,
+        verbose=not quiet
+    )
+
+    if not quiet:
+        total = valid_count + invalid_count
+        print(f"\nValidation summary: {valid_count}/{total} instances valid")
+
+    if invalid_count > 0:
+        exit(1)

avrotize/xmltoschema.py

@@ -0,0 +1,122 @@
+"""Infers schema from XML files and converts to Avro or JSON Structure format.
+
+This module provides:
+- xml2a: Infer Avro schema from XML files
+- xml2s: Infer JSON Structure schema from XML files
+"""
+
+import json
+import os
+from typing import List
+
+from avrotize.schema_inference import (
+    AvroSchemaInferrer,
+    JsonStructureSchemaInferrer,
+    JsonNode
+)
+
+
+def convert_xml_to_avro(
+    input_files: List[str],
+    avro_schema_file: str,
+    type_name: str = 'Document',
+    avro_namespace: str = '',
+    sample_size: int = 0
+) -> None:
+    """Infers Avro schema from XML files.
+
+    Reads XML files, analyzes their structure, and generates an Avro schema
+    that can represent all the data. Multiple files are analyzed together to
+    produce a unified schema.
+
+    Args:
+        input_files: List of XML file paths to analyze
+        avro_schema_file: Output path for the Avro schema
+        type_name: Name for the root type
+        avro_namespace: Namespace for generated Avro types
+        sample_size: Maximum number of documents to sample (0 = all)
+    """
+    if not input_files:
+        raise ValueError("At least one input file is required")
+
+    xml_strings = _load_xml_strings(input_files, sample_size)
+
+    if not xml_strings:
+        raise ValueError("No valid XML data found in input files")
+
+    inferrer = AvroSchemaInferrer(namespace=avro_namespace)
+    schema = inferrer.infer_from_xml_values(type_name, xml_strings)
+
+    # Ensure output directory exists
+    output_dir = os.path.dirname(avro_schema_file)
+    if output_dir and not os.path.exists(output_dir):
+        os.makedirs(output_dir)
+
+    with open(avro_schema_file, 'w', encoding='utf-8') as f:
+        json.dump(schema, f, indent=2)
+
+
+def convert_xml_to_jstruct(
+    input_files: List[str],
+    jstruct_schema_file: str,
+    type_name: str = 'Document',
+    base_id: str = 'https://example.com/',
+    sample_size: int = 0
+) -> None:
+    """Infers JSON Structure schema from XML files.
+
+    Reads XML files, analyzes their structure, and generates a JSON Structure
+    schema that validates with the official JSON Structure SDK.
+
+    Args:
+        input_files: List of XML file paths to analyze
+        jstruct_schema_file: Output path for the JSON Structure schema
+        type_name: Name for the root type
+        base_id: Base URI for $id generation
+        sample_size: Maximum number of documents to sample (0 = all)
+    """
+    if not input_files:
+        raise ValueError("At least one input file is required")
+
+    xml_strings = _load_xml_strings(input_files, sample_size)
+
+    if not xml_strings:
+        raise ValueError("No valid XML data found in input files")
+
+    inferrer = JsonStructureSchemaInferrer(base_id=base_id)
+    schema = inferrer.infer_from_xml_values(type_name, xml_strings)
+
+    # Ensure output directory exists
+    output_dir = os.path.dirname(jstruct_schema_file)
+    if output_dir and not os.path.exists(output_dir):
+        os.makedirs(output_dir)
+
+    with open(jstruct_schema_file, 'w', encoding='utf-8') as f:
+        json.dump(schema, f, indent=2)
+
+
+def _load_xml_strings(input_files: List[str], sample_size: int) -> List[str]:
+    """Loads XML content from files.
+
+    Each file is treated as a single XML document.
+
+    Args:
+        input_files: List of file paths
+        sample_size: Maximum documents to load (0 = all)
+
+    Returns:
+        List of XML strings
+    """
+    xml_strings: List[str] = []
+
+    for file_path in input_files:
+        if sample_size > 0 and len(xml_strings) >= sample_size:
+            break
+
+        with open(file_path, 'r', encoding='utf-8') as f:
+            content = f.read().strip()
+
+        if content:
+            xml_strings.append(content)
+
+    return xml_strings

{avrotize-3.0.2.dist-info → avrotize-3.1.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: avrotize
-Version: 3.0.2
+Version: 3.1.1
 Summary: Tools to convert from and to Avro Schema from various other schema languages.
 Author-email: Clemens Vasters <clemensv@microsoft.com>
 Requires-Python: >=3.10
@@ -26,6 +26,10 @@ Requires-Dist: pandas>=2.2.2
 Requires-Dist: docker>=7.1.0
 Requires-Dist: cddlparser>=0.5.0
 Requires-Dist: json-structure>=0.1.8
+Requires-Dist: psycopg2-binary>=2.9.9 ; extra == "all-sql"
+Requires-Dist: pymysql>=1.1.1 ; extra == "all-sql"
+Requires-Dist: pyodbc>=5.1.0 ; extra == "all-sql"
+Requires-Dist: oracledb>=2.3.0 ; extra == "all-sql"
 Requires-Dist: pytest>=8.3.2 ; extra == "dev"
 Requires-Dist: fastavro>=1.9.5 ; extra == "dev"
 Requires-Dist: xmlschema>=3.3.2 ; extra == "dev"
@@ -37,14 +41,23 @@ Requires-Dist: pydantic>=2.8.2 ; extra == "dev"
 Requires-Dist: avro>=1.12.0 ; extra == "dev"
 Requires-Dist: testcontainers>=4.7.2 ; extra == "dev"
 Requires-Dist: pymysql>=1.1.1 ; extra == "dev"
-Requires-Dist: psycopg2>=2.9.9 ; extra == "dev"
+Requires-Dist: psycopg2-binary>=2.9.9 ; extra == "dev"
 Requires-Dist: pyodbc>=5.1.0 ; extra == "dev"
 Requires-Dist: pymongo>=4.8.0 ; extra == "dev"
 Requires-Dist: oracledb>=2.3.0 ; extra == "dev"
 Requires-Dist: cassandra-driver>=3.29.1 ; extra == "dev"
 Requires-Dist: sqlalchemy>=2.0.32 ; extra == "dev"
 Requires-Dist: graphql-core>=3.2.0 ; extra == "dev"
+Requires-Dist: pymysql>=1.1.1 ; extra == "mysql"
+Requires-Dist: oracledb>=2.3.0 ; extra == "oracle"
+Requires-Dist: psycopg2-binary>=2.9.9 ; extra == "postgres"
+Requires-Dist: pyodbc>=5.1.0 ; extra == "sqlserver"
+Provides-Extra: all-sql
 Provides-Extra: dev
+Provides-Extra: mysql
+Provides-Extra: oracle
+Provides-Extra: postgres
+Provides-Extra: sqlserver
 
 # Avrotize & Structurize
 
@@ -75,6 +88,22 @@ You can install Avrotize from PyPI, [having installed Python 3.10 or later](http
 pip install avrotize
 ```
 
+For SQL database support (`sql2a` command), install the optional database drivers:
+
+```bash
+# PostgreSQL
+pip install avrotize[postgres]
+
+# MySQL
+pip install avrotize[mysql]
+
+# SQL Server
+pip install avrotize[sqlserver]
+
+# All SQL databases
+pip install avrotize[all-sql]
+```
+
 ## Usage
 
 Avrotize provides several commands for converting schema formats via Avrotize Schema.
@@ -86,6 +115,11 @@ Converting to Avrotize Schema:
 - [`avrotize x2a`](#convert-xml-schema-xsd-to-avrotize-schema) - Convert XML schema to Avrotize Schema.
 - [`avrotize asn2a`](#convert-asn1-schema-to-avrotize-schema) - Convert ASN.1 to Avrotize Schema.
 - [`avrotize k2a`](#convert-kusto-table-definition-to-avrotize-schema) - Convert Kusto table definitions to Avrotize Schema.
+- [`avrotize sql2a`](#convert-sql-database-schema-to-avrotize-schema) - Convert SQL database schema to Avrotize Schema.
+- [`avrotize json2a`](#infer-avro-schema-from-json-files) - Infer Avro schema from JSON files.
+- [`avrotize json2s`](#infer-json-structure-schema-from-json-files) - Infer JSON Structure schema from JSON files.
+- [`avrotize xml2a`](#infer-avro-schema-from-xml-files) - Infer Avro schema from XML files.
+- [`avrotize xml2s`](#infer-json-structure-schema-from-xml-files) - Infer JSON Structure schema from XML files.
 - [`avrotize pq2a`](#convert-parquet-schema-to-avrotize-schema) - Convert Parquet schema to Avrotize Schema.
 - [`avrotize csv2a`](#convert-csv-file-to-avrotize-schema) - Convert CSV file to Avrotize Schema.
 - [`avrotize kstruct2a`](#convert-kafka-connect-schema-to-avrotize-schema) - Convert Kafka Connect Schema to Avrotize Schema.
@@ -153,6 +187,7 @@ Direct JSON Structure conversions:
 Other commands:
 
 - [`avrotize pcf`](#create-the-parsing-canonical-form-pcf-of-an-avrotize-schema) - Create the Parsing Canonical Form (PCF) of an Avrotize Schema.
+- [`avrotize validate`](#validate-json-instances-against-schemas) - Validate JSON instances against Avro or JSON Structure schemas.
 
 JSON Structure conversions:
 
@@ -426,6 +461,150 @@ Conversion notes:
 - For `dynamic` columns, the tool will sample the data in the table to determine the structure of the dynamic column. The tool will map the dynamic column to an Avro record type with fields that correspond to the fields found in the dynamic column. If the dynamic column contains nested dynamic columns, the tool will recursively map those to Avro record types. If records with conflicting structures are found in the dynamic column, the tool will emit a union of record types for the dynamic column.
 - If the `--emit-cloudevents-xregistry` option is set, the tool will emit an [xRegistry](http://xregistry.io) registry manifest file with a CloudEvent message definition for each table in the Kusto database and a separate Avro Schema for each table in the embedded schema registry. If one or more tables are found to contain CloudEvent data (as indicated by the presence of the CloudEvents attribute columns), the tool will inspect the content of the `type` (or `__type` or `__type`) columns to determine which CloudEvent types have been stored in the table and will emit a CloudEvent definition and schema for each unique type.
 
+### Convert SQL database schema to Avrotize Schema
+
+```bash
+avrotize sql2a --connection-string <connection_string> [--username <user>] [--password <pass>] [--dialect <dialect>] [--database <database>] [--table-name <table>] [--out <path_to_avro_schema_file>] [--namespace <namespace>] [--infer-json] [--infer-xml] [--sample-size <n>] [--emit-cloudevents] [--emit-xregistry]
+```
+
+Parameters:
+
+- `--connection-string`: The database connection string. Supports SSL/TLS and integrated authentication options (see examples below).
+- `--username`: (optional) Database username. Overrides any username in the connection string. Use this to avoid credentials in command history.
+- `--password`: (optional) Database password. Overrides any password in the connection string. Use this to avoid credentials in command history.
+- `--dialect`: (optional) The SQL dialect: `postgres` (default), `mysql`, `sqlserver`, `oracle`, or `sqlite`.
+- `--database`: (optional) The database name if not specified in the connection string.
+- `--table-name`: (optional) A specific table to convert. If omitted, all tables are converted.
+- `--out`: The path to the Avrotize Schema file. If omitted, output goes to stdout.
+- `--namespace`: (optional) The Avro namespace for the generated schema.
+- `--infer-json`: (optional, default: true) Infer schema for JSON/JSONB columns by sampling data.
+- `--infer-xml`: (optional, default: true) Infer schema for XML columns by sampling data.
+- `--sample-size`: (optional, default: 100) Number of rows to sample for JSON/XML schema inference.
+- `--emit-cloudevents`: (optional) Detect CloudEvents tables and emit CloudEvents declarations.
+- `--emit-xregistry`: (optional) Emit an xRegistry manifest instead of a single schema file.
+
+Connection string examples:
+
+```bash
+# PostgreSQL with separate credentials (preferred for security)
+avrotize sql2a --connection-string "postgresql://host:5432/mydb?sslmode=require" --username myuser --password mypass --out schema.avsc
+
+# PostgreSQL with SSL (credentials in URL)
+avrotize sql2a --connection-string "postgresql://user:pass@host:5432/mydb?sslmode=require" --out schema.avsc
+
+# MySQL with SSL
+avrotize sql2a --connection-string "mysql://user:pass@host:3306/mydb?ssl=true" --dialect mysql --out schema.avsc
+
+# SQL Server with Windows Authentication (omit user/password)
+avrotize sql2a --connection-string "mssql://@host:1433/mydb" --dialect sqlserver --out schema.avsc
+
+# SQL Server with TLS encryption
+avrotize sql2a --connection-string "mssql://user:pass@host:1433/mydb?encrypt=true" --dialect sqlserver --out schema.avsc
+
+# SQLite file
+avrotize sql2a --connection-string "/path/to/database.db" --dialect sqlite --out schema.avsc
+```
+
+Conversion notes:
+
+- The tool connects to a live database and reads the schema from the information schema or system catalogs.
+- Type mappings for each dialect:
+  - **PostgreSQL**: All standard types including `uuid`, `jsonb`, `xml`, arrays, and custom types.
+  - **MySQL**: Standard types including `json`, `enum`, `set`, and spatial types.
+  - **SQL Server**: Standard types including `uniqueidentifier`, `xml`, `money`, and `hierarchyid`.
+  - **Oracle**: Standard types including `number`, `clob`, `blob`, and Oracle-specific types.
+  - **SQLite**: Dynamic typing mapped based on declared type affinity.
+- For JSON/JSONB columns (PostgreSQL, MySQL) and XML columns, the tool samples data to infer the structure. Fields that appear in some but not all records are folded together. If field types conflict across records, the tool emits a union of record types.
+- For columns with keys that cannot be valid Avro identifiers (UUIDs, URLs, special characters), the tool generates `map<string, T>` types instead of record types.
+- Table and column comments are preserved as Avro `doc` attributes where available.
+- Primary key columns are noted in the schema's `unique` attribute.
+
+### Infer Avro schema from JSON files
+
+```bash
+avrotize json2a <json_files...> [--out <path_to_avro_schema_file>] [--type-name <name>] [--namespace <namespace>] [--sample-size <n>]
+```
+
+Parameters:
+
+- `<json_files...>`: One or more JSON files to analyze. Supports JSON arrays, single objects, and JSONL (JSON Lines) format.
+- `--out`: The path to the Avro schema file. If omitted, output goes to stdout.
+- `--type-name`: (optional) Name for the root type (default: "Document").
+- `--namespace`: (optional) Avro namespace for generated types.
+- `--sample-size`: (optional) Maximum number of records to sample (0 = all, default: 0).
+
+Example:
+
+```bash
+# Infer schema from multiple JSON files
+avrotize json2a data1.json data2.json --out schema.avsc --type-name Event --namespace com.example
+
+# Infer schema from JSONL file
+avrotize json2a events.jsonl --out events.avsc --type-name LogEntry
+```
+
+### Infer JSON Structure schema from JSON files
+
+```bash
+avrotize json2s <json_files...> [--out <path_to_jstruct_schema_file>] [--type-name <name>] [--base-id <uri>] [--sample-size <n>]
+```
+
+Parameters:
+
+- `<json_files...>`: One or more JSON files to analyze.
+- `--out`: The path to the JSON Structure schema file. If omitted, output goes to stdout.
+- `--type-name`: (optional) Name for the root type (default: "Document").
+- `--base-id`: (optional) Base URI for $id generation (default: "https://example.com/").
+- `--sample-size`: (optional) Maximum number of records to sample (0 = all, default: 0).
+
+Example:
+
+```bash
+avrotize json2s data.json --out schema.jstruct.json --type-name Person --base-id https://myapi.example.com/schemas/
+```
+
+### Infer Avro schema from XML files
+
+```bash
+avrotize xml2a <xml_files...> [--out <path_to_avro_schema_file>] [--type-name <name>] [--namespace <namespace>] [--sample-size <n>]
+```
+
+Parameters:
+
+- `<xml_files...>`: One or more XML files to analyze.
+- `--out`: The path to the Avro schema file. If omitted, output goes to stdout.
+- `--type-name`: (optional) Name for the root type (default: "Document").
+- `--namespace`: (optional) Avro namespace for generated types.
+- `--sample-size`: (optional) Maximum number of documents to sample (0 = all, default: 0).
+
+Example:
+
+```bash
+avrotize xml2a config.xml --out config.avsc --type-name Configuration --namespace com.example.config
+```
+
+### Infer JSON Structure schema from XML files
+
+```bash
+avrotize xml2s <xml_files...> [--out <path_to_jstruct_schema_file>] [--type-name <name>] [--base-id <uri>] [--sample-size <n>]
+```
+
+Parameters:
+
+- `<xml_files...>`: One or more XML files to analyze.
+- `--out`: The path to the JSON Structure schema file. If omitted, output goes to stdout.
+- `--type-name`: (optional) Name for the root type (default: "Document").
+- `--base-id`: (optional) Base URI for $id generation (default: "https://example.com/").
+- `--sample-size`: (optional) Maximum number of documents to sample (0 = all, default: 0).
+
+Conversion notes (applies to all inference commands):
+
+- XML attributes are converted to fields prefixed with `@` (normalized to valid identifiers).
+- Text content in mixed-content elements becomes a `#text` field.
+- Repeated elements are inferred as arrays.
+- Multiple files with different structures are merged into a unified schema.
+- Sparse data (fields that appear in some but not all records) is folded into a single type.
+
 ### Convert Avrotize Schema to Kusto table declaration
 
 ```bash
@@ -1308,6 +1487,45 @@ Conversion notes:
 - The tool generates the Parsing Canonical Form (PCF) of the Avrotize Schema. The PCF is a normalized form of the schema that is used for schema comparison and compatibility checking.
 - The PCF is a JSON object that is written to stdout.
 
+### Validate JSON instances against schemas
+
+```bash
+avrotize validate <json_files...> --schema <schema_file> [--schema-type <type>] [--quiet]
+```
+
+Parameters:
+
+- `<json_files...>`: One or more JSON files to validate. Supports single JSON objects, JSON arrays, and JSONL (newline-delimited JSON) formats.
+- `--schema <schema_file>`: Path to the schema file (`.avsc` for Avro, `.jstruct.json` for JSON Structure).
+- `--schema-type`: (optional) Schema type: `avro` or `jstruct`. Auto-detected from file extension if omitted.
+- `--quiet`: (optional) Suppress output. Exit code 0 if all instances are valid, 1 if any are invalid.
+
+Validation notes:
+
+- Validates JSON instances against Avro schemas per the [Avrotize Schema specification](specs/avrotize-schema.md).
+- Supports all Avro primitive types: null, boolean, int, long, float, double, bytes, string.
+- Supports all Avro complex types: record, enum, array, map, fixed.
+- Supports logical types with both native and string encodings: decimal, uuid, date, time-millis, time-micros, timestamp-millis, timestamp-micros, duration.
+- Supports field `altnames` for JSON field name mapping.
+- Supports enum `altsymbols` for JSON symbol mapping.
+- For JSON Structure validation, requires the `json-structure` package.
+
+Example:
+
+```bash
+# Validate JSON file against Avro schema
+avrotize validate data.json --schema schema.avsc
+
+# Validate multiple files
+avrotize validate file1.json file2.json --schema schema.avsc
+
+# Validate JSONL file against JSON Structure schema
+avrotize validate events.jsonl --schema events.jstruct.json
+
+# Quiet mode for CI/CD pipelines (exit code only)
+avrotize validate data.json --schema schema.avsc --quiet
+```
+
 ### Convert JSON Structure schema to GraphQL schema
 
 ```bash