About this specification

This section is the precise, construct-by-construct specification of the Koine language. If the Start here and Tutorials sections teach you how to think in Koine, the reference tells you exactly what each keyword does and what C# it emits.

Every page is grounded in the compiler’s tests and the Shop demo, so the snippets compile and the emitted shapes are real.

1.1 How to read this specification

Each construct chapter follows a fixed General → Syntax → Semantics → Translation structure, uses EBNF for grammar, and cites sections with the § glyph. The full set of conventions — grammar notation, numbering, callouts, and diagnostics — is described in Notation & conventions (§2). The token-level rules (comments, identifiers, keywords, literals, operators) live in Lexical structure (§3).

1.2 How the language is shaped

A .koi file declares one or more bounded contexts. Inside a context you declare types (value objects, entities, aggregates, enums, quantities), the behaviour on those types (invariants, derived fields, commands, events, state machines, factories), the strategic pieces (specs, services, policies), and the application layer (repositories, use cases, read models, queries). At the top level — sibling to the contexts — a single contextmap wires the contexts together.

context Catalog {

  enum Currency { EUR, USD, GBP }

  value Money {
    amount:   Decimal
    currency: Currency
    invariant amount >= 0   "a monetary amount cannot be negative"
  }
}

Target-agnostic by design

The pipeline is strictly layered: lexer/parser → target-agnostic semantic model → validator → emitter. Nothing before the emitter knows what C# is. Koine ships C#, TypeScript, Python, PHP, Rust, and Java emitters today. This reference describes the language through its C# emission — but the model itself is portable across every target.

1.3 The construct map

Each construct family has its own reference page. Start here and follow the link for the one you need.

Construct	What you write	Page
context, module, type basics	bounded contexts, sub-namespaces, the type families	Contexts & types
value, quantity, Range<T>	immutable value objects, unit-checked quantities, intervals	Value objects
entity … identified by …	entities and the four identity strategies	Entities & identity
aggregate … root …	aggregate roots, IAggregateRoot, versioning	Aggregates
enum	smart enums, with optional associated data	Enums
comparisons, arithmetic, matches, lambdas	the pure expression sublanguage	Expressions
invariant, spec as guard	constructor guards, regex and conditional rules	Invariants
command, event, states	behaviour, domain events, state machines	Commands, events & state machines
create … { … -> … emit … }	factory methods and -> field initialization	Factories
spec, service, policy	named predicates, domain services, reaction seams	Specs, services & policies
repository, find, versioned	repository contracts, finders, optimistic concurrency	Repositories & concurrency
service … usecase …, readmodel, query	application services, CQRS read models and queries	Application layer & CQRS
import, module, directory builds	multi-file models, imports, sub-namespaces	Multi-file, imports & modules
contextmap, integration event, publishes/subscribes, acl	context maps, the seven roles, shared kernels, integration events	Context maps & integration
version, @since, @deprecated, koine check	model versioning, deprecation, compatibility checks	Versioning & evolution

For a feature-by-feature tour, see the feature catalogue. For the koine build/koine check flags, see the CLI reference.

1.4 Primitive types

Koine has a small set of built-in primitives that map straight to C#:

Koine	C#	Notes
String	string	not orderable
Int	int	orderable
Decimal	decimal	money / quantities; orderable
Bool	bool
Instant	DateTimeOffset	orderable
List<T>	IReadOnlyList<T>	defensively copied in constructors
<Name>Id	generated ID value object	a record wrapping a Guid by default

List<T>, Set<T>, Map<K,V>, and Range<T> are the four built-in generic type constructors. Orderable types (Int, Decimal, Instant) are the ones allowed in relational comparisons and as Range<T> element types — String is not orderable. See Value objects (§5) and Expressions (§9) for the details.

1.5 Tokens, keywords, and operators

The lexical layer — comments, identifiers, the reserved (invariant, matches) vs soft keyword rule, reserved type names, literals, and the atomic -> / <-> operators — is specified in Lexical structure (§3).

1.6 Where to next

• New to the language? Read in sidebar order, starting with Contexts & types.
• Looking up one construct? Jump straight from the construct map above.
• Want to see it all wired together? Browse the Shop demo or the feature catalogue.