Documentation

• 1: Getting Started
• 1.1: Installation
• 1.2: Validating IR Files
• 2: Guides
• 2.1: IR Modeling
• 2.2: Serialization
• 2.3: Testing
• 3: Morphir IR Specification
• 3.1: Morphir IR Specification
• 3.2: JSON Schemas
• 3.2.1: Schema Version 3
• 3.2.1.1: What's New in Version 3
• 3.2.1.2: Full Schema
• 3.2.2: Schema Version 2
• 3.2.2.1: What's New in Version 2
• 3.2.2.2: Full Schema
• 3.2.3: Schema Version 1
• 3.2.3.1: Full Schema
• 4: API Reference
• 5: CLI Reference
• 5.1: morphir ir verify
• 5.2: Troubleshooting
• 6: Contributing
• 6.1: Design Documentation
• 6.1.1: AI Skill Framework Design
• 6.1.2: Guru Philosophy
• 6.1.3: IR Classic Migration and Namespace Strategy
• 6.1.4: Guru Creation Guide
• 6.1.5: Technical Writer Skill Requirements
• 6.1.6: Product Requirements Documents
• 6.1.6.1: PRD: IR JSON Schema Verification
• 6.1.6.2: BDD Test Scenarios: IR JSON Schema Verification
• 6.1.6.3: PRD: Product Manager Skill for Morphir Ecosystem
• 6.1.6.4: PRD: Deployment Architecture Refactor
• 6.1.6.5: PRD: Layered Configuration
• 6.1.6.6: Vulnerability Resolver Skill Requirements
• 6.1.7:
• 6.1.8:
• 6.1.9:
• 6.2: QA & Testing
• 6.2.1: Phase 1 Test Plan
• 6.2.2: GitHub Copilot Skill Emulation Test Plan
• 6.2.3: GitHub Copilot Skill Emulation Execution Report
• 6.2.4: Copilot Skill Emulation Scenarios Runner

1 - Getting Started

Installation

Prerequisites

• .NET SDK 10.0 or higher
• Mono if you’re on Linux or macOS

Install Morphir CLI

dotnet tool install -g Morphir

Verify Installation

morphir --version

Your First Project

1. Create a New Project

dotnet new console -n MyMorphirProject
cd MyMorphirProject

2. Add Morphir.Core Package

dotnet add package Morphir.Core

3. Build Your Project

dotnet build

Next Steps

• Learn about Morphir IR modeling
• Explore the API Reference
• Check out examples and guides

1.1 - Installation

Requirements

• .NET SDK 10.0 or higher
• Mono (for Linux/macOS)

Installation Methods

Global Tool Installation

Install Morphir as a global .NET tool:

dotnet tool install -g Morphir

Local Project Installation

Add Morphir to your project:

dotnet add package Morphir
dotnet add package Morphir.Core

Build from Source

git clone https://github.com/finos/morphir-dotnet.git
cd morphir-dotnet
dotnet build

Verify Installation

Check that Morphir is installed correctly:

morphir info

Troubleshooting

Command Not Found

If the morphir command is not found after installation:

1. Ensure the .NET tools directory is in your PATH:

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

2. Restart your terminal or run:

   source ~/.bashrc  # or ~/.zshrc
   

Version Conflicts

If you encounter version conflicts, check your global.json file and ensure you’re using the correct .NET SDK version.

1.2 - Validating IR Files

Validating Morphir IR Files

This guide will help you get started with validating Morphir IR JSON files using the morphir ir verify command.

Prerequisites

• Morphir .NET CLI installed (see Installation)
• A Morphir IR JSON file to validate

Quick Start

1. Validate Your First IR File

The simplest way to validate an IR file is to run:

morphir ir verify morphir-ir.json

If the IR is valid, you’ll see:

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

No validation errors found.

2. Understanding the Output

The validation output includes:

• Validation Result: ✓ VALID or ✗ INVALID
• File: The path to the validated file
• Schema Version: Which schema version was used (and how it was detected)
• Timestamp: When the validation was performed
• Errors: Detailed error messages (if validation failed)

3. Handling Validation Errors

If validation fails, you’ll see detailed error messages:

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

Found 1 validation error(s):

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

Each error includes:

• Path: JSON path to the error location
• Message: Description of what’s wrong
• Expected: What the schema expects
• Found: What was actually found

Common Scenarios

Validating Multiple Files

To validate all IR files in a directory:

# Validate all JSON files
for file in *.json; do
  echo "Validating $file..."
  morphir ir verify "$file" || exit 1
done

Or in parallel:

find . -name "morphir-ir.json" -exec morphir ir verify {} \;

CI/CD Integration

Add validation to your CI/CD pipeline:

GitHub Actions:

steps:
  - name: Install Morphir CLI
    run: dotnet tool install -g Morphir.CLI

  - name: Validate IR
    run: morphir ir verify output/morphir-ir.json

GitLab CI:

validate-ir:
  stage: test
  script:
    - dotnet tool install -g Morphir.CLI
    - morphir ir verify output/morphir-ir.json

Using Different Output Formats

JSON Output (for parsing in scripts):

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

# Check if valid
cat validation-result.json | jq '.IsValid'

Quiet Mode (for CI/CD):

# Only shows output if validation fails
morphir ir verify --quiet morphir-ir.json

# Check exit code
if morphir ir verify --quiet morphir-ir.json; then
  echo "IR is valid"
fi

Specifying Schema Version

If you need to validate against a specific schema version:

# Validate against v3 schema
morphir ir verify --schema-version 3 morphir-ir.json

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

Understanding Schema Versions

Morphir IR has three schema versions:

The CLI automatically detects the version by examining the JSON structure.

Next Steps

Learn More

• CLI Reference - Complete command documentation
• morphir ir verify - Detailed command reference
• Troubleshooting - Solutions to common issues

Advanced Topics

• Schema Specifications - Understand the IR schema structure
• Error Messages - Detailed error reference
• Batch Validation (Phase 2 - coming soon)
• Custom Validation Rules (Phase 3 - planned)

Common Pitfalls

1. JSON Syntax Errors

Problem: Malformed JSON will fail validation

Solution: Validate JSON syntax first:

cat morphir-ir.json | jq . > /dev/null && echo "Valid JSON"

2. Wrong formatVersion Value

Problem: File has "formatVersion": "3" (string) instead of "formatVersion": 3 (number)

Solution: Ensure formatVersion is a number:

// Incorrect
{
  "formatVersion": "3",
  ...
}

// Correct
{
  "formatVersion": 3,
  ...
}

3. Case Sensitivity in Tags

Problem: Tags must use correct capitalization

Solution: Use "Public" not "public", "Private" not "private"

// Incorrect
"accessControl": "public"

// Correct
"accessControl": "Public"

Example Workflow

Here’s a complete workflow for validating IR in your project:

#!/bin/bash
set -e

echo "=== Morphir IR Validation Workflow ==="

# 1. Generate IR (example using hypothetical compiler)
echo "Step 1: Generating IR..."
morphir-elm make --output output/morphir-ir.json

# 2. Validate IR
echo "Step 2: Validating IR..."
if morphir ir verify output/morphir-ir.json; then
  echo "✓ IR is valid"
else
  echo "✗ IR validation failed"
  exit 1
fi

# 3. Generate detailed report
echo "Step 3: Generating validation report..."
morphir ir verify --json output/morphir-ir.json > validation-report.json

# 4. Check for any warnings (future feature)
echo "Step 4: Checking for warnings..."
# (Future: morphir ir lint output/morphir-ir.json)

echo "=== Workflow Complete ==="

Getting Help

If you run into issues:

1. Check the Troubleshooting Guide
2. Review Common Error Messages
3. Ask in GitHub Discussions
4. Report bugs in GitHub Issues

2 - Guides

Explore our guides to learn how to use Morphir .NET effectively.

Available Guides

• IR Modeling - Learn how to model Morphir IR in .NET
• Serialization - Working with JSON serialization
• Testing - Testing strategies and best practices

Best Practices

• Immutability First: Always prefer immutable data structures
• ADT Design: Use algebraic data types to make illegal states unrepresentable
• Type Safety: Leverage C# 14 features for strong typing
• Testing: Write comprehensive tests using TUnit and Reqnroll

2.1 - IR Modeling

Overview

Morphir IR (Intermediate Representation) is the core data structure that represents your business logic. In Morphir .NET, we model the IR using C# record types and algebraic data types (ADTs).

Type Expressions

Type expressions represent the types in your Morphir model:

public abstract record TypeExpr
{
    public sealed record TInt() : TypeExpr;
    public sealed record TString() : TypeExpr;
    public sealed record TBool() : TypeExpr;
    public sealed record TTuple(IReadOnlyList<TypeExpr> Items) : TypeExpr;
    public sealed record TRecord(IReadOnlyDictionary<string, TypeExpr> Fields) : TypeExpr;
    public sealed record TFunc(TypeExpr Input, TypeExpr Output) : TypeExpr;
}

Value Expressions

Value expressions represent the actual values and computations:

public abstract record ValueExpr
{
    public sealed record Literal(LiteralValue Value) : ValueExpr;
    public sealed record Variable(string Name) : ValueExpr;
    public sealed record Lambda(string Parameter, TypeExpr ParameterType, ValueExpr Body) : ValueExpr;
    public sealed record Apply(ValueExpr Function, ValueExpr Argument) : ValueExpr;
}

Best Practices

1. Use Records: Prefer record types for immutable data structures
2. Pattern Matching: Use exhaustive pattern matching for ADTs
3. Validation: Implement smart constructors for validated types
4. Immutability: Keep all types immutable

Example

Here’s a complete example of modeling a simple function:

var addFunction = new ValueExpr.Lambda(
    Parameter: "x",
    ParameterType: new TypeExpr.TInt(),
    Body: new ValueExpr.Lambda(
        Parameter: "y",
        ParameterType: new TypeExpr.TInt(),
        Body: new ValueExpr.Apply(
            Function: new ValueExpr.Variable("+"),
            Argument: new ValueExpr.Tuple(new[]
            {
                new ValueExpr.Variable("x"),
                new ValueExpr.Variable("y")
            })
        )
    )
);

2.2 - Serialization

Overview

Morphir .NET provides JSON serialization support for Morphir IR, enabling interoperability with other Morphir tooling.

Basic Usage

