Find your path through Vernac
You do not need to read everything in order. Choose the outcome you want below. Tutorials teach by doing; references help while writing; contracts settle exact semantics; development notes explain how the implementation works.
Version guide: these pages describe the 0.5.0 release line, including native debugging, MVC/starter support and live Java editor APIs. Match compiler/runtime and plugin versions. Source builds use 0.5.0-SNAPSHOT; release builds select 0.5.0. If that version is not published yet, use the matching source-build instructions. Historical release records are not the current feature reference.
Choose an entry point
| I want to… | Start here | Continue with |
|---|---|---|
| Learn DDD from the beginning | What is DDD? | DDD for small projects |
| Understand what Vernac does | Architecture, expressed | Follow one operation |
| Try the language without a database | Your first domain model | Behavior |
| Start a small working web application | Spring Boot starter | Server-rendered MVC |
| Explore a larger application | Dispatch showcase | Tutorial learning path |
| Write correct syntax | Language reference | Specification and contracts |
| Give a coding agent a compact context | AI language reference | AI build and migration tools |
| Diagnose unexpected behavior | Practical FAQ | The relevant feature contract below |
| Develop a language plugin | IntelliJ lessons learned | Contributor implementation notes |
| Build or release Vernac itself | Contributing | Release operations |
Model the domain and its meaning
Start with default names, closed values and collections. Then add behavior, usecases and domain services.
Keep the vocabulary beside the model with ubiquitous language, and inspect/export its structure with domain diagrams.
For exact rules: namespaces/imports, field types/nullness, values, entities/aggregates and shared Java implementation rules. The specification index connects the remaining contracts; it is the authoritative route rather than a second competing rule book.
Store, query and evolve data
| Task | Guided explanation | Exact contract or implementation |
|---|---|---|
| Save/load an entire aggregate | Database persistence | PostgreSQL mapping |
| Search by values, absence or text | Repository queries | Query contract |
| Return pages and cursors | Pagination | Pagination contract |
| Change a deployed schema | Flyway workflow | Schema tools |
| Understand representation limits | Persistence FAQ | Scalar limits |
Migration tools produce candidates for review, not deployment approval. The Flyway walkthrough explains the distinct states of source history, copied build resources and the application database, including how to repeat a disposable experiment.
Cross boundaries and reuse capabilities
- Domain events: synchronous participation and durable deferred delivery.
- Ports walkthrough: run an actual integration against a local fixture.
- Java-backed ports and declarative REST: choose the appropriate implementation style.
- DTOs/PATCH, mappings and errors: define the anti-corruption boundary.
- Inbound HTTP and MVC: expose usecases as JSON or server-rendered pages.
- Versioned modules: exports, dependencies, activation, provider selection and schema evolution.
Follow these to the integration contracts when you need a precise guarantee. The persistent-module example linked from the module tutorial demonstrates independent migration histories and coordinated calls.
Work naturally in IntelliJ
Install and navigate, then debug behavior in its source. The debugging chapter covers stepping, locals, expressions, conditions, logpoints, validation and adapter/mapping contexts, as well as the generated-Java contributor view.
Building a plugin yourself? The lessons-learned collection connects language injection, source roots, live APIs, references, debugger scopes and verification. It includes a SQLJ design checklist and distinguishes implemented paths from pending installed-IDE acceptance and future work.
Understand the project rather than use the language
Contributor documentation indexes compiler/tooling mechanisms, design decisions and roadmaps. Documentation maintenance explains which pages own rules and how examples/links are checked. Release operations covers publishing.
Implementation notes and proposals do not override the specification. They can contain historical experiments or deferred work; check their status before treating them as current behavior. Feature gaps belong on the linked roadmaps, not in guessed syntax.
Documentation home · All tutorial chapters · FAQ · Specification index