# 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

```bash
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:

```bash
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:

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

### Validate Before Import

Validate before importing:

```bash
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:

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

### Validate After Revise

Validate revised bundles:

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

### Validate After Implode

Validate after imploding:

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

## Use Cases

### 1. Pre-Deployment Validation

Validate bundles before deploying to production:

```bash
#!/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:

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

### 3. Development Workflow

Validate during policy development:

```bash
# 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:

```bash
# 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:

```bash
# 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:

```bash
#!/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

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

### Validate → Import

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

### Combine → Validate

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

### Revise → Validate

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

### Implode → Validate

```bash
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

```bash
#!/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

```bash
#!/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

```bash
#!/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-Command.md)**: Export bundles for validation
- **[import](Import-Command.md)**: Import validated bundles
- **[revise](Revise-Command.md)**: Revise bundles before validation
- **[implode](Implode-Command.md)**: 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