Serializing IR to JSON

using Morphir.Core.IR;
using System.Text.Json;

var typeExpr = new TypeExpr.TInt();
var json = JsonSerializer.Serialize(typeExpr, new JsonSerializerOptions
{
    WriteIndented = true
});

Deserializing JSON to IR

var json = @"{""_tag"": ""TInt""}";
var typeExpr = JsonSerializer.Deserialize<TypeExpr>(json);

JSON Format

Morphir IR uses a tagged union format in JSON:

{
  "_tag": "TTuple",
  "items": [
    { "_tag": "TInt" },
    { "_tag": "TString" }
  ]
}

Custom Serialization

For custom serialization needs, you can implement your own converters:

public class CustomTypeExprConverter : JsonConverter<TypeExpr>
{
    // Implementation
}

Roundtrip Testing

Always test roundtrip serialization to ensure compatibility:

var original = new TypeExpr.TInt();
var json = JsonSerializer.Serialize(original);
var deserialized = JsonSerializer.Deserialize<TypeExpr>(json);
Assert.Equal(original, deserialized);

2.3 - Testing

Overview

Morphir .NET supports multiple testing approaches to ensure code quality and correctness.

Unit Testing with TUnit

TUnit is the primary unit testing framework:

using TUnit.Assertions;
using TUnit.Core;

public class TypeExprTests
{
    [Test]
    public void TInt_Should_Be_Equal()
    {
        var type1 = new TypeExpr.TInt();
        var type2 = new TypeExpr.TInt();
        
        Assert.That(type1).IsEqualTo(type2);
    }
}

Behavior-Driven Development with Reqnroll

Reqnroll enables BDD-style testing:

Feature: Type Expression Creation
  Scenario: Create an integer type
    Given I want to create a type expression
    When I create a TInt
    Then it should be a valid type expression

Property-Based Testing

Use property-based testing for invariant validation:

[Property]
public bool RoundtripSerialization(TypeExpr typeExpr)
{
    var json = JsonSerializer.Serialize(typeExpr);
    var deserialized = JsonSerializer.Deserialize<TypeExpr>(json);
    return typeExpr.Equals(deserialized);
}

Contract Testing

Test compatibility with Morphir IR format:

[Test]
public void Should_Roundtrip_With_Morphir_Elm()
{
    // Load canonical IR sample
    var json = File.ReadAllText("samples/canonical.json");
    var ir = JsonSerializer.Deserialize<IR>(json);
    
    // Serialize back
    var roundtrip = JsonSerializer.Serialize(ir);
    
    // Verify compatibility
    Assert.That(roundtrip).IsValidJson();
}

Best Practices

1. Exhaustive Testing: Test all ADT cases
2. Edge Cases: Test boundary conditions
3. Roundtrip Tests: Always test serialization roundtrips
4. Property Tests: Use property-based testing for invariants
5. Coverage: Maintain >= 80% code coverage

3 - Morphir IR Specification

Morphir IR Specification

This section contains the Morphir IR (Intermediate Representation) specification and related schema files.

Contents

• Morphir IR Specification: The complete Morphir IR specification document, describing the structure, semantics, and usage of the Morphir IR format.

• JSON Schemas: JSON schema definitions for all supported format versions of the Morphir IR:

  • morphir-ir-v3.yaml: Current format version (v3)
  • morphir-ir-v2.yaml: Format version 2
  • morphir-ir-v1.yaml: Format version 1

Purpose

This specification section serves as the authoritative reference for:

• Implementers: Building tools that generate, consume, or transform Morphir IR
• Developers: Working with Morphir IR in .NET and other platforms
• LLMs: Providing context for AI tools working with Morphir
• Tooling: Validating and processing Morphir IR JSON files

Related Resources

• Morphir Project
• Morphir Repository
• Morphir .NET Repository

3.1 - Morphir IR Specification

Morphir IR Specification

Overview

The Morphir Intermediate Representation (IR) is a language-independent, platform-agnostic representation of business logic and domain models. It serves as a universal format that captures the semantics of functional programs, enabling them to be transformed, analyzed, and executed across different platforms and languages.

Purpose

The Morphir IR specification defines:

• Building blocks: Core concepts and data structures that form the IR
• Relationships: How different components of the IR relate to and reference each other
• Semantics: The meaning and behavior of each construct

This specification is designed to:

• Guide implementers building tools that generate, consume, or transform Morphir IR
• Provide context for Large Language Models (LLMs) working with Morphir
• Serve as the authoritative reference for the Morphir IR structure

Design Principles

The Morphir IR follows these key principles:

• Functional: All logic is expressed as pure functions without side effects
• Type-safe: Complete type information is preserved throughout the IR
• Hierarchical: Code is organized in a hierarchical namespace (Package → Module → Type/Value)
• Naming-agnostic: Names are stored in a canonical format independent of any specific naming convention
• Explicit: All references are fully-qualified to eliminate ambiguity

Core Concepts

Naming

Morphir uses a sophisticated naming system that is independent of any specific naming convention (camelCase, snake_case, etc.). This allows the same IR to be rendered in different conventions for different platforms.

Name

A Name represents a human-readable identifier made up of one or more words.

• Structure: A list of lowercase word strings
• Purpose: Serves as the atomic unit for all identifiers
• Example: ["value", "in", "u", "s", "d"] can be rendered as:
  • valueInUSD (camelCase)
  • ValueInUSD (TitleCase)
  • value_in_USD (snake_case)

Path

A Path represents a hierarchical location in the IR structure.

• Structure: A list of Names
• Purpose: Identifies packages and modules within the hierarchy
• Example: [["morphir"], ["s", "d", "k"], ["string"]] represents the path to the String module

Qualified Name (QName)

A Qualified Name uniquely identifies a type or value within a package.

• Structure: A tuple of (module path, local name)
• Components:
  • Module path: The Path to the module
  • Local name: The Name of the type or value within that module
• Purpose: Identifies items relative to a package

Fully-Qualified Name (FQName)

A Fully-Qualified Name provides a globally unique identifier for any type or value.

• Structure: A tuple of (package path, module path, local name)
• Components:
  • Package path: The Path to the package
  • Module path: The Path to the module within the package
  • Local name: The Name of the type or value
• Purpose: Enables unambiguous references across package boundaries

Attributes and Annotations

The IR supports extensibility through attributes that can be attached to various nodes:

• Type attributes (ta): Extra information attached to type nodes (e.g., source location, type inference results)
• Value attributes (va): Extra information attached to value nodes (e.g., source location, inferred types)

When no additional information is needed, the unit type () is used as a placeholder.

Access Control

AccessControlled

An AccessControlled wrapper manages visibility of types and values.

• Structure: { access, value }
• Access levels:
  • Public: Visible to external consumers of the package
  • Private: Only visible within the package
• Purpose: Controls what parts of a package are exposed in its public API

Documented

A Documented wrapper associates documentation with IR elements.

• Structure: { doc, value }
• Components:
  • doc: A string containing documentation text
  • value: The documented element
• Purpose: Preserves documentation for types and values

Distribution

A Distribution represents a complete, self-contained package of Morphir code with all its dependencies.

Structure

Currently, Morphir supports a single distribution type: Library

A Library distribution contains:

• Package name: The globally unique identifier for the package (like NPM package name or Maven GroupId:ArtifactId)
• Dependencies: A dictionary mapping package names to their specifications
  • Dependencies only contain type signatures (specifications), not implementations
• Package definition: The complete implementation of the package
  • Contains all module definitions, including private modules
  • Includes both type signatures and implementations

Purpose

A distribution is:

• The output of the Morphir compilation process (e.g., morphir-elm make)
• A complete unit that can be executed, analyzed, or transformed
• Self-contained with all dependency information included

Package

A Package is a collection of modules that are versioned and distributed together. It corresponds to what package managers like NPM, NuGet, Maven, or pip consider a package.

Package Specification

A Package Specification provides the public interface of a package.

Structure:

• modules: A dictionary mapping module names (Paths) to Module Specifications

Characteristics:

• Contains only publicly exposed modules
• Types are only included if they are public
• Values are only included if they are public
• No implementation details are included

Package Definition

A Package Definition provides the complete implementation of a package.

Structure:

• modules: A dictionary mapping module names (Paths) to AccessControlled Module Definitions

Characteristics:

• Contains all modules (both public and private)
• All types are included (both public and private)
• All values are included with their implementations
• Each module is wrapped in AccessControlled to indicate its visibility

Package Name

A Package Name is the globally unique identifier for a package.

• Structure: A Path (list of Names)
• Examples: [["morphir"], ["s", "d", "k"]], [["my"], ["company"], ["models"]]
• Purpose: Uniquely identifies a package across all Morphir systems

Module

A Module groups related types and values together, similar to packages in Java or namespaces in other languages.

Module Specification

A Module Specification provides the public interface of a module.

Structure:

• types: Dictionary of type names to Documented Type Specifications
• values: Dictionary of value names to Documented Value Specifications
• doc: Optional documentation string for the module

Characteristics:

• Only includes publicly exposed types and values
• Contains type signatures but no implementations
• Documentation is preserved from the source

Module Definition

A Module Definition provides the complete implementation of a module.

Structure:

• types: Dictionary of type names to AccessControlled, Documented Type Definitions
• values: Dictionary of value names to AccessControlled, Documented Value Definitions
• doc: Optional documentation string for the module

Characteristics:

• Includes all types and values (public and private)
• Contains complete implementations
• Each type and value is wrapped in AccessControlled to indicate visibility
• Documentation is preserved from the source

Module Name

A Module Name uniquely identifies a module within a package.

• Structure: A Path (list of Names)
• Examples: [["morphir"], ["i", "r"], ["type"]], [["my"], ["module"]]

Qualified Module Name

A Qualified Module Name provides a globally unique module identifier.

• Structure: A tuple of (package path, module path)
• Purpose: Enables unambiguous module references across packages

Type System

The Morphir type system is based on functional programming principles, similar to languages like Elm, Haskell, or ML.

Type Expressions

A Type is a recursive tree structure representing type expressions. Each node can have type attributes attached.

Variable

Represents a type variable (generic parameter).

• Structure: Variable a Name
• Components:
  • a: Type attribute
  • Name: The variable name
• Example: The a in List a
• Purpose: Enables generic/polymorphic types

