API ManagementDomain-Based Information Model

Applying Domain-Driven Design to the Canonical Model

Lately it seems ‘canonical’ has a bad rep. The truth is, one-size-fits-all rarely fits anyone — but when it comes to enterprise service building, there are huge benefits to the ability to reuse, refine, or extend a great thing that’s already been built.

This week, we had a chat with API expert Brian Otten, to see what he had to say about canonical, information models, and domain-driven design.

Why has there been adversity to “canonical”?

Brian: It’s viewed as rigid, use as-is, hard to make changes, hard to do impact-analysis of changes. So if I change things in the model, am I going to break things all over the place? It goes back to principles of service-design, or API design — You don’t want to introduce breaking changes, or changes that are not backwards-compatible.


And yet canonical is still relevant.

Brian: Sure — it allows us to have mapping for naming conventions, it obviates integration transformation, it simplifies and ensures a Business-driven model… it’s a question of moving the dial on from the world of integration where one application has services, even if it’s service enabled, if your APIs all have one model.


Could we get an in-the-field example?

One of ignite’s banking customers is a great example. They have Provider Services, so they’re the ones that are pulling in the Payment info from their customers, and then putting it through to their middleware or their payments platform where all of the payments get processed, and then that sends it back out to some consumer service that will then allow them to say “Well, this payment has been processed and here’s your transaction number and here’s this, that, or the other.”

So you’ve got these fully fledged products with a whole bunch of running services and APIs, and if the consumer services AND the middleware AND the providers all have different models, (in other words, there’s no canonical) how am I supposed to know if I’m receiving a payment instruction, and if I need to process that payment in my internal platform, how do I know what’s what? If I’m calling this one Payment ID, and the other one Payment Ref, or something, well now I need a translation. I need some kind of transformation to take that format, because it’s a different format of the data, different naming conventions, and maybe it’s even broken up into two different things, so you would need a complex mapping to try to work out what one concept is, one property, one attribute, one element on one side, and one on the other.


So you’re able to use domain-based models in place of that transformation?

By having canonical on both sides, everything can talk canonical, so I don’t need a transformation. I can just pump that data in, it knows exactly what to do with it, and then all of the code can just run, right? I won’t have to transform anything into anything else. Then the consumer says, okay, here’s my payment info, Maybe I’m doing a settlement, process payment information, it’s also in canonical form, so that I can track Payment, or Payment Ref, whatever, and I can track that thing more easily through all of the working bits of the system. It kind of obviates the whole integration transformation thing. Makes that a whole lot simpler.

So you can decide once, it maps to whatever your business thinks of it, and you don’t have another team coming along making things up, and then misusing that thing because “Oh I thought it was the Payment Reference, but it looks like actually it was the Sub-Payment Reference number and the…” and people misuse the data. Without canonical there could be ambiguity around what the data is supplying.


So how is a Domain-Based Information Model like a “New Canonical”?

Brian: The old was one-size fits all.

It’s a separation of concerns. With a Domain-Based Information Model, you’re truly getting the right granularity. You’re dealing with the right data in the right place. Let’s take a healthcare agency, for example. Let’s say I have a service that needs to see whether a member of my healthcare system is going to be eligible for certain coverage and benefits. Say I make up my own version of what a benefit looks like, because I’m on the Membership team. But then there’s another team that actually looks after all of the products and benefits, maybe we have one or more systems that manage those products and benefits. Again, maybe we’re going to be in that situation where mine isn’t the same as yours.

Or maybe you have the problem where if you built it in a deeply hierarchical way, like a lot of the canonical models where I’m having to trim stuff out all of the time — they’re building for one size fits all — a Domain-Based Information Model breaks that model and data into the right granularity, so that you can use it more effectively.


What are the benefits of this newer model?

Brian: It’s a question of being able to federate the model, a granularity and ownership thing. The right people who know about that data own that part of the model, and they get out of the business of owning parts of the model that they don’t really need to own. The side effects are that you get a flatter model — unlike the kind of relational data where, although we had databases, you had to encapsulate all those relationships, then have one table that has all of the keys to another thing, because I want to work on a query where I find all of the Policies for a Member, and make the data model represent ALL of that stuff — with APIs you don’t have to do that. You can truly separate that stuff off and encapsulate it. And that’s more in line with microservices architecture, where you just want to own the data in YOUR domain, and you want to get out of the business of owning that other data and its model. So it kind of results in a flatter model, where some of the industry-standard canonical models (like ACORD, FPML, and all of those in the banking industry) took the one-size fits all approach. So you have these big objects that contain all of the relationships. But with granular APIs and microservices, you don’t want to have to have all of that stuff in your model. So there’s less bloat.


How does that fit in with DDD (Domain-Driven Design)?

Domain should drive the design. Eric J. Evans

3 key principles:

  • Expert involvement — Experts and designers (business + IT)
  • Ubiquitous language — Develop a common language (CBL = Common Business Language)
  • Iteration and refinement — This is essentially the living canonical. You cannot spend 6 months on a model that reflects the business 6 months ago if you need to build services for now.

Brian: With ignite, it’s really about doing the canonical modelling in conjunction with the API design in effect.

And that’s why with the domain-driven development, you develop the model WITH the APIs, right? A lot of companies have these big architecture teams and they come up with the business models first, and then the data models afterwards, saying “Here, you have to use this!” But because the model wasn’t built in the context of the business process and operations, there are problems. And that’s exactly what you’re doing with APIs — how do people need to see this data to perform X function?

Again, we’re back to the transformation problem. I have a model, even if that means just trimming out stuff, cutting out stuff, it’s a little error prone. It’s all about trying to solve for that problem — one of the toughest ones for service design was the granularity of both the services and the data model.


In ignite, what elements does the domain-based information model include/bake into the API Product or microservice you’re building?


For more information on the domain-based information model and how that fits in with the rest of your holistic API and service catalog, download our PDF on domain-based information models.



Andy Medlicott

Andy is a digital expert and Lead Engineer at Waitrose and Partners. He has a passion for harnessing technology and industry trends to ensure excellent engineering practice which in turn delivers consistently high quality solutions.

Related Articles