Morphir Framework

Morphir provides formal specifications for its configuration formats, Intermediate Representation (IR), and tool distribution. These specifications serve as the authoritative reference for:

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

The Morphir reference documentation provides technical details for backends, APIs, and tools. It is organized into three primary areas:

• Backends: Platform-specific code generation (e.g., Scala, Spark, TypeScript, Spring Boot, Relational).
• JSON Schema: Documentation for JSON Schema generation, configuration, mappings, and codecs.
• CLI Reference: Documentation for the Morphir command-line interface, including incremental builds and documentation merging.

Use the following guide to find what you need:

• Specific Backend: Look in backends/.
• JSON/Schema Work: Look in json-schema/.
• CLI Usage: Look in cli/.

Morphir v4 is organized into three primary architectural themes that define its core functionality:

1. IR v4 (Intermediate Representation): Defines the data model, including types, values, modules, packages, distributions, naming conventions, and serialization formats.
2. Document Tree Protocol: Specifies the layout for the Document Tree IR and the JSON-RPC 2.0 API used for communication.
3. Morphir Daemon: A long-running service managing the workspace lifecycle, project management, dependency resolution, incremental builds, file watching, and package publishing via JSON-RPC.

Additionally, the Extensions (MEP architecture) allows for adding frontends, backends, validators, and transforms using Process and WASM runtimes.

The Morphir Playground is an interactive environment designed to allow users to compile source code to Morphir IR and generate artifacts without interacting with the local filesystem.

Workflow:

1. Pick a Frontend: Select a language/frontend from the catalog.
2. Write Source: Type source code in the editor.
3. Compile: The code is compiled to Morphir IR.
4. Inspect: Use Insight and XRay views to inspect the resulting IR.
5. Generate: Pick a target and generate artifacts (returned as downloads).

The Playground is driven by the same ExtensionRegistry used by the CLI, ensuring that if the CLI can compile a language, the Playground can too. It supports both built-in providers (running in-process) and installed extensions (driven via the Morphir Extension Protocol (MEP)).

The Morphir Daemon is a long-running service designed to manage the development lifecycle of Morphir projects. It provides several core capabilities:

• Workspace Management: Enables multi-project development where projects can share dependencies.
• Build Orchestration: Coordinates builds across multiple projects in the correct dependency order.
• File Watching: Automatically triggers recompilation when source files are modified.
• IDE Integration: Provides support for the Language Server Protocol (LSP).
• Package Publishing: Handles packing and publishing packages to registries.

Morphir is a multi-language system designed to capture an application's domain model and business logic in a technology-agnostic data format. By treating business knowledge as data rather than opaque code, Morphir allows you to:

• Translate it: Move between different languages and platforms as technology evolves.
• Visualize it: Convert complex logic into understandable explanations for business users.
• Share it: Distribute consistent interpretations of logic across different departments or organizations.
• Store it: Retrieve and explain historical versions of business logic.

The core philosophy is that data and rules reign supreme, while the specific programming language or platform is treated as an implementation detail.

Morphir IR Version 4 introduces several architectural changes:

• Removal of Generic Parameters: Types and Values no longer use a generic attribute parameter a. They now use specific TypeAttributes and ValueAttributes structures.
• Explicit Attributes: Attributes now explicitly include source location, constraints (for types), and inferred types (for values).
• First-class Module Configuration: Added support for module.json files containing full module definitions.
• Incomplete Definitions: Introduced IncompleteTypeDefinition and IncompleteBody to support best-effort compilation.
• Native and External Bodies: Platform builtins (NativeBody) and FFI bindings (ExternalBody) are now treated as value definition bodies rather than expressions.

Morphir IR Schema Version 3 is the current standard for the Morphir Intermediate Representation (IR). It is characterized by a consistent use of capitalized tags for all constructs (e.g., "Library", "Public", "Variable", "Apply").

Version 3 follows the formatVersion contract. The integer 3 is an alias for exactly 3.0.0. While 3.0.0 is a valid baseline string, later releases (like 3.1.0) require strict three-component release strings. Canonical writers should emit the integer 3 for version 3.0.0 and use the full string for any version with a non-zero minor or patch component.

The finos/morphir-go project is a backend for the Morphir ecosystem designed to generate Go code from Morphir IR.

Note: This backend is maintained in its own repository (finos/morphir-go) and is not part of the main finos/morphir umbrella repository.

Project Scope

• Goal: Convert Morphir IR into Go modules or workspaces that align with the Morphir IR specification.
• MVP Focus: Generation (IR $\rightarrow$ Go), module/workspace scaffolding, and basic pipeline integration (make/gen/build).
• Non-Goals (MVP): The backend does not provide a full runtime/execution framework, comprehensive packaging policies, or automatic code formatting/linting (these should be handled by downstream Go tools).