Reference

A reference to another type or type alias.

• Structure: Reference a FQName (List Type)
• Components:
  • a: Type attribute
  • FQName: Fully-qualified name of the referenced type
  • List Type: Type arguments (for generic types)
• Examples:
  • String → Reference a (["morphir"], ["s", "d", "k"], ["string"]) []
  • List Int → Reference a (["morphir"], ["s", "d", "k"], ["list"]) [intType]
• Purpose: Refers to built-in types, custom types, or type aliases

Tuple

A composition of multiple types in a fixed order.

• Structure: Tuple a (List Type)
• Components:
  • a: Type attribute
  • List Type: Element types in order
• Examples:
  • (Int, String) → Tuple a [intType, stringType]
  • (Int, Int, Bool) → Tuple a [intType, intType, boolType]
• Notes:
  • Zero-element tuple is equivalent to Unit
  • Single-element tuple is equivalent to the element type itself
• Purpose: Represents product types with positional access

Record

A composition of named fields with their types.

• Structure: Record a (List Field)
• Components:
  • a: Type attribute
  • List Field: List of field definitions
• Field structure: { name: Name, tpe: Type }
• Example: { firstName: String, age: Int }
• Notes:
  • Field order is preserved but not semantically significant
  • All fields are required (no optional fields)
• Purpose: Represents product types with named field access

ExtensibleRecord

A record type that can be extended with additional fields.

• Structure: ExtensibleRecord a Name (List Field)
• Components:
  • a: Type attribute
  • Name: Type variable representing the extension
  • List Field: Known fields
• Example: { a | firstName: String, age: Int } means “type a with at least these fields”
• Purpose: Enables flexible record types that can be extended

Function

Represents a function type.

• Structure: Function a Type Type
• Components:
  • a: Type attribute
  • First Type: Argument type
  • Second Type: Return type
• Examples:
  • Int -> String → Function a intType stringType
  • Int -> Int -> Bool → Function a intType (Function a intType boolType)
• Notes:
  • Multi-argument functions are represented via currying (nested Function types)
• Purpose: Represents the type of functions and lambdas

Unit

The type with exactly one value.

• Structure: Unit a
• Components:
  • a: Type attribute
• Purpose: Placeholder where a type is needed but the value is unused
• Corresponds to void in some languages

Type Specifications

A Type Specification defines the interface of a type without implementation details.

TypeAliasSpecification

An alias for another type.

• Structure: TypeAliasSpecification (List Name) Type
• Components:
  • List Name: Type parameters
  • Type: The aliased type expression
• Example: type alias UserId = String
• Purpose: Provides a meaningful name for a type expression

OpaqueTypeSpecification

A type with unknown structure.

• Structure: OpaqueTypeSpecification (List Name)
• Components:
  • List Name: Type parameters
• Characteristics:
  • Structure is hidden from consumers
  • Cannot be automatically serialized
  • Values can only be created and manipulated via provided functions
• Purpose: Encapsulates implementation details

CustomTypeSpecification

A tagged union type (sum type).

• Structure: CustomTypeSpecification (List Name) Constructors
• Components:
  • List Name: Type parameters
  • Constructors: Dictionary of constructor names to their arguments
• Constructor arguments: List (Name, Type) - list of named, typed arguments
• Example: type Result e a = Ok a | Err e
• Purpose: Represents choice between multiple alternatives

DerivedTypeSpecification

A type with platform-specific representation but known serialization.

• Structure: DerivedTypeSpecification (List Name) Details
• Details contain:
  • baseType: The type used for serialization
  • fromBaseType: FQName of function to convert from base type
  • toBaseType: FQName of function to convert to base type
• Example: A LocalDate might serialize to/from String with conversion functions
• Purpose: Enables platform-specific types while maintaining serialization capability

Type Definitions

A Type Definition provides the complete implementation of a type.

TypeAliasDefinition

Complete definition of a type alias.

• Structure: TypeAliasDefinition (List Name) Type
• Components:
  • List Name: Type parameters
  • Type: The complete type expression being aliased
• Same as specification (aliases have no hidden implementation)

CustomTypeDefinition

Complete definition of a custom type.

• Structure: CustomTypeDefinition (List Name) (AccessControlled Constructors)
• Components:
  • List Name: Type parameters
  • AccessControlled Constructors: Constructor definitions with visibility control
• If constructors are Private → specification becomes OpaqueTypeSpecification
• If constructors are Public → specification becomes CustomTypeSpecification
• Purpose: Allows hiding constructors while exposing the type

Value System

Values represent both data and logic in Morphir. All computations are expressed as value expressions.

Value Expressions

A Value is a recursive tree structure representing computations. Each node can have type and value attributes.

Literal

A literal constant value.

• Structure: Literal va Literal
• Components:
  • va: Value attribute
  • Literal: The literal value
• Supported literal types:
  • BoolLiteral: Boolean values (True, False)
  • CharLiteral: Single characters ('a', 'Z')
  • StringLiteral: Text strings ("hello")
  • WholeNumberLiteral: Integers (42, -17)
  • FloatLiteral: Floating-point numbers (3.14, -0.5)
  • DecimalLiteral: Arbitrary-precision decimals
• Purpose: Represents constant data

Constructor

Reference to a custom type constructor.

• Structure: Constructor va FQName
• Components:
  • va: Value attribute
  • FQName: Fully-qualified name of the constructor
• If the constructor has arguments, it will be wrapped in Apply nodes
• Example: Just in Maybe a, Ok in Result e a
• Purpose: Creates tagged union values

Tuple

A tuple value with multiple elements.

• Structure: Tuple va (List Value)
• Components:
  • va: Value attribute
  • List Value: Element values in order
• Example: (42, "hello", True)
• Purpose: Groups multiple values together with positional access

List

A list of values.

• Structure: List va (List Value)
• Components:
  • va: Value attribute
  • List Value: List elements
• Example: [1, 2, 3, 4]
• Purpose: Represents homogeneous sequences

Record

A record value with named fields.

• Structure: Record va (Dict Name Value)
• Components:
  • va: Value attribute
  • Dict Name Value: Dictionary mapping field names to values
• Example: { firstName = "John", age = 30 }
• Purpose: Represents structured data with named field access

Variable

Reference to a variable in scope.

• Structure: Variable va Name
• Components:
  • va: Value attribute
  • Name: Variable name
• Example: References to function parameters or let-bound variables
• Purpose: Accesses values bound in the current scope

Reference

Reference to a defined value (function or constant).

• Structure: Reference va FQName
• Components:
  • va: Value attribute
  • FQName: Fully-qualified name of the referenced value
• Example: Morphir.SDK.List.map, Basics.add
• Purpose: Invokes or references defined functions and constants

Field

Field access on a record.

• Structure: Field va Value Name
• Components:
  • va: Value attribute
  • Value: The record expression
  • Name: Field name to access
• Example: user.firstName → Field va (Variable va ["user"]) ["first", "name"]
• Purpose: Extracts a specific field from a record

FieldFunction

A function that extracts a field.

• Structure: FieldFunction va Name
• Components:
  • va: Value attribute
  • Name: Field name
• Example: .firstName creates a function \r -> r.firstName
• Purpose: Creates a field accessor function

Apply

Function application.

• Structure: Apply va Value Value
• Components:
  • va: Value attribute
  • First Value: The function
  • Second Value: The argument
• Multi-argument calls are represented via currying (nested Apply nodes)
• Example: add 1 2 → Apply va (Apply va (Reference va add) (Literal va 1)) (Literal va 2)
• Purpose: Invokes functions with arguments

Lambda

Anonymous function (lambda abstraction).

• Structure: Lambda va Pattern Value
• Components:
  • va: Value attribute
  • Pattern: Pattern matching the input
  • Value: Function body
• Example: \x -> x + 1 → Lambda va (AsPattern va (WildcardPattern va) ["x"]) (body)
• Purpose: Creates inline functions

LetDefinition

A let binding introducing a single value.

• Structure: LetDefinition va Name Definition Value
• Components:
  • va: Value attribute
  • Name: Binding name
  • Definition: Value definition being bound
  • Value: Expression where the binding is in scope
• Example: let x = 5 in x + x
• Purpose: Introduces local bindings

LetRecursion

Mutually recursive let bindings.

• Structure: LetRecursion va (Dict Name Definition) Value
• Components:
  • va: Value attribute
  • Dict Name Definition: Multiple bindings that can reference each other
  • Value: Expression where the bindings are in scope
• Purpose: Enables mutual recursion between bindings

Destructure

Pattern-based destructuring.

• Structure: Destructure va Pattern Value Value
• Components:
  • va: Value attribute
  • Pattern: Pattern to match
  • First Value: Expression to destructure
  • Second Value: Expression where extracted variables are in scope
• Example: let (x, y) = point in ...
• Purpose: Extracts values from structured data

IfThenElse

Conditional expression.

• Structure: IfThenElse va Value Value Value
• Components:
  • va: Value attribute
  • First Value: Condition
  • Second Value: Then branch
  • Third Value: Else branch
• Example: if x > 0 then "positive" else "non-positive"
• Purpose: Conditional logic

PatternMatch

Pattern matching with multiple cases.

• Structure: PatternMatch va Value (List (Pattern, Value))
• Components:
  • va: Value attribute
  • Value: Expression to match against
  • List (Pattern, Value): List of pattern-branch pairs
• Example: case maybeValue of Just x -> x; Nothing -> 0
• Purpose: Conditional logic based on structure

UpdateRecord

Record update expression.

• Structure: UpdateRecord va Value (Dict Name Value)
• Components:
  • va: Value attribute
  • Value: The record to update
  • Dict Name Value: Fields to update with new values
• Example: { user | age = 31 }
• Notes: This is copy-on-update (immutable)
• Purpose: Creates a modified copy of a record

Unit

The unit value.

• Structure: Unit va
• Components:
  • va: Value attribute
• Purpose: Represents the single value of the Unit type

Patterns

Patterns are used for destructuring and filtering values. They appear in lambda, let destructure, and pattern match expressions.

WildcardPattern

Matches any value without binding.

• Structure: WildcardPattern a
• Syntax: _ in source languages
• Purpose: Ignores a value

AsPattern

Binds a name to a value matched by a nested pattern.

