Language overview

Screenplay is a business-oriented language for specifying the desired functionality of an information system. It describes concepts, commands, facts, views, queries, automations, policies, and specifications without making a particular runtime authoritative. Screenplay now owns the versioned semantic foundation; Stage, Studio, and generated applications are being migrated to consume it capability by capability.

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, bounded escape hatches — behavior remains meaningful without implementation code. Selected implementation points can carry inline code or file references as realization attachments.
• Slices are the atom — everything lives inside a typed slice aligned with Event Modeling’s vocabulary.
• First-class sub-languages — the Projection Declaration Language (PDL) and Change Data Capture Language (CDL) are built-in, independently consumable grammars. Inline language tags are extensible, while host construct keywords remain closed.
• 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 and composite types>
<policies, personas, and authentication>
<triggers>
<layouts, themes, and UI profiles>
<module>+
  <screen and dialog templates>
  <forms and contributions>
  <feature>+
    <feature>*          ← sub-features, arbitrarily deep
    <contributions>
    <slice>+
      <construct>+      ← commands, events, read models, queries, projections, specifications, reactions, captures, 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
Reaction rules	Reactions
What sets a reaction off	Triggers
UI declarations at three abstraction levels	Screens
Built-in sub-languages and extensible inline language tags	Sub-languages and inline code
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.