Overview¶

In this section we will explore the concepts and ideas that RIDDL uses. This is not about the RIDDL language syntax, just the concepts of the language.

Definitions¶

RIDDL consists only of definitions that define the design of the desired system.

Definitional Hierarchy¶

Definitions in RIDDL are arranged in a hierarchy. Definitions that contain other definitions are known as branches. Definitions that do not contain other definitions are known as leaves.

This is done simply by having an attribute that lists the contents of any definition:

contents: The contained definitions that define the container. Not all definitions can contain other ones so sometimes this is empty.

Simplifications¶

The valid hierarchy structure is shown below, but to make this hierarchy easier to comprehend, we've taken some short-cuts :

All the common attributes have been omitted for brevity but are implied on each line of the hierarchy.
We only descend as far as a Type definition. Whenever you see one, you should infer this hierarchy:
Types
- Fields

Hierarchy¶

With those clarifying simplifications, here is the containment graph. It is a graph, not a tree: several definitions are legal at more than one scope, and four of them nest inside themselves. These three views split it up so each stays readable; the table below is the exhaustive version.

Where definitions live. Dashed edges are conditional — a Repository or Connector sits at domain scope only when it genuinely spans several contexts, and a Group only in a context with the application intention.

flowchart TD
    Root(["Root"]) --> Module
    Root --> Domain
    Module -->|"any top-level<br/>definition"| Domain

    Domain -->|nested| Domain
    Domain --> Context
    Domain --> Epic
    Domain --> Saga
    Domain -.->|spans contexts| Repository
    Domain -.->|spans contexts| Connector

    Context --> Entity
    Context --> Adaptor
    Context --> Projector
    Context --> Repository
    Context --> Processor
    Context --> Saga
    Context --> Connector
    Context -.->|application| Group

    Entity --> State

Note that Saga and Connector each have two parents. A tree cannot say that, which is part of how the old diagram drifted.

What every processor may contain. RIDDL 2.0 unified the processors, so rather than repeat one bundle of contents six times, it is drawn once. Everything below the hub is legal inside any of the six above it.

flowchart TD
    Context --> PC
    Entity --> PC
    Adaptor --> PC
    Projector --> PC
    Repository --> PC
    Processor --> PC

    PC(["Processor contents"])
    PC --> Handler
    PC --> Function
    PC --> Connector
    PC -->|nested| Processor
    PC --> Ports["Inlet · Outlet<br/>Relationship"]
    PC --> Leaves["Type · Constant · Invariant<br/>Version · Copyright<br/>Comment · Include"]

    Repository --> Schema
    Projector --> Updates["updates"]

    classDef bundle stroke-dasharray: 4 3;
    class Ports,Leaves bundle;

Behaviour and stories. Where the pseudocode and the user-facing narrative live. Saga is the outlier that bears stream ports without being a processor.

flowchart TD
    State --> Handler
    State --> Invariant
    Handler --> OnClause["On Clause"] --> Statement
    Function -->|nested| Function
    Function --> Statement

    Saga --> Step["Saga Step"] --> Statement
    Saga --> SagaPorts["Inlet · Outlet<br/>Function · Include"]

    Epic --> Case --> Interaction
    Group -->|nested| Group
    Group --> GroupDefs["Input · Output<br/>contains · shown by"]

    classDef bundle stroke-dasharray: 4 3;
    class SagaPorts,GroupDefs bundle;

Detailed Containment Reference¶

Container	Can Contain
Root	Domain, Module, Author, Version, Copyright, Include, Import
Module	any top-level definition, flat and unordered
Domain	Type, Epic, Context, Domain (nested), Saga, User, Author, Repository†, Connector†, Version, Copyright, Include, Import
Epic	Case → Interaction, Type, `shown by`, Include
Context	Entity, Projector, Saga, Adaptor, Repository, Processor, Connector, Group‡, + processor contents
Entity	State, + processor contents
State	Handler, Invariant
Projector	`updates`, + processor contents
Saga	SagaStep → Statement, Inlet, Outlet, Function, Include
Adaptor	processor contents
Repository	Schema, + processor contents
Processor	processor contents
Function	Statement, Type, Function (nested), Include
Handler	On Clause → Statement
Group	Group (nested), `contains`, Input, Output, `shown by`
Invariant	a Value condition

† at domain scope only when the definition genuinely spans several contexts ‡ only in a context with the application intention

Processor contents — every processor may contain: Handler, Function, Type, Constant, Invariant, Inlet, Outlet, Relationship, nested Processor, Connector, Version, Copyright, Comment, Include.

New in RIDDL 2.0

Four concepts are new, and one changed shape:

Module — a flat, named collection of any top-level definition, which absorbed the deprecated nebula
Version — one component of a composed version coordinate
Copyright — a named notice, inherited nearest-first
Standard Module — the predefined stream terminators every model can use without importing anything
Processor — unified: every processor kind now bears ports and carries a shape derived from its arity

Next¶

When you're done exploring all the concepts, check out our guides next.

Full Index¶

The pages in this section cover each RIDDL concept in detail. Use the navigation menu to explore individual concepts.