• Structure: AsPattern a Pattern Name
• Components:
  • a: Pattern attribute
  • Pattern: Nested pattern
  • Name: Variable name to bind
• Syntax: pattern as name in source languages
• Special case: Simple variable binding is AsPattern a (WildcardPattern a) name
• Purpose: Captures matched values

TuplePattern

Matches a tuple by matching each element.

• Structure: TuplePattern a (List Pattern)
• Components:
  • a: Pattern attribute
  • List Pattern: Patterns for each tuple element
• Example: (x, y) matches a 2-tuple
• Purpose: Destructures tuples

ConstructorPattern

Matches a specific type constructor and its arguments.

• Structure: ConstructorPattern a FQName (List Pattern)
• Components:
  • a: Pattern attribute
  • FQName: Fully-qualified constructor name
  • List Pattern: Patterns for constructor arguments
• Example: Just x matches Just with pattern x
• Purpose: Destructures and filters tagged unions

EmptyListPattern

Matches an empty list.

• Structure: EmptyListPattern a
• Syntax: [] in source languages
• Purpose: Detects empty lists

HeadTailPattern

Matches a non-empty list by head and tail.

• Structure: HeadTailPattern a Pattern Pattern
• Components:
  • a: Pattern attribute
  • First Pattern: Matches the head element
  • Second Pattern: Matches the tail (remaining list)
• Syntax: x :: xs in source languages
• Purpose: Destructures lists recursively

LiteralPattern

Matches an exact literal value.

• Structure: LiteralPattern a Literal
• Components:
  • a: Pattern attribute
  • Literal: The exact value to match
• Example: 42, "hello", True
• Purpose: Filters by exact value

UnitPattern

Matches the unit value.

• Structure: UnitPattern a
• Purpose: Matches the Unit value

Value Specifications

A Value Specification defines the type signature of a value or function.

Structure:

• inputs: List of (Name, Type) pairs representing function parameters
• output: The return type

Characteristics:

• Contains only type information, no implementation
• Multi-argument functions list all parameters
• Zero-argument values (constants) have empty inputs list

Example: add : Int -> Int -> Int becomes:

{ inputs = [("a", Int), ("b", Int)]
, output = Int
}

Value Definitions

A Value Definition provides the complete implementation of a value or function.

Structure:

• inputTypes: List of (Name, va, Type) tuples for function parameters
  • Name: Parameter name
  • va: Value attribute for the parameter
  • Type: Parameter type
• outputType: The return type
• body: The value expression implementing the logic

Characteristics:

• Contains both type information and implementation
• Parameters are extracted from nested lambdas when possible
• Body contains the actual computation

Relationships Between Concepts

Hierarchical Structure

Distribution
  └─ Package (with dependencies)
      └─ Module
          ├─ Types
          │   └─ Type Definition/Specification
          └─ Values
              └─ Value Definition/Specification

Specifications vs Definitions

• Specifications: Public interface only

  • Used for dependencies
  • Contain type signatures only
  • Expose only public items

• Definitions: Complete implementation

  • Used for the package being compiled
  • Contain all details
  • Include both public and private items

Conversion Flow

Definition → Specification
  - Package Definition → Package Specification
  - Module Definition → Module Specification  
  - Type Definition → Type Specification
  - Value Definition → Value Specification

Specifications can be created with or without private items:

• definitionToSpecification: Public items only
• definitionToSpecificationWithPrivate: All items included

Reference Resolution

References in the IR are always fully-qualified:

1. Within expressions: References use FQName (package, module, local name)
2. Within modules: Items use local Names (looked up in module context)
3. Within packages: Modules use Paths (looked up in package context)

This eliminates ambiguity and enables:

• Easy dependency tracking
• Cross-package linking
• Independent processing of modules

Semantics

Type System Semantics

• Type Safety: All values have types; type checking ensures correctness
• Polymorphism: Type variables enable generic programming
• Structural Typing: Records and tuples are compared structurally
• Nominal Typing: Custom types are compared by name
• Immutability: All values are immutable; updates create new values

Value Evaluation Semantics

• Pure Functions: All functions are pure (no side effects)
• Eager Evaluation: Arguments are evaluated before function application
• Pattern Matching: Patterns are tested in order; first match wins
• Scope Rules:
  • Lambda parameters are in scope in the lambda body
  • Let bindings are in scope in the let expression body
  • Pattern variables are in scope in the associated branch

Access Control Semantics

• Public: Visible in package specifications; accessible to consumers
• Private: Only visible within package definition; not exposed
• Custom type constructors: Can be public (pattern matching allowed) or private (opaque type)

Usage Guidelines for Tool Implementers

Generating IR

When generating Morphir IR from source code:

1. Preserve names in canonical form: Convert all identifiers to lowercase word lists
2. Use fully-qualified references: Always include package and module paths
3. Maintain access control: Mark public vs private appropriately
4. Extract lambdas into function parameters: Use the inputTypes field instead of nested lambdas where possible
5. Preserve documentation: Include doc strings from source

Consuming IR

When consuming Morphir IR:

1. Respect access control: Only access public items from dependencies
2. Resolve references: Use the distribution to look up type and value definitions
3. Handle attributes: Be prepared for different attribute types or use unit type
4. Follow naming conventions: Use Name conversion utilities for target platform
5. Process hierarchically: Start from Distribution → Package → Module → Types/Values

Transforming IR

When transforming Morphir IR:

1. Preserve structure: Maintain the hierarchical organization
2. Update references consistently: If you rename items, update all references
3. Maintain type correctness: Ensure transformations preserve type safety
4. Handle both specifications and definitions: Transform both forms consistently
5. Preserve attributes: Carry forward attributes unless explicitly changing them

JSON Schema Specifications

To support tooling, validation, and interoperability, formal JSON schemas are provided for all supported format versions of the Morphir IR. These schemas are defined in YAML format for readability and include comprehensive documentation.

Available Schemas

• Format Version 3 (Current): The latest format version, which uses capitalized constructor tags (e.g., "Library", "Public", "Variable").

• Format Version 2: Uses capitalized distribution and type tags (e.g., "Library", "Public", "Variable") but lowercase value and pattern tags (e.g., "apply", "lambda", "as_pattern").

• Format Version 1: The original format version, which uses lowercase tags throughout (e.g., "library", "public") and a different module structure where modules have name and def fields.

Key Differences Between Versions

Format Version 1 → 2

• Distribution tag: Changed from "library" to "Library"
• Access control: Changed from "public"/"private" to "Public"/"Private"
• Module structure: Changed from {"name": ..., "def": ...} to array-based [modulePath, accessControlled]
• Type tags: Changed to capitalized forms (e.g., "variable" → "Variable")

Format Version 2 → 3

• Value expression tags: Changed from lowercase to capitalized (e.g., "apply" → "Apply")
• Pattern tags: Changed from lowercase with underscores to capitalized (e.g., "as_pattern" → "AsPattern")
• Literal tags: Changed from lowercase with underscores to capitalized (e.g., "bool_literal" → "BoolLiteral")

Using the Schemas

The JSON schemas can be used for:

1. Validation: Validate Morphir IR JSON files against the appropriate version schema
2. Documentation: Understand the structure and constraints of the IR format
3. Code Generation: Generate parsers, serializers, and type definitions for various languages
4. Tooling: Build editors, linters, and other tools that work with Morphir IR

Example validation using a JSON schema validator:

# Using Python jsonschema (recommended for YAML schemas)
pip install jsonschema pyyaml
python -c "import json, yaml, jsonschema; \
  schema = yaml.safe_load(open('docs/content/spec/schemas/morphir-ir-v3.yaml')); \
  data = json.load(open('morphir-ir.json')); \
  jsonschema.validate(data, schema); \
  print('✓ Valid Morphir IR')"

# Using ajv-cli (Node.js) - requires converting YAML to JSON first
npm install -g ajv-cli
python -c "import yaml, json; \
  json.dump(yaml.safe_load(open('docs/content/spec/schemas/morphir-ir-v3.yaml')), \
  open('morphir-ir-v3.json', 'w'))"
ajv validate -s morphir-ir-v3.json -d morphir-ir.json

Schema Location

All schemas are located in the docs/content/spec/schemas/ directory of the Morphir .NET repository:

• docs/content/spec/schemas/morphir-ir-v1.yaml
• docs/content/spec/schemas/morphir-ir-v2.yaml
• docs/content/spec/schemas/morphir-ir-v3.yaml

Conclusion

The Morphir IR provides a comprehensive, type-safe representation of functional business logic. Its design enables:

• Portability: Same logic can target multiple platforms
• Analysis: Logic can be analyzed for correctness and properties
• Transformation: Logic can be optimized and adapted
• Tooling: Rich development tools can be built on a standard format
• Interoperability: Different languages can share logic via IR

This specification defines the structure and semantics necessary for building a robust ecosystem of Morphir tools and ensuring consistent interpretation across implementations. The accompanying JSON schemas provide formal, machine-readable definitions that can be used for validation, code generation, and tooling support.

3.2 - JSON Schemas

Morphir IR JSON Schemas

This directory contains formal JSON schema specifications for all supported format versions of the Morphir IR (Intermediate Representation).

Schema Files

• morphir-ir-v3.yaml: Current format version (v3)
• morphir-ir-v2.yaml: Format version 2
• morphir-ir-v1.yaml: Format version 1

Format Version Differences

Version 1 → Version 2

Tag Capitalization:

• Distribution: "library" → "Library"
• Access control: "public"/"private" → "Public"/"Private"
• Type tags: "variable" → "Variable", "reference" → "Reference", etc.

Structure Changes:

• Modules changed from {"name": ..., "def": ...} objects to [modulePath, accessControlled] arrays

Version 2 → Version 3

Tag Capitalization:

• Value expression tags: "apply" → "Apply", "lambda" → "Lambda", etc.
• Pattern tags: "as_pattern" → "AsPattern", "wildcard_pattern" → "WildcardPattern", etc.
• Literal tags: "bool_literal" → "BoolLiteral", "string_literal" → "StringLiteral", etc.

Usage

Validation

The schemas can be used to validate Morphir IR JSON files. Note that due to the complexity and recursive nature of these schemas, validation can be slow with some validators.

Using Python jsonschema

pip install jsonschema pyyaml

python3 << 'EOF'
import json
import yaml
from jsonschema import validate

