A GraphQL Schema in the Domain Language
A GraphQL schema is the best place there has ever been for the ubiquitous language of a domain – and if the domain is German, it may stay German there, too.
A GraphQL Schema in the Domain Language
The German word “Fachsprache” has two readings, and the more common one is explicitly not meant here. It isn’t about jargon – not the vocabulary an industry uses to keep outsiders at a distance. What I mean is what Eric Evans described in 2003 in “Domain-Driven Design” as the ubiquitous language: the one shared language that the business side and development actually speak in a project. The same words in the meeting, in the ticket, in the model, in the code. One vocabulary for everyone – not two vocabularies with a translation table in between.
The idea is fifteen years old, and in practice it rarely fails for lack of will. It fails for lack of a place. A glossary in the wiki goes stale from the day it is created, because nobody updates it when a field gets renamed. The code would be the more honest place, but the code belongs to only one side: the business department doesn’t read Java classes. What was missing all these years was an artifact that both sides can read and that is checked by machines at the same time.
Since I started working with GraphQL, I’m convinced this artifact now exists: the schema. And – this is the more uncomfortable part of the thesis – you may speak the domain language there in German, too.
Translating twice, losing twice#
In projects with a German-speaking business side, I have run into the same pattern again and again over the years. The business department says “Angebot” (offer). The database says OFFER, the class in the service is called Quote, and a Proposal shows up in the frontend – three translations of the same word, created at three points in time under three different deadlines. Ever since, every conversation between the business side and development translates twice: on the way in while listening, on the way back while answering.
Each of these translations doesn’t just cost time, it distorts. Whether “Angebot” should be called offer, quote, bid or proposal isn’t a neutral choice – each of these words carries its own meaning in English, and none matches exactly what the business side means. In the end, a developer under deadline pressure makes the decision, and it then stays in the system for years – unnoticed, but effective in every single conversation about exactly this field.
flowchart LR F["Business side<br/>says “Angebot”"] -->|translate| E["Development<br/>Offer? Quote? Bid?"] E -->|translate| S["System<br/>OFFER, Quote, Proposal"] S -->|translate back| E E -->|translate back| F
The most expensive misunderstandings I have seen in reviews were rarely technical in nature. They were terms that had changed their meaning on the way through this chain – a “storniertes Angebot” (canceled offer) that was a cancelled quote in the system, even though the business side understood something different by “Stornierung” than development did by cancelled.
The experiment: uber-ng#
In March, I created a small repository for this: uber-ng, a deliberately manageable recreation of a ride-hailing service like the one you know from Uber. Not a product – a prototype with in-memory data, a few Mocha tests and a single question: How does a GraphQL schema read when the domain terms stay German?
The schema sits there as a separate file in schema notation – the SDL that is currently being added to the GraphQL specification after years of being merely a tooling convention. The core looks like this:
enum STATUS {
angefragt
warteAufBestaetigung
angenommen
}
type Angebot implements Node {
id: ID!
fahrgast: Fahrgast
von: String!
nach: String!
fahrer: Fahrer
wartezeit: String
status: STATUS
}
type Mutation {
fahrtAnfragen(input: AnfrageInput!): Angebot
angebotAnnehmen(input: AngebotAnnehmenInput!): Angebot
angebotAblehnen(input: AngebotAblehnenInput!): Angebot
}
type Subscription {
onAngebotChanged: Angebot
}
If you read this, you don’t need a glossary next to it. A ride is requested (“fahrtAnfragen”); what results is an offer (“Angebot”); an offer can be accepted or declined – and whoever declines must give a reason, because AngebotAblehnenInput requires a grund: String!. The mutations are verbs of the domain, not CRUD prose. fahrtAnfragen even enforces a domain distinction that a createOffer would have swallowed: what gets requested is a ride – the offer is the system’s answer to it, not something the passenger creates themselves. I only noticed this difference while formulating the schema, not before.
The clients’ requests then speak this language, too:
mutation {
fahrtAnfragen(input: {
fahrgastId: "f1"
von: "Alexanderplatz"
nach: "Flughafen Tegel"
}) {
id
status
wartezeit
}
}
You can read this mutation out loud in a meeting, and the business side understands it without an interpreter. That is no small thing. It is the moment an API stops being a pure developer artifact.
Technically, the setup is deliberately ordinary: Node, a GraphQL server, subscriptions over WebSockets, as they have become established with subscriptions-transport-ws by now. onAngebotChanged pushes every state change of an offer to the connected clients – the passenger sees when angefragt (requested) turns into warteAufBestaetigung (awaiting confirmation) without having to ask. For the experiment, that is a side issue. The only interesting part is that this channel speaks the domain language, too: what arrives at the client is called Angebot, not OfferDTO.
What makes the schema a glossary#
A glossary describes a language. The schema enforces it – and that is exactly what it has over every glossary I have come across so far:
- Every query is validated against the schema. Whoever invents or misspells a term gets an error instead of a silent misunderstanding.
- Introspection makes the vocabulary queryable: GraphiQL shows types, fields and descriptions while you type – the glossary delivers itself.
@deprecatedretires terms in an orderly way, with a reason and visible to every client. In uber-ng, exactly such a note is attached tofahrgastId.- The schema lives in version control. Every change of a term is a diff, and a diff can get a review in which the business side takes part, too.
Then there are the description texts: the SDL allows a description on every type, every field and every enum value, and introspection delivers it along. So it doesn’t just say that there is an Angebot, but what the business side means by it – the definition travels with the term instead of aging in another system.
A wiki can do none of this. Neither can a UML model. To my knowledge, the GraphQL schema is the first artifact that is at the same time readable by humans, checkable by machines and binding for operations. The schema is the glossary – not a copy of it.
States have names#
The most inconspicuous part of the schema carries the most weight: the enum. STATUS with its three values is a complete, checkable description of an offer’s lifecycle – and the values are named the way the business side would say them on the phone.
In older systems, I rarely found this lifecycle written down anywhere. There, it is scattered across status strings in the database, if cascades in the service and the memory of the longest-serving colleague. Here, it is a few lines long, versioned and visible to every client:
stateDiagram-v2 [*] --> angefragt: fahrtAnfragen angefragt --> warteAufBestaetigung: Matching in progress warteAufBestaetigung --> angenommen: angebotAnnehmen warteAufBestaetigung --> [*]: angebotAblehnen
This is also where the first ugly spot shows: warteAufBestaetigung. GraphQL names only allow ASCII – letters, digits, underscore. The “ä” has to stay out; the domain language only gets into the schema filtered. I write this down deliberately instead of hiding it: if you choose German identifiers, you also choose Bestaetigung, Strasse and ueberweisen. In running text, that would be a spelling mistake; in the schema, it is the price of the decision, and you should know it before you make it.
Schema in German, implementation in English#
The second question the experiment was supposed to answer: Where does the boundary run? After a few weeks, for me it lies exactly at the resolver map. The schema carries the domain language; everything behind it stays English – variables, helper functions, comments. Simplified, and written here with graphql-subscriptions, the pattern looks like this:
const uuid = require('uuid/v4');
const { PubSub } = require('graphql-subscriptions');
const pubsub = new PubSub();
const offers = {}; // in-memory store, resets on restart
const resolvers = {
Query: {
angebote: (root, { take = 10, skip = 0 }) =>
Object.values(offers).slice(skip, skip + take),
},
Mutation: {
fahrtAnfragen: (root, { input }) => {
// a ride request creates a new offer in its initial state
const offer = {
id: uuid(),
von: input.von,
nach: input.nach,
status: 'angefragt',
};
offers[offer.id] = offer;
pubsub.publish('offerChanged', { onAngebotChanged: offer });
return offer;
},
angebotAnnehmen: (root, { input }) => {
const offer = offers[input.angebotId];
// accepting is only valid while the offer awaits confirmation
if (offer.status !== 'warteAufBestaetigung') return offer;
offer.status = 'angenommen';
pubsub.publish('offerChanged', { onAngebotChanged: offer });
return offer;
},
},
Subscription: {
onAngebotChanged: {
subscribe: () => pubsub.asyncIterator('offerChanged'),
},
},
};
The German words appear exactly where the schema demands them: as keys of the resolver map and as enum values. The rest is ordinary English code. This separation has proven surprisingly stable, and it corresponds to the domain truth: offers and pubsub are technology and may be English. Angebot is a term with domain meaning, and it belongs to the business side – not to whoever happens to be implementing it.
A side effect I hadn’t expected: the tests suddenly read like domain texts, too. A Mocha test that calls fahrtAnfragen and then checks whether the status is angefragt describes a domain fact – you could copy it almost word for word into the ticket as an acceptance criterion. Test coverage turns into a piece of documented domain knowledge, without needing an additional tool.
What speaks against it#
Let me stay honest: the experiment also made the resistance visible, and it isn’t small.
The break in style first. type Angebot implements Node mixes two languages in one line. onAngebotChanged glues an English prefix onto a German noun and appends an English participle – an identifier made of three language layers. camelCase is built for English word boundaries; with German compounds it gets bumpy, and nobody reads warteAufBestaetigung fluently. That bothers you while reading, a little bit every day, and it never stops bothering you.
Then there is the ecosystem. Every tutorial, every Stack Overflow answer, every example in the Apollo documentation is in English – whoever transfers snippets now translates in the opposite direction. And the hardest limit is the team itself: as soon as a colleague joins who doesn’t speak German, the calculation flips completely. Then the German schema is no longer a bridge to the business side but a wall right through development.
And a practical point that counts in everyday work: searchability. If you search for an error message along with angebotAnnehmen, you find nothing – if you search with acceptOffer, you at least find other people’s discussions that half fit. German identifiers decouple a project to some extent from the web’s collective debugging. For a prototype, that doesn’t matter; for a team under deadline pressure, it does.
When the domain language wins#
So the trade-off isn’t a matter of taste but a question to the domain: In which language is the domain itself written?
A ride-hailing service is a rewarding playground, but the real use case is domains that are German – not out of habit, but by law. Contracts under German law. Collective wage agreements. Billing rules whose terms a German regulation prescribes word for word. In a billing project a few years ago, words such as “Abschlag” (installment) and “Gutschrift” (credit note) were legally defined; their English translations in the code regularly triggered discussions that didn’t exist in the domain at all – was the discount now an “Abschlag” or rather a “Rabatt”? When the law speaks German and the business side thinks in German, an English API layer is the only place in the system that translates. And therefore the only place that can lie without anyone noticing.
The reverse holds just as well. An international team, a product for several markets, a public API – there, English is the domain language, and then it belongs consistently in the schema. By the way, the SDL comes with a usable middle path: English identifiers, but German description texts on types and fields. Then the schema at least carries the definitions of the terms, if not their names – and the translation table sits where it is checked and versioned instead of gathering dust in a wiki.
The bottom line#
uber-ng won’t become a product, and it never had to. The experiment showed me two things. First: the place is right. A GraphQL schema can deliver what glossaries, wikis and model documents promised for fifteen years and didn’t keep – a shared language that is checked instead of merely described. Second: the language in the schema is an architecture decision, not a question of style. German in the schema has a cost – breaks in style, ASCII crutches, friction with the ecosystem. It pays off exactly when the domain is German and every translation would create a second, unchecked truth.
For the projects in between, the question stays open, and that is fine. All that matters to me is that it gets asked at all. So far, in every schema I have seen, it was silently answered with “English” – and silent answers are rarely the well-considered ones.
Further reading#
Revised and translated from German with the help of AI.