Validate Command

Validate Command

Overview

The validate command validates bundled entities, focusing primarily on policy code validation. It ensures that policy code in JSON format conforms to the policy code schema, helping catch errors before deployment.

Syntax

graphman validate --input <input-file>

Parameters

Required Parameters

Parameter	Description
--input	Input bundle file to validate

Behavior

Validation Scope

The validate command currently validates:

• Policy Code: JSON-formatted policy code against policy code schema
• Services: Policy code within service entities
• Policies: Policy code within policy entities

Validation Process

1. Reads the input bundle
2. Identifies policies and services with policy code
3. Validates JSON-formatted policy code against schema
4. Reports validation errors with detailed messages
5. Provides entity-level validation status

Policy Code Formats

The validator checks policy code in:

• policy.code field (JSON format)
• policy.json field (JSON format)

Note: XML and YAML policy formats are not validated.

Examples

Basic Validation

Validate a bundle:

graphman validate --input bundle.json

Sample Output (Success):

info: validating policies
info:   validating MyPolicy: ok
info:   validating AnotherPolicy: ok
info: validating services
info:   validating MyService: ok

Sample Output (Errors):

info: validating policies
info:   validating MyPolicy: error(s)
warn:     $.policy.code - MyPolicy - Missing required property: assertionId
warn:     $.policy.code - MyPolicy - Invalid assertion type: UnknownAssertion
info:   validating AnotherPolicy: ok

Validate After Export

Validate exported configuration:

graphman export --gateway dev --output dev-config.json
graphman validate --input dev-config.json

Validate Before Import

Validate before importing:

graphman validate --input deployment-bundle.json
if [ $? -eq 0 ]; then
  graphman import --input deployment-bundle.json --gateway prod
else
  echo "Validation failed, aborting import"
fi

Validate After Combine

Validate combined bundles:

graphman combine --inputs bundle1.json bundle2.json --output combined.json
graphman validate --input combined.json

Validate After Revise

Validate revised bundles:

graphman revise --input old-bundle.json --output revised.json --options.normalize true
graphman validate --input revised.json

Validate After Implode

Validate after imploding:

graphman implode --input exploded/ --output bundle.json
graphman validate --input bundle.json

Use Cases

1. Pre-Deployment Validation

Validate bundles before deploying to production:

#!/bin/bash
echo "Validating deployment bundle..."
if graphman validate --input deployment.json; then
  echo "✓ Validation passed"
  graphman import --input deployment.json --gateway prod
else
  echo "✗ Validation failed - aborting deployment"
  exit 1
fi

2. CI/CD Pipeline Integration

Integrate validation in CI/CD:

# .gitlab-ci.yml
validate:
  script:
    - graphman validate --input bundle.json
  only:
    - merge_requests

3. Development Workflow

Validate during policy development:

# After editing policy code
graphman implode --input policy-dev/ --output policy.json
graphman validate --input policy.json

# If valid, deploy to dev
if [ $? -eq 0 ]; then
  graphman import --input policy.json --gateway dev
fi

4. Bundle Quality Check

Validate bundle quality before version control:

# Export and validate
graphman export --gateway dev --output dev-config.json
graphman validate --input dev-config.json

# If valid, commit
if [ $? -eq 0 ]; then
  git add dev-config.json
  git commit -m "Updated configuration"
fi

5. Policy Migration Validation

Validate after policy migration:

# Migrate and validate
graphman revise --input old-policies.json --output new-policies.json
graphman validate --input new-policies.json

6. Automated Testing

Validate test bundles:

#!/bin/bash
for bundle in test-bundles/*.json; do
  echo "Validating $bundle..."
  if ! graphman validate --input "$bundle"; then
    echo "Failed: $bundle"
    exit 1
  fi
done
echo "All bundles validated successfully"

Validation Errors

Common Error Types

Error Type	Description	Example
Missing Property	Required field is missing	Missing required property: assertionId
Invalid Type	Field has wrong data type	Expected string, got number
Unknown Assertion	Assertion type not recognized	Invalid assertion type: UnknownAssertion
Schema Violation	Doesn't conform to schema	Additional property not allowed: extraField
Invalid Reference	Reference to non-existent entity	Invalid policy reference: abc123

Error Message Format

warn:     <path> - <entity-name> - <error-message>

Example:

warn:     $.policy.code - MyPolicy - Missing required property: assertionId

Policy Code Schema

The validator uses policy code schema files:

<graphman-home>/schema/<version>/policy-code-schema.json

Schema Structure

The policy code schema defines:

• Valid assertion types
• Required properties per assertion
• Property data types
• Nested structure rules
• Allowed values

Limitations

Current Limitations

1. Policy Code Only: Only validates JSON-formatted policy code
2. No XML Validation: XML policies are not validated
3. No YAML Validation: YAML policies are not validated
4. Limited Entity Types: Only policies and services are validated
5. Schema-Based Only: Validation is limited to schema conformance

Not Validated

The following are not validated:

• Entity references (e.g., folder paths, key references)
• Business logic correctness
• Policy runtime behavior
• Configuration values
• Cluster properties
• JDBC connections
• Other entity types

Important Notes

• Policy Code Format: Only JSON format is validated
• Schema Version: Uses the configured schema version
• Non-Blocking: Validation errors don't prevent command execution
• Exit Code: Returns non-zero exit code on validation failure
• Detailed Output: Provides specific error locations and messages
• Entity-Level: Validation is performed per entity
• Multiple Errors: All errors for an entity are reported

Exit Codes

Exit Code	Meaning
0	Validation successful (no errors)
Non-zero	Validation failed (errors found)

Integration with Other Commands

Export → Validate

graphman export --gateway dev --output bundle.json
graphman validate --input bundle.json

Validate → Import

if graphman validate --input bundle.json; then
  graphman import --input bundle.json --gateway prod
fi

Combine → Validate

graphman combine --inputs b1.json b2.json --output combined.json
graphman validate --input combined.json

Revise → Validate

graphman revise --input old.json --output new.json
graphman validate --input new.json

Implode → Validate

graphman implode --input exploded/ --output bundle.json
graphman validate --input bundle.json

Best Practices

1. Always validate before import to production
2. Integrate in CI/CD pipelines for automated validation
3. Validate after transformations (combine, revise, implode)
4. Use exit codes in scripts for flow control
5. Review validation errors carefully before proceeding
6. Keep policy code in JSON format for validation
7. Validate during development to catch errors early
8. Document validation requirements in deployment procedures

Workflow Examples

Deployment Pipeline

#!/bin/bash
set -e  # Exit on error

echo "Step 1: Export from dev"
graphman export --gateway dev --output dev-bundle.json

echo "Step 2: Validate bundle"
graphman validate --input dev-bundle.json

echo "Step 3: Prepare for production"
graphman revise --input dev-bundle.json --output prod-bundle.json \
  --options.normalize true \
  --options.excludeGoids true

echo "Step 4: Validate again"
graphman validate --input prod-bundle.json

echo "Step 5: Deploy to production"
graphman import --input prod-bundle.json --gateway prod

echo "Deployment successful"

Development Workflow

#!/bin/bash
# Policy development workflow

# Edit policy code
vim policies/MyPolicy.cjson

# Implode
graphman implode --input policies/ --output policy-bundle.json

# Validate
if graphman validate --input policy-bundle.json; then
  echo "✓ Policy is valid"
  
  # Deploy to dev
  graphman import --input policy-bundle.json --gateway dev
  
  # Run tests
  ./run-tests.sh
else
  echo "✗ Policy validation failed"
  exit 1
fi

Batch Validation

#!/bin/bash
# Validate multiple bundles

FAILED=0

for bundle in bundles/*.json; do
  echo "Validating $(basename $bundle)..."
  if graphman validate --input "$bundle"; then
    echo "  ✓ Valid"
  else
    echo "  ✗ Invalid"
    FAILED=$((FAILED + 1))
  fi
done

if [ $FAILED -eq 0 ]; then
  echo "All bundles are valid"
  exit 0
else
  echo "$FAILED bundle(s) failed validation"
  exit 1
fi

Related Commands

• export: Export bundles for validation
• import: Import validated bundles
• revise: Revise bundles before validation
• implode: Implode and validate

Troubleshooting

Validation Errors After Export

If validation fails on exported bundles:

• Check Gateway version compatibility
• Verify policy code format
• Review assertion types
• Check schema version

False Positives

If validation reports errors for valid policies:

• Verify schema version matches Gateway version
• Check if using latest Graphman version
• Review policy code schema
• Consider refreshing schema: graphman schema --refresh true

No Validation Output

If no validation occurs:

• Verify bundle contains policies or services
• Check that policy code is in JSON format
• Ensure policy.code or policy.json fields exist
• Verify input file path is correct

Future Enhancements

Potential future validation capabilities:

• XML policy validation
• YAML policy validation
• Entity reference validation
• Cross-entity dependency validation
• Business rule validation
• Configuration value validation