# Load schema
with open('morphir-ir-v3.yaml', 'r') as f:
    schema = yaml.safe_load(f)

# Load Morphir IR JSON
with open('morphir-ir.json', 'r') as f:
    data = json.load(f)

# Validate
validate(instance=data, schema=schema)
print("✓ Valid Morphir IR")
EOF

Using Node.js ajv

npm install -g ajv-cli ajv-formats

# Convert YAML to JSON first
python3 -c "import yaml, json; \
  json.dump(yaml.safe_load(open('morphir-ir-v3.yaml')), open('morphir-ir-v3.json', 'w'))"

# Validate
ajv validate -s morphir-ir-v3.json -d morphir-ir.json

Quick Structural Check

For a quick check without full validation, you can verify basic structure:

import json

def check_morphir_ir(filepath):
    with open(filepath) as f:
        data = json.load(f)
    
    # Check format version
    version = data.get('formatVersion')
    assert version in [1, 2, 3], f"Unknown format version: {version}"
    
    # Check distribution structure
    dist = data['distribution']
    assert isinstance(dist, list) and len(dist) == 4
    assert dist[0] in ["library", "Library"], f"Unknown distribution type: {dist[0]}"
    
    # Check package definition
    pkg_def = dist[3]
    assert 'modules' in pkg_def
    
    print(f"✓ Basic structure valid: Format v{version}, {len(pkg_def['modules'])} modules")

check_morphir_ir('morphir-ir.json')

Integration with Tools

These schemas can be used to:

1. Generate Code: Create type definitions and parsers for various programming languages
2. IDE Support: Provide autocomplete and validation in JSON editors
3. Testing: Validate generated IR in test suites
4. Documentation: Generate human-readable documentation from schema definitions

Schema Format

The schemas are written in YAML format for better readability and include:

• Comprehensive inline documentation
• Type constraints and patterns
• Required vs. optional fields
• Recursive type definitions
• Enum values for tagged unions

Contributing

When updating the IR format:

1. Update the appropriate schema file(s) to match the upstream schemas from the main Morphir repository
2. Update the format version handling in the .NET codec implementation if needed
3. Add migration logic in the codec files if needed
4. Update this README with the changes
5. Test the schema against example IR files

References

• Morphir Project
• Morphir Repository
• JSON Schema Specification
• YAML Format

3.2.1 - Schema Version 3

Morphir IR Schema - Version 3

Format version 3 is the current version of the Morphir IR format. It uses capitalized tags throughout for consistency and clarity.

Overview

Version 3 of the Morphir IR format standardizes on capitalized tags for all constructs. This provides a consistent naming convention across the entire IR structure.

Key Characteristics

Tag Capitalization

All tags in version 3 are capitalized:

• Distribution: "Library"
• Access Control: "Public" and "Private"
• Type Tags: "Variable", "Reference", "Tuple", "Record", etc.
• Value Tags: "Apply", "Lambda", "LetDefinition", etc.
• Pattern Tags: "AsPattern", "WildcardPattern", "ConstructorPattern", etc.
• Literal Tags: "BoolLiteral", "StringLiteral", "WholeNumberLiteral", etc.

Core Concepts

Naming System

The Morphir IR uses a sophisticated naming system independent of any specific naming convention.

Name

A Name represents a human-readable identifier made up of one or more words.

• Structure: Array of lowercase word strings
• Purpose: Atomic unit for all identifiers
• Example: ["value", "in", "u", "s", "d"] renders as valueInUSD or value_in_USD

Name:
  type: array
  items:
    type: string
    pattern: "^[a-z][a-z0-9]*$"
  minItems: 1

Path

A Path represents a hierarchical location in the IR structure.

• Structure: List of Names
• Purpose: Identifies packages and modules
• Example: [["morphir"], ["s", "d", "k"], ["string"]] for the String module

Path:
  type: array
  items:
    $ref: "#/definitions/Name"
  minItems: 1

Fully-Qualified Name (FQName)

Provides globally unique identifiers for types and values.

• Structure: [packagePath, modulePath, localName]
• Purpose: Unambiguous references across package boundaries

FQName:
  type: array
  minItems: 3
  maxItems: 3
  items:
    - $ref: "#/definitions/PackageName"
    - $ref: "#/definitions/ModuleName"
    - $ref: "#/definitions/Name"

Access Control

AccessControlled

Manages visibility of types and values.

• Structure: {access, value}
• Access levels: "Public" (visible externally) or "Private" (package-only)
• Purpose: Controls API exposure

AccessControlled:
  type: object
  required: ["access", "value"]
  properties:
    access:
      type: string
      enum: ["Public", "Private"]
    value:
      description: "The value being access controlled."

Distribution and Package Structure

Distribution

A Distribution represents a complete, self-contained package with all dependencies.

• Current type: Library (only supported distribution type)
• Structure: ["Library", packageName, dependencies, packageDefinition]
• Purpose: Output of compilation process, ready for execution or transformation

distribution:
  type: array
  minItems: 4
  maxItems: 4
  items:
    - type: string
      const: "Library"
    - $ref: "#/definitions/PackageName"
    - $ref: "#/definitions/Dependencies"
    - $ref: "#/definitions/PackageDefinition"

Package Definition

Complete implementation of a package with all details.

• Contains: All modules (public and private)
• Includes: Type signatures and implementations
• Purpose: Full package representation for processing

Package Specification

Public interface of a package.

• Contains: Only publicly exposed modules
• Includes: Only type signatures, no implementations
• Purpose: Dependency interface

Module Structure

Module Definition

Complete implementation of a module.

• Contains: All types and values (public and private) with implementations
• Structure: Dictionary of type names to AccessControlled type definitions, and value names to AccessControlled value definitions
• Purpose: Complete module implementation

Module Specification

Public interface of a module.

• Contains: Only publicly exposed types and values
• Includes: Type signatures only, no implementations
• Purpose: Module’s public API

Type System

The type system is based on functional programming principles, supporting:

Type Expressions

Variable

Represents a type variable (generic parameter).

• Structure: ["Variable", attributes, name]
• Example: The a in List a
• Purpose: Enables polymorphic types

VariableType:
  type: array
  minItems: 3
  maxItems: 3
  items:
    - const: "Variable"
    - $ref: "#/definitions/Attributes"
    - $ref: "#/definitions/Name"

Reference

Reference to another type or type alias.

• Structure: ["Reference", attributes, fqName, typeArgs]
• Examples: String, List Int, Maybe a
• Purpose: References built-in types, custom types, or type aliases

ReferenceType:
  type: array
  minItems: 4
  maxItems: 4
  items:
    - const: "Reference"
    - $ref: "#/definitions/Attributes"
    - $ref: "#/definitions/FQName"
    - type: array
      items:
        $ref: "#/definitions/Type"

Tuple

Composition of multiple types in fixed order.

• Structure: ["Tuple", attributes, elementTypes]
• Example: (Int, String, Bool)
• Purpose: Product types with positional access

Record

Composition of named fields with types.

• Structure: ["Record", attributes, fields]
• Example: {firstName: String, age: Int}
• Purpose: Product types with named field access
• Note: All fields are required

Function

Function type representation.

• Structure: ["Function", attributes, argType, returnType]
• Example: Int -> String
• Purpose: Represents function and lambda types
• Note: Multi-argument functions use currying (nested Function types)

Type Specifications

TypeAliasSpecification

An alias for another type.

• Structure: ["TypeAliasSpecification", typeParams, aliasedType]
• Example: type alias UserId = String
• Purpose: Meaningful name for type expression

CustomTypeSpecification

Tagged union type (sum type).

• Structure: ["CustomTypeSpecification", typeParams, constructors]
• Example: type Result e a = Ok a | Err e
• Purpose: Choice between multiple alternatives

OpaqueTypeSpecification

Type with unknown structure.

• Structure: ["OpaqueTypeSpecification", typeParams]
• Characteristics: Structure hidden, no automatic serialization
• Purpose: Encapsulates implementation details

Value System

All data and logic in Morphir are represented as value expressions.

Value Expressions

Literal

Literal constant value.

• Structure: ["Literal", attributes, literal]
• Types: BoolLiteral, CharLiteral, StringLiteral, WholeNumberLiteral, FloatLiteral, DecimalLiteral
• Purpose: Represents constant data

Variable

Reference to a variable in scope.

• Structure: ["Variable", attributes, name]
• Example: References to function parameters or let-bound variables
• Purpose: Accesses values bound in current scope

Reference

Reference to a defined value (function or constant).

• Structure: ["Reference", attributes, fqName]
• Example: Morphir.SDK.List.map, Basics.add
• Purpose: Invokes or references defined functions

Apply

Function application.

• Structure: ["Apply", attributes, function, argument]
• Example: add 1 2 (nested Apply nodes for currying)
• Purpose: Invokes functions with arguments

Lambda

Anonymous function.

• Structure: ["Lambda", attributes, argumentPattern, body]
• Example: \x -> x + 1
• Purpose: Creates inline functions

LetDefinition

Let binding introducing a single value.

• Structure: ["LetDefinition", attributes, bindingName, definition, inExpr]
• Example: let x = 5 in x + x
• Purpose: Introduces local bindings

IfThenElse

Conditional expression.

• Structure: ["IfThenElse", attributes, condition, thenBranch, elseBranch]
• Example: if x > 0 then "positive" else "non-positive"
• Purpose: Conditional logic

PatternMatch

Pattern matching with multiple cases.

• Structure: ["PatternMatch", attributes, valueToMatch, cases]
• Example: case maybeValue of Just x -> x; Nothing -> 0
• Purpose: Conditional logic based on structure

Patterns

Used for destructuring and filtering values.

WildcardPattern

Matches any value without binding.

• Structure: ["WildcardPattern", attributes]
• Syntax: _
• Purpose: Ignores a value

AsPattern

Binds a name to a matched value.

• Structure: ["AsPattern", attributes, nestedPattern, variableName]
• Special case: Simple variable binding uses AsPattern with WildcardPattern
• Purpose: Captures matched values

ConstructorPattern

Matches specific type constructor and arguments.

• Structure: ["ConstructorPattern", attributes, fqName, argPatterns]
• Example: Just x matches Just with pattern x
• Purpose: Destructures and filters tagged unions

Literals

BoolLiteral

Boolean literal.

• Structure: ["BoolLiteral", boolean]
• Values: true or false

