Learn

Architecture & pattern guides

Read the idea, build it on a Grid, prove it in a challenge. Short, practical guides — illustrated with RodGrid's own nodes — on system design, design patterns, flow modeling, and how to get the most out of the app.

All articles

Published Language

A documented, shared format for the data that crosses a boundary, so consumers depend on it instead of on another context's internal model: who owns it, how it changes without breaking them, and what it costs.

A second request for the planning tables

The ticket asks for read access to the planning database. It comes from the open-data team of a regional transit authority, which wants to publish timetables for the journey-planner apps people use on their phones, and it is the second request of its kind: passenger information already reads those tables to drive the departure displays at stops and stations. A third consumer, a fare-calculation team, has asked whether it could do the same.

The tables belong to network planning, and their model is built for planning: a block is the chain of trips one vehicle drives in a day, a duty is one driver's shift, and every trip is a row tied to both. Every reader of those tables is bound to that model, and the displays team has already paid for it once, when planning renamed a column linking trips to blocks and their query stopped returning departures. Granting the ticket would bind a second team, and soon a third, to tables shaped for a job none of them does.

A language made for the exchange

One answer is to grant access and promise to freeze the tables, which protects the consumers by stopping planning from improving its own model. The opposite answer, having planning send data in the displays team's model, ties planning to one consumer and does nothing for the apps. A Published Language is the third option: a well-documented, shared interchange format, which the contexts translate into or out of as they need. It can be an industry standard or a format the upstream documents for its consumers; the authority chose one that is neither side's internal model, a timetable format in the terms passengers use: stops, routes, trips, the days each trip runs and the time it calls at each stop. Blocks and duties are not in it, because no consumer needs them.

Planning translates its model into that format, and each consumer translates the format into its own. No context has to understand another's internal model. Planning can split blocks, merge duties or rebuild its tables, and as long as its translation still produces the same timetable, the displays and the apps do not notice.

One timetable format, three contexts

Planning translates into the published format; each consumer translates out of it. Blocks and duties never cross the boundary.

That is why, here, a third language beats exposing either model. An internal model is shaped by the decisions of the team that owns it, and changes whenever they do. A published language is shaped by what has to cross the boundary, and does not have to change when either internal model does.

Somebody owns the words

A format that every team may edit soon means slightly different things to each of them. A Published Language needs an owner who documents what each element means, decides what changes, and announces it. Inside one organisation that is usually the upstream team that offers the data, here network planning, which publishes the specification next to the data it describes. Between organisations it is often a standards body or an industry group, and every side translates to a format none of them controls. Transit has one: GTFS, the General Transit Feed Specification, is a timetable format that many transit agencies publish and journey-planning apps read. Had the authority adopted it for the apps, its open-data export would simply be a translation into GTFS.

Changing a language other people speak

Owning the language also means changing it carefully. When planning wanted to tell passengers which trips run step-free vehicles, it added an optional field to the trip. The specification tells readers to ignore fields they do not know, so consumers that knew nothing about it kept working, and the displays began showing an accessibility symbol once their own release was ready. Removing or renaming a field is different, because some consumer still reads it. Additive changes, explicit versions and deprecation windows are the subject of API versioning & backwards compatibility, and the same discipline applies when the language travels as events rather than through an API.

Watch outA schema that changes with neither a version nor an announcement tends to fork: each context keeps the copy it read on day one, and the shared language drifts into dialects that no one can reconcile without asking every team which copy it uses.

What the third language costs

For two contexts built by one team that always change together, a published language is usually more ceremony than the boundary is worth. Where there are several consumers, as here, the price is translation: every exchange passes through two, the upstream into the format and each consumer out of it, and each is code to keep correct. A new need also goes through the owner: a consumer that needs an element the format lacks may wait until the owner adds it.

A consumer can make its side cheaper by conforming to the published language rather than translating it, which is the Conformist decision applied to a stable, documented format instead of someone's internals. A consumer whose model the format would distort goes the other way and translates it behind an Anti-Corruption Layer.

The language and the door

The language is what crosses the boundary; the door it crosses through is often an Open Host Service, the documented service a context offers to all its consumers, which Context map: how bounded contexts relate explains along with the other relationships between contexts.

One context, many readers, on a Grid

In the Context Mapping Challenge, one context has to be exposed through an Open Host Service with a Published Language. Give that role to the context with the most readers, as planning is here, connect its Open Host Service to the language it speaks, and send each reader through the language instead of straight into the upstream. The open-data ticket then gets its answer on the Grid: each reader's seam says whether it translates the language into its own model or conforms to it.

Practice this