What the Rosie Project Synopsis Actually Is
The Rosie Project is a visual programming language built at University College Dublin. It's designed around pattern-matching and rule-based execution. People use it to create domain-specific languages without writing traditional parsers from scratch. When someone asks about the Rosie Project Synopsis, they're usually referring to the summary metadata that describes a Rosie DSL project — its purpose, its rules, its patterns, and how everything connects. It isn't a single command. It's the conceptual outline you create before writing the code. I ran into this exact question about two years ago when a team at a fintech company wanted to migrate their event-validation logic into a Rosie DSL. They had spreadsheets full of business rules and zero clear structure. The synopsis phase is where you stop trying to write rules and start mapping what the problem actually looks like. That part matters more than most people realize. Most guides skip straight to syntax. That's the wrong order. I'll walk through the process the way we actually did it at UCD, with the messiness included.
Before opening the IDE, write a single paragraph describing what your DSL handles and what it does not. Be aggressively specific. If you're building a DSL for payment validation, explicitly state that it does not handle currency conversion, fraud detection, or user authentication. This boundary saves you three weeks of scope creep later. I learned that the hard way on a project for a logistics client who kept asking us to model their entire warehouse workflow inside the DSL instead of just the shipment-status transitions. Rosie works on pattern matching against typed records. Your first practical output should be a plain list of every record type your DSL will consume or produce. For the fintech team I mentioned, this looked like: TransactionRecord — id, amount, currency, timestamp, source, destination
ValidationResult — transactionId, passed, reason, severity
ErrorLog — timestamp, code, message
This isn't fancy. It takes twenty minutes. It prevents you from discovering at runtime that your pattern definitions don't cover a field that actually exists in the data.
Get the Full Details
Step 3: Enumerate the Rules
Write each business rule as a plain English sentence. Don't try to translate it into Rosie syntax yet. Just get them all on paper. Here's what that list looked like for the team: Rule A: Transactions over fifty thousand euros require dual-authorization.
Rule B: Transactions in GBP must have a conversion record present.
Rule C: Source and destination accounts cannot be identical.
Rule D: Timestamps must not be more than five minutes in the future.
Rule E: If currency is USD and amount is below ten dollars, flag for review. Five rules. Simple. Readable. You will change all five before deployment. That's normal.
Step 4: Identify the Patterns First
Here's the counter-intuitive part that most beginners miss. In Rosie, the pattern comes before the rule body. People instinctively start writing the action ("if X, then do Y"). Start by writing the pattern alone. A pattern in Rosie is a template that matches incoming records. Get the pattern right and the rule body almost writes itself. Get it wrong and you'll spend hours debugging why your rule never fires. I remember a project where we had a pattern that was supposed to match a user profile record with a nullable email field. The field was optional in the schema but I hadn't accounted for that in the pattern declaration. The rule silently skipped every record where email was null. We caught it after two days of confused debugging. The fix was adding {email?} to the pattern instead of {email}. That single character cost us a weekend.
Step 5: Map Input to Output
Draw a simple flow. Record in Pattern matches Rule executes Result record produced. Keep it on one page. This is your synopsis document. It should contain: Project name: One identifier
Version: Semantic version starting at 0.1.0
Domain: The paragraph from Step 1
Record types: The list from Step 2
Rule set: The sentences from Step 3
Pattern-to-rule mapping: Which pattern triggers which rule
Output specification: What result records look like
Common Pitfalls I've Seen Repeatedly
Over-engineering the pattern syntax on day one. People try to make their patterns clever. They nest conditions, reuse variables across unrelated rules, and build abstractions that don't pay off. Simple patterns are fast to execute and easy to debug. Complicated patterns are a maintenance nightmare. Ignoring pattern ordering. Rosie evaluates rules in order. If you have a broad pattern and a narrow pattern, the broad one must come first if you want the narrow one to ever fire on unmatched cases. I once deployed a DSL where a generic catch-all rule was sitting at the top of the file. Every subsequent rule was unreachable. The system appeared to work because the catch-all produced default results. We found the issue during a load test when the default results caused data corruption downstream. Move it to the bottom. Assuming Rosie handles concurrency. It doesn't. Not really. Each pattern match is atomic within a single record stream, but if you're feeding multiple parallel streams into the same project, you need an external orchestrator. We built a message-queue wrapper around our Rosie projects for that reason. It adds latency but keeps things deterministic.
When the Synopsis Isn't Enough
There are cases where a written synopsis fails. If your DSL has more than about forty rules, the plain-text approach becomes unreadable. We hit that wall on a healthcare compliance project and switched to splitting the project into modular sub-projects, each with its own synopsis file. The main project then imports and composes them. That structure scales. You can also export the synopsis as a JSON schema and version-control it alongside your .rs files. Most teams don't bother doing that. They should. Start in a text editor. Write the synopsis. Show it to someone who knows the domain but has never seen Rosie. If they can explain the rules back to you without asking clarifying questions, your synopsis is solid. Then open the IDE and translate. Don't skip that human check. I've seen projects where the developer and the domain expert agreed on the written rules but disagreed on edge cases that only surfaced during integration. The synopsis catches most of those before code is written. The whole process — from blank page to deployable synopsis document — takes roughly two to four hours for a small DSL with under twenty rules. A larger project might take a full day. Budget accordingly. Rushing the synopsis phase is the single most common reason Rosie DSL projects fail to meet expectations in production.