BoolLiteral:
  type: array
  minItems: 2
  maxItems: 2
  items:
    - const: "BoolLiteral"
    - type: boolean

StringLiteral

Text string literal.

• Structure: ["StringLiteral", string]
• Example: "hello"

StringLiteral:
  type: array
  minItems: 2
  maxItems: 2
  items:
    - const: "StringLiteral"
    - type: string

WholeNumberLiteral

Integer literal.

• Structure: ["WholeNumberLiteral", integer]
• Example: 42, -17

Recommended Format

Version 3 is the recommended format for new Morphir IR files. It provides:

• Consistency: All tags follow the same capitalization convention
• Clarity: Capitalized tags are easier to distinguish in JSON
• Future-proof: This format will be maintained going forward

Full Schema

For the complete schema definition, see the full schema page.

References

• Morphir IR Specification
• Schema Version 1
• Schema Version 2

3.2.1.1 - What's New in Version 3

What’s New in Version 3

Version 3 of the Morphir IR schema introduces consistent capitalization across all tags, providing a uniform and predictable format.

Key Changes from Version 2

Consistent Capitalization

The primary change in version 3 is the complete capitalization of all tags throughout the schema:

Value Expression Tags

All value expression tags are now capitalized:

• "apply" → "Apply"
• "lambda" → "Lambda"
• "let_definition" → "LetDefinition"
• "if_then_else" → "IfThenElse"
• "pattern_match" → "PatternMatch"
• "literal" → "Literal"
• "variable" → "Variable"
• "reference" → "Reference"
• "constructor" → "Constructor"
• "tuple" → "Tuple"
• "list" → "List"
• "record" → "Record"
• "field" → "Field"
• "field_function" → "FieldFunction"
• "let_recursion" → "LetRecursion"
• "destructure" → "Destructure"
• "update_record" → "UpdateRecord"
• "unit" → "Unit"

Pattern Tags

All pattern tags are now capitalized:

• "wildcard_pattern" → "WildcardPattern"
• "as_pattern" → "AsPattern"
• "tuple_pattern" → "TuplePattern"
• "constructor_pattern" → "ConstructorPattern"
• "empty_list_pattern" → "EmptyListPattern"
• "head_tail_pattern" → "HeadTailPattern"
• "literal_pattern" → "LiteralPattern"
• "unit_pattern" → "UnitPattern"

Literal Tags

All literal tags are now capitalized:

• "bool_literal" → "BoolLiteral"
• "char_literal" → "CharLiteral"
• "string_literal" → "StringLiteral"
• "whole_number_literal" → "WholeNumberLiteral"
• "float_literal" → "FloatLiteral"
• "decimal_literal" → "DecimalLiteral"

Benefits

Consistency

Version 3 provides a single, uniform naming convention across the entire IR structure. This makes the schema:

• Easier to remember: One rule applies everywhere
• More predictable: All tags follow PascalCase capitalization
• Cleaner to work with: No need to remember which tags use underscores or lowercase

Better Tooling Support

The consistent capitalization improves:

• Code generation: Automated tools can rely on uniform naming
• Serialization/Deserialization: Simplified mapping to programming language types
• Validation: Easier to write validation rules and tests

Migration from Version 2

Migrating from version 2 to version 3 requires updating all lowercase and underscore-separated tags:

1. Capitalize all value tags
2. Capitalize all pattern tags
3. Capitalize all literal tags
4. Remove underscores and use PascalCase

Recommendation

Version 3 is the current and recommended format for all new Morphir IR files. It provides the best balance of consistency, clarity, and tooling support.

See Also

• Version 3 Overview
• Full Schema
• Migration from Version 2

3.2.1.2 - Full Schema

Morphir IR Schema Version 3 - Complete Schema

This page contains the complete JSON schema definition for Morphir IR format version 3 (current version).

Download

You can download the schema file directly: morphir-ir-v3.yaml

Usage

This schema can be used to validate Morphir IR JSON files in format version 3:

# Using Python jsonschema (recommended for YAML schemas)
pip install jsonschema pyyaml
python -c "import json, yaml, jsonschema; \
  schema = yaml.safe_load(open('morphir-ir-v3.yaml')); \
  data = json.load(open('your-morphir-ir.json')); \
  jsonschema.validate(data, schema); \
  print('✓ Valid Morphir IR')"

References

• Schema Version 3 Documentation
• Morphir IR Specification

Appendix: Complete Schema Definition

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992

# JSON Schema for Morphir IR Format Version 3
# This schema defines the structure of a Morphir IR distribution in version 3 format.
# A distribution is the output of the Morphir compilation process (e.g., morphir-elm make).

$schema: "http://json-schema.org/draft-07/schema#"
$id: "https://finos.github.io/morphir/schemas/morphir-ir-v3.yaml"
title: "Morphir IR Distribution"
description: |
  A Morphir IR distribution represents a complete, self-contained package of business logic
  with all its dependencies. It captures the semantics of functional programs in a
  language-independent, platform-agnostic format.

type: object
required:
  - formatVersion
  - distribution
properties:
  formatVersion:
    type: integer
    const: 3
    description: "The version of the IR format. Must be 3 for this schema."
  
  distribution:
    description: "The distribution data, currently only Library distributions are supported."
    type: array
    minItems: 4
    maxItems: 4
    items:
      - type: string
        const: "Library"
        description: "The type of distribution. Currently only Library is supported."
      - $ref: "#/definitions/PackageName"
      - $ref: "#/definitions/Dependencies"
      - $ref: "#/definitions/PackageDefinition"

