1 Kumori DSL Concepts Overview

Kumori DSL is a declarative language for defining cloud-native applications. Instead of telling the system how to deploy your app step-by-step, you describe what your application should be. This “specification as code” approach separates your application’s definition from deployment specifics, making it consistent, repeatable, and version-controllable. The Kumori platform then takes your application specification and handles the deployment complexities.

At its core, kdsl provides a small set of concepts that work together to describe what your application is, how its parts interact, and how it should be deployed. These concepts are:

  • Modules: The top-level unit of code organization, grouping related packages and managing dependencies.
  • Packages: Collections of related source files, each containing artifacts and type definitions.
  • Artifacts: The main building blocks—components, services, deployments, and builtins—that define your application’s structure and behavior. For a quick introduction to artifacts, see Artifacts.
  • Type System: Ensures correctness and consistency by validating all definitions before deployment.
  • Standard Library: A set of built-in types and functions for common cloud-native needs.

Each of these concepts is explained in detail in the following sections. Understanding them will help you confidently design, validate, and deploy Kumori applications.

1.1 Key DSL Concepts & Philosophy

Several core principles guide kdsl’s design and usage:

  • Declarative Nature: You state what you want your application to be, letting the Kumori platform handle how to achieve it.
  • Separation of Concerns: Clear distinctions between interfaces and implementations, and application logic from infrastructure.
  • Composability & Reusability: Components and services are designed to be highly combinable, fostering efficient development.
  • Validation First: Emphasis on static analysis and validation upfront to prevent errors and ensure successful deployments.

These principles help kdsl simplify complex application definition and management.

1.2 Modules

A module is the highest-level organizational unit in Kumori DSL. Every project starts with a kumori.mod.json file at its root, which specifies the module’s name, version, and any dependencies on other modules. This file enables reproducible builds and clear dependency management.

Modules contain one or more packages—subdirectories that group related artifacts and types. By structuring your code into modules, you make it easier to share, reuse, and maintain large Kumori projects.

// kumori.mod.json
{
    "spec": "kumori/module/v1",
    "kumori": "0.0.1",
    "module": "kumori.systems/example",
    "requires": [
        { 
            "target": "example.com/remote/example",
            "version": "v1.2.3"
        }
    ]
}

For a deep dive, see Dependency Management.

1.3 Packages and Imports

Kumori DSL applications are organized into packages. A package is a collection of source files in the same directory that are compiled together. Artifacts (components, services, etc.) and other definitions in one source file are visible to all other source files within the same package.

A repository contains one module. A module is a collection of related kdsl packages that are released together. A kdsl repository typically contains only one module, located at the root of the repository. A file named kumori.mod.json there declares the module path: the import path prefix for all packages within the module. The module contains the packages in the directory containing its kumori.mod.json file as well as subdirectories of that directory, up to the next subdirectory containing another kumori.mod.json file (if any).

Note that you don’t need to publish your code to a remote repository before you can build it. A module can be defined locally without belonging to a repository. However, it’s a good habit to organize your code as if you will publish it someday.

Each module’s path not only serves as an import path prefix for its packages, but also indicates where the kdsl command should look to download it. For example, in order to download the module github.com/MyOrg/Example, the kdsl command would consult the repository indicated by https://github.com/MyOrg/Example.

An import path is a string used to import a package. A package’s import path is its module path joined with its subdirectory within the module. For example, the module github.com/MyOrg/Example contains a package in the directory service/. That package’s import path is github.com/MyOrg/Example/service. Packages in the standard library do not have a module path prefix.

Imports allow you to reuse types and artifacts from other packages or modules. Use the import statement at the top of your .kumori files to bring in external definitions. Imports can reference the standard library, other packages in your module, or external modules.

package xyz

import (
    "strconv"
    "example.com/remote/example/package"
) 

// ...

For a deep dive, see Dependency Management.

1.4 Type System

kdsl features a strong static type system. This system validates the structure, data types, and relationships within your application definition before deployment. Its benefits include:

  • Early Error Detection: Catches mistakes (typos, incorrect types) during kdsl build or kdsl check, preventing possible deployment failures.
  • Consistency: Ensures adherence to defined contracts and schemas.
  • Clear Contracts: Reinforces clear interactions between application parts.

This system guarantees the integrity of your application specification. A detailed explanation of kdsl’s type system is available in a separate guide.

For a deep dive, see Type System.