CLI Reference

• 1: morphir ir verify
• 2: Troubleshooting

dotnet tool install -g Morphir.CLI

dotnet tool install Morphir.CLI

morphir --help
morphir ir --help
morphir ir verify --help

# Validate a single file with auto-detection
morphir ir verify path/to/morphir-ir.json

# Validate with explicit schema version
morphir ir verify --schema-version 3 path/to/morphir-ir.json

# Get JSON output for CI/CD
morphir ir verify --json path/to/morphir-ir.json

# Quiet mode (only errors)
morphir ir verify --quiet path/to/morphir-ir.json

1 - morphir ir verify

morphir ir verify

Validate Morphir IR JSON files against the official JSON schemas for format versions 1, 2, and 3.

Synopsis

morphir ir verify <file-path> [options]

Description

The morphir ir verify command validates a Morphir IR JSON file against the appropriate schema specification. The command automatically detects the schema version from the file content, or you can explicitly specify the version to use.

This command is useful for:

• Catching structural errors before IR files are used by other tools
• Validating generated IR from Morphir compilers
• CI/CD integration to ensure IR quality
• Debugging IR issues with detailed error messages

Arguments

<file-path>

Required. Path to the Morphir IR JSON file to validate.

• Supports absolute and relative paths
• File must exist and be readable
• File must contain valid JSON

Examples:

morphir ir verify morphir-ir.json
morphir ir verify ../output/morphir-ir.json
morphir ir verify /absolute/path/to/morphir-ir.json

Options

--schema-version <version>

Explicitly specify the schema version to validate against.

• Valid values: 1, 2, or 3
• Default: Auto-detected from file content
• Use when: Testing version-specific compatibility or overriding auto-detection

Examples:

# Validate against v3 schema regardless of file content
morphir ir verify --schema-version 3 morphir-ir.json

# Test if a v2 IR file is compatible with v3 schema
morphir ir verify --schema-version 3 morphir-ir-v2.json

--json

Output validation results in JSON format instead of human-readable text.

• Default: Human-readable output
• Use when: Parsing results in CI/CD, scripts, or other tools
• Output: Structured JSON with validation details

JSON Output Format:

{
  "IsValid": true,
  "SchemaVersion": "3",
  "DetectionMethod": "auto",
  "FilePath": "/path/to/morphir-ir.json",
  "Errors": [],
  "Timestamp": "2025-12-15T10:30:00Z"
}

For invalid IR:

{
  "IsValid": false,
  "SchemaVersion": "3",
  "DetectionMethod": "auto",
  "FilePath": "/path/to/morphir-ir.json",
  "Errors": [
    {
      "Path": "$.distribution[3]",
      "Message": "Required properties [\"formatVersion\"] are not present",
      "Expected": "required property",
      "Found": "undefined (missing)",
      "Line": null,
      "Column": null
    }
  ],
  "Timestamp": "2025-12-15T10:30:00Z"
}

Example:

# Get JSON output for parsing
morphir ir verify --json morphir-ir.json

# Use in scripts
RESULT=$(morphir ir verify --json morphir-ir.json)
echo $RESULT | jq '.IsValid'

--quiet

Suppress all output except for errors.

• Default: Show detailed output
• Use when: Running in CI/CD pipelines where you only care about failures
• Exit code: Still returns 0 (success) or 1 (failure)

Examples:

# Quiet mode - only shows output if validation fails
morphir ir verify --quiet morphir-ir.json

# Use in CI/CD
if morphir ir verify --quiet morphir-ir.json; then
  echo "IR is valid"
else
  echo "IR validation failed"
  exit 1
fi

Exit Codes

Output

Human-Readable Output (Default)

Valid IR:

Validation Result: ✓ VALID
File: /path/to/morphir-ir.json
Schema Version: v3 (auto)
Timestamp: 2025-12-15 10:30:00 UTC

No validation errors found.

Invalid IR:

Validation Result: ✗ INVALID
File: /path/to/morphir-ir.json
Schema Version: v3 (auto)
Timestamp: 2025-12-15 10:30:00 UTC

Found 2 validation error(s):

  Path: $.distribution[3]
  Message: Required properties ["formatVersion"] are not present
  Expected: required property
  Found: undefined (missing)

  Path: $.distribution[3].modules[0].name
  Message: Value is "string" but should be "array"
  Expected: array
  Found: string

JSON Output

See the --json option above for the JSON output format specification.

Schema Version Detection

The command automatically detects the schema version by analyzing the IR file structure:

• v1: Detected by presence of v1-specific structure
• v2: Detected by "formatVersion": 2 field
• v3: Detected by "formatVersion": 3 field

Detection Method in Output:

• auto: Version was automatically detected
• manual: Version was explicitly specified via --schema-version

Examples

Basic Validation

Validate a single IR file with auto-detection:

morphir ir verify morphir-ir.json

Explicit Version

Validate against a specific schema version:

morphir ir verify --schema-version 3 morphir-ir.json

CI/CD Integration

Validate IR in a GitHub Actions workflow:

- name: Validate Morphir IR
  run: |
    dotnet morphir ir verify --json morphir-ir.json > validation-result.json
    if [ $? -ne 0 ]; then
      cat validation-result.json
      exit 1
    fi

Script with Error Handling

#!/bin/bash
set -e

echo "Validating Morphir IR files..."

for file in output/*.json; do
  echo "Validating $file..."
  if morphir ir verify --quiet "$file"; then
    echo "✓ $file is valid"
  else
    echo "✗ $file is invalid"
    morphir ir verify "$file"  # Show detailed errors
    exit 1
  fi
done

echo "All IR files are valid!"

JSON Output Parsing

Parse JSON output with jq:

# Check if valid
morphir ir verify --json morphir-ir.json | jq '.IsValid'

# Get error count
morphir ir verify --json morphir-ir.json | jq '.Errors | length'

# Extract error messages
morphir ir verify --json morphir-ir.json | jq '.Errors[].Message'

# Get schema version used
morphir ir verify --json morphir-ir.json | jq '.SchemaVersion'

Common Error Messages

File Not Found

Error: File does not exist: path/to/file.json

Solution: Check the file path and ensure the file exists.

Malformed JSON

Validation Result: ✗ INVALID

Found 1 validation error(s):

  Path: $
  Message: Malformed JSON: 'i' is an invalid start of a value. LineNumber: 6 | BytePositionInLine: 4.
  Expected: Valid JSON
  Found: Invalid JSON syntax

Solution: Fix the JSON syntax error. The error message includes the line and byte position.

Missing Required Field

Path: $.distribution
Message: Required properties ["formatVersion"] are not present
Expected: required property
Found: undefined (missing)

Solution: Add the missing formatVersion field to your IR file.

Type Mismatch

Path: $.distribution[3].modules[0].name
Message: Value is "string" but should be "array"
Expected: array
Found: string

Solution: Change the field type to match the schema requirement (in this case, name should be an array, not a string).

Troubleshooting

Schema Version Not Detected

If auto-detection fails or detects the wrong version:

1. Check the formatVersion field in your JSON (for v2/v3)
2. Use --schema-version explicitly to override auto-detection
3. Verify JSON structure matches the expected schema version

Performance Issues

For large IR files (>1MB):

• Validation may take several seconds
• Consider using --quiet mode in CI/CD to reduce output overhead
• (Phase 2 will include performance optimizations for batch processing)

False Positives

If validation fails but you believe the IR is correct:

1. Check schema version - ensure you’re validating against the correct version
2. Review error messages - they include expected vs. found values
3. Consult schema documentation - see Schema Specifications
4. Report an issue - if you believe the schema or validator has a bug

Related Commands

• morphir ir detect-version (Phase 2) - Detect schema version without validation
• morphir ir migrate (Phase 3) - Migrate IR between schema versions

See Also

• Schema Specifications - Complete IR schema documentation
• Troubleshooting Guide - Solutions to common issues
• CI/CD Integration Guide (coming soon)

2 - Troubleshooting

Troubleshooting Guide

This guide covers common issues you may encounter when using the Morphir .NET CLI and how to resolve them.

Installation Issues

Tool Not Found After Installation

Problem: After running dotnet tool install, the morphir command is not found.

Solution:

1. Check if tools are in PATH:

   echo $PATH | grep .dotnet/tools
   

2. Add to PATH if missing (Linux/macOS):

   export PATH="$PATH:$HOME/.dotnet/tools"
   

3. Add to PATH if missing (Windows):

   $env:PATH += ";$env:USERPROFILE\.dotnet\tools"
   

4. Restart your terminal after modifying PATH

Installation Fails with “Unable to find package”

Problem: dotnet tool install Morphir.CLI fails to find the package.

Solution:

1. Check NuGet sources:

   dotnet nuget list source
   

2. Add nuget.org if missing:

   dotnet nuget add source https://api.nuget.org/v3/index.json -n nuget.org
   

3. Verify package name - ensure you’re using the correct package name

Validation Issues

“File does not exist” Error

Problem:

Error: File does not exist: morphir-ir.json

Solutions:

1. Check file path:

   ls -l morphir-ir.json
   

2. Use absolute path:

   morphir ir verify /full/path/to/morphir-ir.json
   

3. Check current directory:

   pwd
   cd /path/to/ir/files
   morphir ir verify morphir-ir.json
   

Malformed JSON Errors

Problem:

Message: Malformed JSON: 'i' is an invalid start of a value. LineNumber: 6

Solutions:

1. Validate JSON syntax with a JSON validator:

   cat morphir-ir.json | jq .
   

2. Check for common issues:

   • Missing commas between array/object elements
   • Trailing commas (not allowed in JSON)
   • Unquoted keys or values
   • Invalid escape sequences

3. Use a JSON formatter:

   cat morphir-ir.json | jq . > morphir-ir-formatted.json
   

Schema Version Detection Issues

Problem: Auto-detection selects the wrong schema version.

Solutions:

1. Explicitly specify version:

   morphir ir verify --schema-version 3 morphir-ir.json
   

2. Check formatVersion field (for v2/v3):

   cat morphir-ir.json | jq '.formatVersion'
   

3. Verify IR structure:

   • v1: No formatVersion field
   • v2: "formatVersion": 2
   • v3: "formatVersion": 3

Validation Fails but IR Appears Correct

Problem: Validation reports errors, but you believe the IR is valid.

Investigation Steps:

1. Review error messages carefully - they include Expected vs. Found values

2. Check schema documentation - Schema Specifications

3. Validate against different versions:

   morphir ir verify --schema-version 1 morphir-ir.json
   morphir ir verify --schema-version 2 morphir-ir.json
   morphir ir verify --schema-version 3 morphir-ir.json
   

4. Compare with known-good IR:

   # Validate a reference file
   morphir ir verify reference-morphir-ir.json
   

5. Check for common issues:

   • Incorrect tag capitalization (e.g., "Public" vs "public")
   • Missing required fields
   • Incorrect array structure
   • Type mismatches

Performance Issues

Validation Takes Too Long

Problem: Validation of large IR files (>1MB) takes several seconds.

Current Limitations:

• This is expected behavior for large files in Phase 1
• Schema validation is inherently slower for complex, deeply-nested JSON

Workarounds:

1. Use --quiet mode to reduce output overhead:

   morphir ir verify --quiet morphir-ir.json
   

2. Validate in parallel (for multiple files):

   find . -name "*.json" | xargs -P 4 -I {} morphir ir verify --quiet {}
   

3. Phase 2 improvements (coming soon):

   • Performance optimizations for batch processing
   • Caching and incremental validation

High Memory Usage

Problem: Validation consumes excessive memory for very large IR files.

Solutions:

1. Check file size:

   ls -lh morphir-ir.json
   

2. For files >10MB:

   • Consider splitting into smaller modules
   • Report the issue with file size details

3. Increase available memory (if using Docker):

   docker run --memory 2g morphir-cli ir verify morphir-ir.json
   

CI/CD Integration Issues

CI Pipeline Doesn’t Fail on Invalid IR

Problem: Pipeline continues even when validation fails.

Solution: Check exit codes explicitly:

# GitHub Actions
- name: Validate IR
  run: |
    morphir ir verify morphir-ir.json
    if [ $? -ne 0 ]; then
      echo "Validation failed"
      exit 1
    fi

Or use set -e in bash scripts:

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

morphir ir verify morphir-ir.json
echo "Validation succeeded!"

JSON Output Not Parsed Correctly

Problem: CI tools can’t parse JSON output.

Solutions:

1. Verify JSON format:

   morphir ir verify --json morphir-ir.json | jq .
   

2. Save to file:

   morphir ir verify --json morphir-ir.json > validation-result.json
   

3. Check for extra output:

   • Use --quiet with --json to suppress non-JSON output
   • Some logging may appear on stderr

Permission Denied in Docker

Problem:

Permission denied: /app/morphir-ir.json

Solution: Fix file permissions or use volume mounts:

# In Dockerfile
RUN chmod +r /app/*.json

# Or when running
docker run -v $(pwd):/app:ro morphir-cli ir verify /app/morphir-ir.json

Error Message Reference

Common Validation Errors

Missing Required Field

Path: $.distribution
Message: Required properties ["formatVersion"] are not present
Expected: required property
Found: undefined (missing)

Fix: Add the missing field to your JSON:

{
  "formatVersion": 3,
  "distribution": [ ... ]
}

Type Mismatch

Path: $.modules[0].name
Message: Value is "string" but should be "array"
Expected: array
Found: string

Fix: Change the field type:

// Incorrect
"name": "MyModule"

// Correct
"name": ["my", "module"]

Invalid Tag Value

Path: $.modules[0].accessControl
Message: Value must be one of: ["Public", "Private"]
Expected: "Public" or "Private"
Found: "public"

Fix: Use correct capitalization:

// Incorrect
"accessControl": "public"

// Correct
"accessControl": "Public"

Array Structure Error

Path: $.distribution[2]
Message: Expected array to have exactly 4 elements
Expected: array of length 4
Found: array of length 3

Fix: Ensure array has the correct number of elements per schema.

Reporting Issues

If you encounter an issue not covered here:

1. Check existing issues: GitHub Issues

2. Gather information:

   • Morphir .NET CLI version: morphir --version
   • .NET SDK version: dotnet --version
   • Operating system and version
   • Complete error message
   • Minimal reproduction steps

3. Create a new issue with:

   • Clear title describing the problem
   • Steps to reproduce
   • Expected vs. actual behavior
   • Environment information
   • Sample IR file (if possible) or minimal example

Getting Help

• Documentation: Morphir .NET Docs
• GitHub Issues: finos/morphir-dotnet/issues
• Community: FINOS Morphir

See Also

• CLI Reference - Complete command documentation
• morphir ir verify - Detailed verification command reference
• Schema Specifications - IR schema documentation