definitions:
  # ===== Basic Building Blocks =====
  
  Name:
    type: array
    items:
      type: string
      pattern: "^[a-z][a-z0-9]*$"
    minItems: 1
    description: |
      A Name is a list of lowercase words that represents a human-readable identifier.
      Example: ["value", "in", "u", "s", "d"] can be rendered as valueInUSD or value_in_USD.
  
  Path:
    type: array
    items:
      $ref: "#/definitions/Name"
    minItems: 1
    description: |
      A Path is a list of Names representing a hierarchical location in the IR structure.
      Used for package names and module names.
  
  PackageName:
    $ref: "#/definitions/Path"
    description: "Globally unique identifier for a package."
  
  ModuleName:
    $ref: "#/definitions/Path"
    description: "Unique identifier for a module within a package."
  
  FQName:
    type: array
    minItems: 3
    maxItems: 3
    items:
      - $ref: "#/definitions/PackageName"
      - $ref: "#/definitions/ModuleName"
      - $ref: "#/definitions/Name"
    description: |
      Fully-Qualified Name that provides a globally unique identifier for any type or value.
      Consists of [packagePath, modulePath, localName].
  
  # ===== Attributes =====
  
  Attributes:
    type: object
    description: |
      Attributes can be attached to various nodes in the IR for extensibility.
      When no additional information is needed, an empty object {} is used.
  
  # ===== Access Control =====
  
  AccessControlled:
    type: object
    required: ["access", "value"]
    properties:
      access:
        type: string
        enum: ["Public", "Private"]
        description: "Controls visibility of types and values."
      value:
        description: "The value being access controlled."
    description: "Wrapper that manages visibility of types and values."
  
  # Note: Documented is not a separate schema definition because it's encoded conditionally.
  # When documentation exists, the JSON has both "doc" and "value" fields.
  # When documentation is absent, the JSON contains only the documented element directly (no wrapper).
  # This is handled inline in the definitions that use Documented.
  
  # ===== Distribution Structure =====
  
  Dependencies:
    type: array
    items:
      type: array
      minItems: 2
      maxItems: 2
      items:
        - $ref: "#/definitions/PackageName"
        - $ref: "#/definitions/PackageSpecification"
    description: "Dictionary of package dependencies, contains only type signatures."
  
  PackageDefinition:
    type: object
    required: ["modules"]
    properties:
      modules:
        type: array
        items:
          type: array
          minItems: 2
          maxItems: 2
          items:
            - $ref: "#/definitions/ModuleName"
            - allOf:
                - $ref: "#/definitions/AccessControlled"
                - properties:
                    value:
                      $ref: "#/definitions/ModuleDefinition"
        description: "All modules in the package (public and private)."
    description: "Complete implementation of a package with all details."
  
  PackageSpecification:
    type: object
    required: ["modules"]
    properties:
      modules:
        type: array
        items:
          type: array
          minItems: 2
          maxItems: 2
          items:
            - $ref: "#/definitions/ModuleName"
            - $ref: "#/definitions/ModuleSpecification"
        description: "Public modules only."
    description: "Public interface of a package, contains only type signatures."
  
  # ===== Module Structure =====
  
  ModuleDefinition:
    type: object
    required: ["types", "values"]
    properties:
      types:
        type: array
        items:
          type: array
          minItems: 2
          maxItems: 2
          items:
            - $ref: "#/definitions/Name"
            - allOf:
                - $ref: "#/definitions/AccessControlled"
                - properties:
                    value:
                      # Documented wrapper: can have "doc" and "value", or just the type definition directly
                      oneOf:
                        - type: object
                          required: ["doc", "value"]
                          properties:
                            doc:
                              type: string
                            value:
                              $ref: "#/definitions/TypeDefinition"
                        - $ref: "#/definitions/TypeDefinition"
        description: "All type definitions (public and private)."
      values:
        type: array
        items:
          type: array
          minItems: 2
          maxItems: 2
          items:
            - $ref: "#/definitions/Name"
            - allOf:
                - $ref: "#/definitions/AccessControlled"
                - properties:
                    value:
                      # Documented wrapper: can have "doc" and "value", or just the value definition directly
                      oneOf:
                        - type: object
                          required: ["doc", "value"]
                          properties:
                            doc:
                              type: string
                            value:
                              $ref: "#/definitions/ValueDefinition"
                        - $ref: "#/definitions/ValueDefinition"
        description: "All value definitions (public and private)."
      doc:
        type: string
        description: "Optional documentation for the module."
    description: "Complete implementation of a module."
  
  ModuleSpecification:
    type: object
    required: ["types", "values"]
    properties:
      types:
        type: array
        items:
          type: array
          minItems: 2
          maxItems: 2
          items:
            - $ref: "#/definitions/Name"
            - oneOf:
                - type: object
                  required: ["doc", "value"]
                  properties:
                    doc:
                      type: string
                    value:
                      $ref: "#/definitions/TypeSpecification"
                - $ref: "#/definitions/TypeSpecification"
        description: "Public type specifications only."
      values:
        type: array
        items:
          type: array
          minItems: 2
          maxItems: 2
          items:
            - $ref: "#/definitions/Name"
            - oneOf:
                - type: object
                  required: ["doc", "value"]
                  properties:
                    doc:
                      type: string
                    value:
                      $ref: "#/definitions/ValueSpecification"
                - $ref: "#/definitions/ValueSpecification"
        description: "Public value specifications only."
      doc:
        type: string
        description: "Optional documentation for the module."
    description: "Public interface of a module."
  
  # ===== Type System =====
  
  Type:
    description: |
      A Type is a recursive tree structure representing type expressions.
      Each type can be one of: Variable, Reference, Tuple, Record, ExtensibleRecord, Function, or Unit.
    oneOf:
      - $ref: "#/definitions/VariableType"
      - $ref: "#/definitions/ReferenceType"
      - $ref: "#/definitions/TupleType"
      - $ref: "#/definitions/RecordType"
      - $ref: "#/definitions/ExtensibleRecordType"
      - $ref: "#/definitions/FunctionType"
      - $ref: "#/definitions/UnitType"
  
  VariableType:
    type: array
    minItems: 3
    maxItems: 3
    items:
      - const: "Variable"
      - $ref: "#/definitions/Attributes"
      - $ref: "#/definitions/Name"
    description: "Represents a type variable (generic parameter)."
  
  ReferenceType:
    type: array
    minItems: 4
    maxItems: 4
    items:
      - const: "Reference"
      - $ref: "#/definitions/Attributes"
      - $ref: "#/definitions/FQName"
      - type: array
        items:
          $ref: "#/definitions/Type"
        description: "Type arguments for generic types."
    description: "Reference to another type or type alias."
  
  TupleType:
    type: array
    minItems: 3
    maxItems: 3
    items:
      - const: "Tuple"
      - $ref: "#/definitions/Attributes"
      - type: array
        items:
          $ref: "#/definitions/Type"
        description: "Element types in order."
    description: "A composition of multiple types in a fixed order (product type)."
  
  RecordType:
    type: array
    minItems: 3
    maxItems: 3
    items:
      - const: "Record"
      - $ref: "#/definitions/Attributes"
      - type: array
        items:
          $ref: "#/definitions/Field"
        description: "List of field definitions."
    description: "A composition of named fields with their types."
  
  ExtensibleRecordType:
    type: array
    minItems: 4
    maxItems: 4
    items:
      - const: "ExtensibleRecord"
      - $ref: "#/definitions/Attributes"
      - $ref: "#/definitions/Name"
      - type: array
        items:
          $ref: "#/definitions/Field"
        description: "Known fields."
    description: "A record type that can be extended with additional fields."
  
  FunctionType:
    type: array
    minItems: 4
    maxItems: 4
    items:
      - const: "Function"
      - $ref: "#/definitions/Attributes"
      - $ref: "#/definitions/Type"
      - $ref: "#/definitions/Type"
    description: |
      Represents a function type. Multi-argument functions are represented via currying.
      Items: [tag, attributes, argumentType, returnType]
  
  UnitType:
    type: array
    minItems: 2
    maxItems: 2
    items:
      - const: "Unit"
      - $ref: "#/definitions/Attributes"
    description: "The type with exactly one value (similar to void in some languages)."
  
  Field:
    type: object
    required: ["name", "tpe"]
    properties:
      name:
        $ref: "#/definitions/Name"
        description: "Field name."
      tpe:
        $ref: "#/definitions/Type"
        description: "Field type."
    description: "A field in a record type."
  
  # ===== Type Specifications =====
  
  TypeSpecification:
    description: "Defines the interface of a type without implementation details."
    oneOf:
      - $ref: "#/definitions/TypeAliasSpecification"
      - $ref: "#/definitions/OpaqueTypeSpecification"
      - $ref: "#/definitions/CustomTypeSpecification"
      - $ref: "#/definitions/DerivedTypeSpecification"
  
  TypeAliasSpecification:
    type: array
    minItems: 3
    maxItems: 3
    items:
      - const: "TypeAliasSpecification"
      - type: array
        items:
          $ref: "#/definitions/Name"
        description: "Type parameters."
      - $ref: "#/definitions/Type"
    description: "An alias for another type."
  
  OpaqueTypeSpecification:
    type: array
    minItems: 2
    maxItems: 2
    items:
      - const: "OpaqueTypeSpecification"
      - type: array
        items:
          $ref: "#/definitions/Name"
        description: "Type parameters."
    description: |
      A type with unknown structure. The implementation is hidden from consumers.
  
  CustomTypeSpecification:
    type: array
    minItems: 3
    maxItems: 3
    items:
      - const: "CustomTypeSpecification"
      - type: array
        items:
          $ref: "#/definitions/Name"
        description: "Type parameters."
      - $ref: "#/definitions/Constructors"
    description: "A tagged union type (sum type)."
  
  DerivedTypeSpecification:
    type: array
    minItems: 3
    maxItems: 3
    items:
      - const: "DerivedTypeSpecification"
      - type: array
        items:
          $ref: "#/definitions/Name"
        description: "Type parameters."
      - type: object
        required: ["baseType", "fromBaseType", "toBaseType"]
        properties:
          baseType:
            $ref: "#/definitions/Type"
            description: "The type used for serialization."
          fromBaseType:
            $ref: "#/definitions/FQName"
            description: "Function to convert from base type."
          toBaseType:
            $ref: "#/definitions/FQName"
            description: "Function to convert to base type."
        description: "Details for derived type."
    description: |
      A type with platform-specific representation but known serialization.
  
  # ===== Type Definitions =====
  
  TypeDefinition:
    description: "Provides the complete implementation of a type."
    oneOf:
      - $ref: "#/definitions/TypeAliasDefinition"
      - $ref: "#/definitions/CustomTypeDefinition"
  
  TypeAliasDefinition:
    type: array
    minItems: 3
    maxItems: 3
    items:
      - const: "TypeAliasDefinition"
      - type: array
        items:
          $ref: "#/definitions/Name"
        description: "Type parameters."
      - $ref: "#/definitions/Type"
    description: "Complete definition of a type alias."
  
  CustomTypeDefinition:
    type: array
    minItems: 3
    maxItems: 3
    items:
      - const: "CustomTypeDefinition"
      - type: array
        items:
          $ref: "#/definitions/Name"
        description: "Type parameters."
      - allOf:
          - $ref: "#/definitions/AccessControlled"
          - properties:
              value:
                $ref: "#/definitions/Constructors"
    description: |
      Complete definition of a custom type. If constructors are Private, 
      the specification becomes OpaqueTypeSpecification.
  
  Constructors:
    type: array
    items:
      type: array
      minItems: 2
      maxItems: 2
      items:
        - $ref: "#/definitions/Name"
        - type: array
          items:
            type: array
            minItems: 2
            maxItems: 2
            items:
              - $ref: "#/definitions/Name"
              - $ref: "#/definitions/Type"
          description: "Constructor arguments as (name, type) pairs."
    description: "Dictionary of constructor names to their typed arguments."
  
  # ===== Value System =====
  
  Value:
    description: |
      A Value is a recursive tree structure representing computations.
      All data and logic in Morphir are represented as value expressions.
    oneOf:
      - $ref: "#/definitions/LiteralValue"
      - $ref: "#/definitions/ConstructorValue"
      - $ref: "#/definitions/TupleValue"
      - $ref: "#/definitions/ListValue"
      - $ref: "#/definitions/RecordValue"
      - $ref: "#/definitions/VariableValue"
      - $ref: "#/definitions/ReferenceValue"
      - $ref: "#/definitions/FieldValue"
      - $ref: "#/definitions/FieldFunctionValue"
      - $ref: "#/definitions/ApplyValue"
      - $ref: "#/definitions/LambdaValue"
      - $ref: "#/definitions/LetDefinitionValue"
      - $ref: "#/definitions/LetRecursionValue"
      - $ref: "#/definitions/DestructureValue"
      - $ref: "#/definitions/IfThenElseValue"
      - $ref: "#/definitions/PatternMatchValue"
      - $ref: "#/definitions/UpdateRecordValue"
      - $ref: "#/definitions/UnitValue"
  
  LiteralValue:
    type: array
    minItems: 3
    maxItems: 3
    items:
      - const: "Literal"
      - $ref: "#/definitions/Attributes"
      - $ref: "#/definitions/Literal"
    description: "A literal constant value."
  
  ConstructorValue:
    type: array
    minItems: 3
    maxItems: 3
    items:
      - const: "Constructor"
      - $ref: "#/definitions/Attributes"
      - $ref: "#/definitions/FQName"
    description: "Reference to a custom type constructor."
  
  TupleValue:
    type: array
    minItems: 3
    maxItems: 3
    items:
      - const: "Tuple"
      - $ref: "#/definitions/Attributes"
      - type: array
        items:
          $ref: "#/definitions/Value"
        description: "Element values in order."
    description: "A tuple value with multiple elements."
  
  ListValue:
    type: array
    minItems: 3
    maxItems: 3
    items:
      - const: "List"
      - $ref: "#/definitions/Attributes"
      - type: array
        items:
          $ref: "#/definitions/Value"
        description: "List elements."
    description: "A list of values."
  
  RecordValue:
    type: array
    minItems: 3
    maxItems: 3
    items:
      - const: "Record"
      - $ref: "#/definitions/Attributes"
      - type: array
        items:
          type: array
          minItems: 2
          maxItems: 2
          items:
            - $ref: "#/definitions/Name"
            - $ref: "#/definitions/Value"
        description: "Dictionary mapping field names to values."
    description: "A record value with named fields."
  
  VariableValue:
    type: array
    minItems: 3
    maxItems: 3
    items:
      - const: "Variable"
      - $ref: "#/definitions/Attributes"
      - $ref: "#/definitions/Name"
    description: "Reference to a variable in scope."
  
  ReferenceValue:
    type: array
    minItems: 3
    maxItems: 3
    items:
      - const: "Reference"
      - $ref: "#/definitions/Attributes"
      - $ref: "#/definitions/FQName"
    description: "Reference to a defined value (function or constant)."
  
  FieldValue:
    type: array
    minItems: 4
    maxItems: 4
    items:
      - const: "Field"
      - $ref: "#/definitions/Attributes"
      - $ref: "#/definitions/Value"
      - $ref: "#/definitions/Name"
    description: "Field access on a record. Items: [tag, attributes, recordExpr, fieldName]"
  
  FieldFunctionValue:
    type: array
    minItems: 3
    maxItems: 3
    items:
      - const: "FieldFunction"
      - $ref: "#/definitions/Attributes"
      - $ref: "#/definitions/Name"
    description: "A function that extracts a field (e.g., .firstName)."
  
  ApplyValue:
    type: array
    minItems: 4
    maxItems: 4
    items:
      - const: "Apply"
      - $ref: "#/definitions/Attributes"
      - $ref: "#/definitions/Value"
      - $ref: "#/definitions/Value"
    description: |
      Function application. Items: [tag, attributes, function, argument].
      Multi-argument calls are represented via currying (nested Apply nodes).
  
  LambdaValue:
    type: array
    minItems: 4
    maxItems: 4
    items:
      - const: "Lambda"
      - $ref: "#/definitions/Attributes"
      - $ref: "#/definitions/Pattern"
      - $ref: "#/definitions/Value"
    description: |
      Anonymous function (lambda abstraction).
      Items: [tag, attributes, argumentPattern, body]
  
  LetDefinitionValue:
    type: array
    minItems: 5
    maxItems: 5
    items:
      - const: "LetDefinition"
      - $ref: "#/definitions/Attributes"
      - $ref: "#/definitions/Name"
      - $ref: "#/definitions/ValueDefinition"
      - $ref: "#/definitions/Value"
    description: |
      A let binding introducing a single value.
      Items: [tag, attributes, bindingName, definition, inExpr]
  
  LetRecursionValue:
    type: array
    minItems: 4
    maxItems: 4
    items:
      - const: "LetRecursion"
      - $ref: "#/definitions/Attributes"
      - type: array
        items:
          type: array
          minItems: 2
          maxItems: 2
          items:
            - $ref: "#/definitions/Name"
            - $ref: "#/definitions/ValueDefinition"
        description: "Multiple bindings that can reference each other."
      - $ref: "#/definitions/Value"
    description: "Mutually recursive let bindings."
  
  DestructureValue:
    type: array
    minItems: 5
    maxItems: 5
    items:
      - const: "Destructure"
      - $ref: "#/definitions/Attributes"
      - $ref: "#/definitions/Pattern"
      - $ref: "#/definitions/Value"
      - $ref: "#/definitions/Value"
    description: |
      Pattern-based destructuring.
      Items: [tag, attributes, pattern, valueToDestructure, inExpr]
  
  IfThenElseValue:
    type: array
    minItems: 5
    maxItems: 5
    items:
      - const: "IfThenElse"
      - $ref: "#/definitions/Attributes"
      - $ref: "#/definitions/Value"
      - $ref: "#/definitions/Value"
      - $ref: "#/definitions/Value"
    description: |
      Conditional expression.
      Items: [tag, attributes, condition, thenBranch, elseBranch]
  
  PatternMatchValue:
    type: array
    minItems: 4
    maxItems: 4
    items:
      - const: "PatternMatch"
      - $ref: "#/definitions/Attributes"
      - $ref: "#/definitions/Value"
      - type: array
        items:
          type: array
          minItems: 2
          maxItems: 2
          items:
            - $ref: "#/definitions/Pattern"
            - $ref: "#/definitions/Value"
        description: "List of pattern-branch pairs."
    description: "Pattern matching with multiple cases."
  
  UpdateRecordValue:
    type: array
    minItems: 4
    maxItems: 4
    items:
      - const: "UpdateRecord"
      - $ref: "#/definitions/Attributes"
      - $ref: "#/definitions/Value"
      - type: array
        items:
          type: array
          minItems: 2
          maxItems: 2
          items:
            - $ref: "#/definitions/Name"
            - $ref: "#/definitions/Value"
        description: "Fields to update with new values."
    description: |
      Record update expression (immutable copy-on-update).
      Items: [tag, attributes, recordToUpdate, fieldsToUpdate]
  
  UnitValue:
    type: array
    minItems: 2
    maxItems: 2
    items:
      - const: "Unit"
      - $ref: "#/definitions/Attributes"
    description: "The unit value (the single value of the Unit type)."
  
  # ===== Literals =====
  
  Literal:
    description: "Represents literal constant values."
    oneOf:
      - $ref: "#/definitions/BoolLiteral"
      - $ref: "#/definitions/CharLiteral"
      - $ref: "#/definitions/StringLiteral"
      - $ref: "#/definitions/WholeNumberLiteral"
      - $ref: "#/definitions/FloatLiteral"
      - $ref: "#/definitions/DecimalLiteral"
  
  BoolLiteral:
    type: array
    minItems: 2
    maxItems: 2
    items:
      - const: "BoolLiteral"
      - type: boolean
    description: "Boolean literal (true or false)."
  
  CharLiteral:
    type: array
    minItems: 2
    maxItems: 2
    items:
      - const: "CharLiteral"
      - type: string
        minLength: 1
        maxLength: 1
    description: "Single character literal."
  
  StringLiteral:
    type: array
    minItems: 2
    maxItems: 2
    items:
      - const: "StringLiteral"
      - type: string
    description: "Text string literal."
  
  WholeNumberLiteral:
    type: array
    minItems: 2
    maxItems: 2
    items:
      - const: "WholeNumberLiteral"
      - type: integer
    description: "Integer literal."
  
  FloatLiteral:
    type: array
    minItems: 2
    maxItems: 2
    items:
      - const: "FloatLiteral"
      - type: number
    description: "Floating-point number literal."
  
  DecimalLiteral:
    type: array
    minItems: 2
    maxItems: 2
    items:
      - const: "DecimalLiteral"
      - type: string
        pattern: "^-?[0-9]+(\\.[0-9]+)?$"
    description: "Arbitrary-precision decimal literal (stored as string)."
  
  # ===== Patterns =====
  
  Pattern:
    description: |
      Patterns are used for destructuring and filtering values.
      They appear in lambda, let destructure, and pattern match expressions.
    oneOf:
      - $ref: "#/definitions/WildcardPattern"
      - $ref: "#/definitions/AsPattern"
      - $ref: "#/definitions/TuplePattern"
      - $ref: "#/definitions/ConstructorPattern"
      - $ref: "#/definitions/EmptyListPattern"
      - $ref: "#/definitions/HeadTailPattern"
      - $ref: "#/definitions/LiteralPattern"
      - $ref: "#/definitions/UnitPattern"
  
  WildcardPattern:
    type: array
    minItems: 2
    maxItems: 2
    items:
      - const: "WildcardPattern"
      - $ref: "#/definitions/Attributes"
    description: "Matches any value without binding (the _ pattern)."
  
  AsPattern:
    type: array
    minItems: 4
    maxItems: 4
    items:
      - const: "AsPattern"
      - $ref: "#/definitions/Attributes"
      - $ref: "#/definitions/Pattern"
      - $ref: "#/definitions/Name"
    description: |
      Binds a name to a value matched by a nested pattern.
      Simple variable binding is AsPattern with WildcardPattern nested.
      Items: [tag, attributes, nestedPattern, variableName]
  
  TuplePattern:
    type: array
    minItems: 3
    maxItems: 3
    items:
      - const: "TuplePattern"
      - $ref: "#/definitions/Attributes"
      - type: array
        items:
          $ref: "#/definitions/Pattern"
        description: "Patterns for each tuple element."
    description: "Matches a tuple by matching each element."
  
  ConstructorPattern:
    type: array
    minItems: 4
    maxItems: 4
    items:
      - const: "ConstructorPattern"
      - $ref: "#/definitions/Attributes"
      - $ref: "#/definitions/FQName"
      - type: array
        items:
          $ref: "#/definitions/Pattern"
        description: "Patterns for constructor arguments."
    description: "Matches a specific type constructor and its arguments."
  
  EmptyListPattern:
    type: array
    minItems: 2
    maxItems: 2
    items:
      - const: "EmptyListPattern"
      - $ref: "#/definitions/Attributes"
    description: "Matches an empty list (the [] pattern)."
  
  HeadTailPattern:
    type: array
    minItems: 4
    maxItems: 4
    items:
      - const: "HeadTailPattern"
      - $ref: "#/definitions/Attributes"
      - $ref: "#/definitions/Pattern"
      - $ref: "#/definitions/Pattern"
    description: |
      Matches a non-empty list by head and tail (the x :: xs pattern).
      Items: [tag, attributes, headPattern, tailPattern]
  
  LiteralPattern:
    type: array
    minItems: 3
    maxItems: 3
    items:
      - const: "LiteralPattern"
      - $ref: "#/definitions/Attributes"
      - $ref: "#/definitions/Literal"
    description: "Matches an exact literal value."
  
  UnitPattern:
    type: array
    minItems: 2
    maxItems: 2
    items:
      - const: "UnitPattern"
      - $ref: "#/definitions/Attributes"
    description: "Matches the unit value."
  
  # ===== Value Specifications and Definitions =====
  
  ValueSpecification:
    type: object
    required: ["inputs", "output"]
    properties:
      inputs:
        type: array
        items:
          type: array
          minItems: 2
          maxItems: 2
          items:
            - $ref: "#/definitions/Name"
            - $ref: "#/definitions/Type"
        description: "Function parameters as (name, type) pairs."
      output:
        $ref: "#/definitions/Type"
        description: "The return type."
    description: |
      The type signature of a value or function.
      Contains only type information, no implementation.
  
  ValueDefinition:
    type: object
    required: ["inputTypes", "outputType", "body"]
    properties:
      inputTypes:
        type: array
        items:
          type: array
          minItems: 3
          maxItems: 3
          items:
            - $ref: "#/definitions/Name"
            - $ref: "#/definitions/Attributes"
            - $ref: "#/definitions/Type"
        description: "Function parameters as (name, attributes, type) tuples."
      outputType:
        $ref: "#/definitions/Type"
        description: "The return type."
      body:
        $ref: "#/definitions/Value"
        description: "The value expression implementing the logic."
    description: |
      The complete implementation of a value or function.
      Contains both type information and implementation.