Language overview

Screenplay is the modeling language for the Cratis platform. It lets developers describe a complete bounded context — events, commands, queries, projections, screens, automations, authorization, validation, constraints, and concepts — in a single declarative file. Stage interprets a Screenplay and runs it as a live application; Studio uses the same contract to visualize and generate.

File extension

Screenplay files use the .play extension.

Design principles

• Indentation-based — Python-style, no braces. Structure follows the offside rule: a construct owns everything indented beneath it.
• Declarative first, imperative escape hatch — every construct has a declarative form; any construct can drop into C#, TypeScript, React, or HTML via inline code blocks or file references.
• Slices are the atom — everything lives inside a typed slice aligned with Event Modeling’s vocabulary.
• Sub-language pluggability — the Projection Declaration Language (PDL) and Change Data Capture Language (CDL) are embedded sub-grammars. Additional sub-languages can be registered and parsed inside named constructs.
• Concepts carry compliance — value types declare PII and sensitivity attributes once, with the reason they are personal data; all usages inherit them.
• file is never required — a document must be expressible, and meaningful, before any code exists. Code pointers are realization metadata a slice gains once it is built.

Top-level structure

<domain>
<imports>
<concepts>
<types>
<policies>
<personas>
<module>
  <layouts>
  <feature>+
    <feature>*          ← sub-features, arbitrarily deep
    <slice>+
      <construct>+      ← events, commands, queries, projections, captures, reactors, screens, constraints
<seeds>

Imports

Cross-module references. Imported types are available by their short name within the module.

import Customers.CustomerRegistered
import Customers.CustomerDetailsReadModel

Comments

Line comments start with // and run to the end of the line.

Language reference

Topic	Page
The domain a file belongs to	Domain
Formalized value types with compliance attributes	Concepts
Composite value types - the shapes events carry	Types
Named authorization rules	Policies
Roles interacting with the application	Personas
Modules, features, and the four slice types	Modules, Features and Slices
Single-line and fenced multi-line descriptions	Descriptions
Event type declarations	Events
Commands, validation, the produces block, and handlers	Commands
Read-side entry points, parameters and performers	Queries
What a handler, a performer, a rule and a policy are given	Contexts
PDL-embedded projections	Projections
CDL-embedded change data capture	Captures
Events seeded per event source id	Event seeding
Server-side rules enforced before commit	Constraints
Event reaction rules	Reactors
UI declarations at three abstraction levels	Screens
Registering additional embedded sub-languages	Sub-language Pluggability
The full EBNF grammar	Grammar

Tooling

The @cratis/screenplay-language NPM package provides a Monaco language service for .play files — syntax highlighting (including embedded C#/TypeScript/React/HTML blocks and the PDL/CDL sub-languages), IntelliSense completions, hover documentation, and diagnostics. The screenplay-editor app hosts the editor standalone.

The Screenplay VS Code extension brings the same language support to VS Code — a TextMate grammar with embedded-language and PDL/CDL highlighting, plus IntelliSense, hover, and diagnostics driven by the same shared language logic. .play files carry the Cratis icon.