expressir 1.2.10-aarch64-linux → 2.4.29-aarch64-linux

data/docs/_guides/cli/validate-schemas.adoc

@@ -0,0 +1,534 @@
+---
+title: Validate Schemas
+parent: CLI Guides
+grand_parent: Guides
+nav_order: 3
+---
+
+== Validate Schemas
+
+=== Purpose
+
+The `validate load` command checks EXPRESS schemas for syntax errors and version
+string compliance. This ensures schemas are well-formed and properly versioned
+before deployment or further processing.
+
+=== References
+
+* link:validate-ascii.html[Validate ASCII Content]
+* link:../../tutorials/parsing-your-first-schema.html[Tutorial: Parsing Your First Schema]
+* link:../../pages/express-language.html[EXPRESS Language Documentation]
+* link:format-schemas.html[Format Schemas]
+
+=== Concepts
+
+Schema validation:: Checking that EXPRESS schema files can be successfully parsed and meet structural requirements
+Version string:: Required metadata in schema declarations identifying the schema version
+Batch validation:: Validating multiple schemas in a single operation
+Schema manifest:: YAML file containing schema definitions that can be validated
+Exit codes:: Command returns 0 for success, 1 for validation failures
+
+=== Basic Usage
+
+==== Validate Single File
+
+[source,bash]
+----
+expressir validate load schema.exp
+----
+
+Output on success:
+[source]
+----
+Validating schema.exp
+Validation passed for all EXPRESS schemas.
+----
+
+Output on failure:
+[source]
+----
+Validating schema.exp
+******************** RESULTS: FAILED TO PARSE ********************
+Failed to parse: schema.exp
+
+******************** RESULTS: MISSING VERSION STRING ********************
+Missing version string: schema `example_schema` | schema.exp
+----
+
+==== Validate Multiple Files
+
+[source,bash]
+----
+# Explicit files
+expressir validate load schema1.exp schema2.exp schema3.exp
+
+# Using wildcards
+expressir validate load schemas/*.exp
+
+# Recursive search
+expressir validate load schemas/**/*.exp
+----
+
+==== Validate from Schema Manifest
+
+[source,bash]
+----
+# Validate all schemas defined in a manifest
+expressir validate load manifest.yaml
+
+# With verbose output
+expressir validate load manifest.yaml --verbose
+----
+
+==== CI/CD Usage
+
+[source,bash]
+----
+# Exit code 0 on success, 1 on failure
+expressir validate load schemas/*.exp
+if [ $? -eq 0 ]; then
+  echo "✓ All schemas valid"
+else
+  echo "✗ Validation failed"
+  exit 1
+fi
+----
+
+=== Command Options
+
+==== Available Options
+
+[options="header"]
+|===
+| Option | Description | Default
+
+| `--verbose`
+| Show detailed processing information
+| false
+
+| `--help`, `-h`
+| Display help message
+| -
+|===
+
+==== Verbose Option
+
+[source,bash]
+----
+expressir validate load schema.exp --verbose
+----
+
+Provides additional output about the validation process, including schema names and structure information.
+
+=== Validation Checks
+
+==== Syntax Validation
+
+The validator checks that schemas can be successfully parsed according to EXPRESS grammar rules:
+
+* **Keywords**: Proper use of EXPRESS keywords
+* **Structure**: Correct entity, type, function declarations
+* **Syntax**: Valid statements, expressions, and references
+* **Encoding**: UTF-8 character encoding
+
+Example of syntax errors detected:
+
+[source,express]
+----
+SCHEMA invalid_schema;
+  ENTITY person
+    name : STRING;  (* Missing semicolon after ENTITY *)
+  END_ENTITY;
+END_SCHEMA;
+----
+
+Validation output:
+[source]
+----
+Failed to parse: invalid_schema.exp
+----
+
+==== Version String Validation
+
+All schemas must include a version declaration:
+
+[source,express]
+----
+SCHEMA example_schema;
+  -- Valid: includes version
+END_SCHEMA; -- example_schema
+----
+
+Missing version:
+[source,express]
+----
+SCHEMA example_schema;
+  (* No version declared *)
+END_SCHEMA;
+----
+
+Validation output:
+[source]
+----
+Missing version string: schema `example_schema` | example_schema.exp
+----
+
+Valid version declaration:
+[source,express]
+----
+SCHEMA example_schema;
+  SCHEMA_VERSION('1.0.0');
+END_SCHEMA;
+----
+
+=== Use Cases
+
+==== Pre-commit Validation
+
+Validate schemas before committing to version control:
+
+[source,bash]
+----
+#!/bin/bash
+# .git/hooks/pre-commit
+
+# Get staged .exp files
+STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\.exp$')
+
+if [ -z "$STAGED_FILES" ]; then
+  exit 0
+fi
+
+echo "Validating staged EXPRESS schemas..."
+
+# Validate each staged file
+for file in $STAGED_FILES; do
+  if ! expressir validate load "$file"; then
+    echo "❌ Validation failed for: $file"
+    echo "Please fix validation errors before committing."
+    exit 1
+  fi
+done
+
+echo "✓ All staged schemas are valid"
+----
+
+Make it executable:
+[source,bash]
+----
+chmod +x .git/hooks/pre-commit
+----
+
+==== CI/CD Pipeline Integration
+
+GitHub Actions workflow:
+
+[source,yaml]
+----
+name: Validate Schemas
+
+on: [push, pull_request]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.0'
+
+      - name: Install Expressir
+        run: gem install expressir
+
+      - name: Validate all schemas
+        run: |
+          echo "Validating EXPRESS schemas..."
+          if expressir validate load schemas/*.exp; then
+            echo "✓ All schemas valid"
+          else
+            echo "✗ Schema validation failed"
+            exit 1
+          fi
+----
+
+==== Quality Assurance Script
+
+Comprehensive validation script:
+
+[source,bash]
+----
+#!/bin/bash
+# validate-all.sh - Complete schema validation
+
+set -e
+
+SCHEMA_DIR="schemas"
+REPORT_FILE="validation_report.txt"
+
+echo "EXPRESS Schema Validation Report" > "$REPORT_FILE"
+echo "================================" >> "$REPORT_FILE"
+echo "Date: $(date)" >> "$REPORT_FILE"
+echo "" >> "$REPORT_FILE"
+
+# Count total schemas
+TOTAL=$(find "$SCHEMA_DIR" -name "*.exp" | wc -l)
+echo "Total schemas: $TOTAL" >> "$REPORT_FILE"
+echo "" >> "$REPORT_FILE"
+
+# Run validation
+echo "Running validation..." | tee -a "$REPORT_FILE"
+if expressir validate load "$SCHEMA_DIR"/*.exp >> "$REPORT_FILE" 2>&1; then
+  echo "✓ All schemas passed validation" | tee -a "$REPORT_FILE"
+  exit 0
+else
+  echo "✗ Validation failed - see $REPORT_FILE" | tee -a "$REPORT_FILE"
+  exit 1
+fi
+----
+
+==== Batch Validation with Reporting
+
+[source,bash]
+----
+#!/bin/bash
+# validate-with-report.sh
+
+VALID=0
+INVALID=0
+MISSING_VERSION=0
+
+for file in schemas/*.exp; do
+  echo "Checking: $file"
+
+  OUTPUT=$(expressir validate load "$file" 2>&1)
+  STATUS=$?
+
+  if [ $STATUS -eq 0 ]; then
+    echo "  ✓ Valid"
+    ((VALID++))
+  else
+    if echo "$OUTPUT" | grep -q "Failed to parse"; then
+      echo "  ✗ Parse error"
+      ((INVALID++))
+    fi
+    if echo "$OUTPUT" | grep -q "Missing version"; then
+      echo "  ⚠ Missing version"
+      ((MISSING_VERSION++))
+    fi
+  fi
+done
+
+echo ""
+echo "Summary:"
+echo "  Valid: $VALID"
+echo "  Parse errors: $INVALID"
+echo "  Missing version: $MISSING_VERSION"
+
+if [ $INVALID -gt 0 ] || [ $MISSING_VERSION -gt 0 ]; then
+  exit 1
+fi
+----
+
+=== Validation Workflow
+
+==== Development Workflow
+
+[source,bash]
+----
+# 1. Edit schema
+vim my_schema.exp
+
+# 2. Validate
+expressir validate load my_schema.exp
+
+# 3. If valid, format
+expressir format my_schema.exp -o my_schema.exp
+
+# 4. Commit
+git add my_schema.exp
+git commit -m "Add my_schema"
+----
+
+==== Team Workflow
+
+[source,bash]
+----
+# 1. Validate all schemas
+expressir validate load schemas/*.exp
+
+# 2. Fix any errors
+# (edit files as needed)
+
+# 3. Re-validate
+expressir validate load schemas/*.exp
+
+# 4. Proceed with deployment
+./deploy.sh
+----
+
+=== Common Validation Errors
+
+==== Parse Errors
+
+**Missing Semicolon**
+
+[source,express]
+----
+ENTITY person
+  name : STRING;  (* Missing semicolon after entity name *)
+----
+
+**Solution**: Add semicolon after ENTITY declaration:
+[source,express]
+----
+ENTITY person;
+  name : STRING;
+----
+
+**Invalid Keyword**
+
+[source,express]
+----
+ENTITTY person;  (* Typo in keyword *)
+----
+
+**Solution**: Correct the keyword spelling.
+
+**Unclosed Block**
+
+[source,express]
+----
+SCHEMA example;
+  ENTITY person;
+    name : STRING;
+  (* Missing END_ENTITY *)
+END_SCHEMA;
+----
+
+**Solution**: Add missing END_ENTITY.
+
+==== Version String Errors
+
+**Missing Version**
+
+[source,express]
+----
+SCHEMA example_schema;
+  (* No version declared *)
+END_SCHEMA;
+----
+
+**Solution**: Add SCHEMA_VERSION declaration:
+[source,express]
+----
+SCHEMA example_schema;
+  SCHEMA_VERSION('1.0.0');
+END_SCHEMA;
+----
+
+**Invalid Version Format**
+
+While any string is technically valid, use semantic versioning:
+[source,express]
+----
+SCHEMA example_schema;
+  SCHEMA_VERSION('1.0.0');  (* Recommended format *)
+END_SCHEMA;
+----
+
+=== Error Messages
+
+==== Failed to Parse
+
+[source]
+----
+******************** RESULTS: FAILED TO PARSE ********************
+Failed to parse: schema.exp
+----
+
+**Meaning**: The schema file contains syntax errors that prevent parsing.
+
+**Actions**:
+1. Open the file in an editor
+2. Check for common syntax errors
+3. Validate EXPRESS grammar rules
+4. Test with a minimal schema first
+
+==== Missing Version String
+
+[source]
+----
+******************** RESULTS: MISSING VERSION STRING ********************
+Missing version string: schema `example_schema` | schema.exp
+----
+
+**Meaning**: The schema lacks a SCHEMA_VERSION declaration.
+
+**Actions**:
+1. Add SCHEMA_VERSION to the schema
+2. Use semantic versioning format
+3. Document version in project metadata
+
+=== Best Practices
+
+**Validate Before Committing**::
+Always validate schemas before version control operations
++
+[source,bash]
+----
+expressir validate load schema.exp && git commit -m "Update schema"
+----
+
+**Automate Validation**::
+Add validation to CI/CD pipelines
++
+[source,bash]
+----
+# In CI script
+expressir validate load schemas/*.exp || exit 1
+----
+
+**Use Exit Codes**::
+Check validation results programmatically
++
+[source,bash]
+----
+if expressir validate load schema.exp; then
+  echo "Valid - proceeding"
+else
+  echo "Invalid - stopping"
+  exit 1
+fi
+----
+
+**Validate After Format**::
+Ensure formatting didn't introduce errors
++
+[source,bash]
+----
+expressir format schema.exp -o schema.exp
+expressir validate load schema.exp
+----
+
+**Keep Versions Updated**::
+Maintain accurate version strings in all schemas
+
+
+
+=== Next Steps
+
+**Related Commands**::
+* link:validate-ascii.html[Validate ASCII Content] - Check for non-ASCII characters
+* link:format-schemas.html[Format Schemas] - Pretty-print schemas
+* link:coverage-analysis.html[Coverage Analysis] - Check documentation
+
+**Advanced Topics**::
+* link:../ruby-api/parsing-files.html[Ruby API Parsing] - Programmatic validation
+* link:../deployment/ci-cd-setup.html[CI/CD Setup] - Automated workflows
+
+**Quality Assurance**::
+* link:benchmark-performance.html[Benchmark Performance] - Performance testing
+* link:../../tutorials/working-with-multiple-schemas.html[Working with Multiple Schemas]