DEV Community: Faisal Mehmood

I Tried Aontu to Validate Microservice Architecture. Is It Worth the Complexity?

Faisal Mehmood — Wed, 21 Oct 2026 07:04:34 +0000

AI coding tools have made building software faster, but writing code is only one part of engineering. Keeping a system consistent as it grows is often the harder problem.

Consider a microservice application. One service depends on another, configuration values are shared across environments, and different developers make changes to the same architecture. If an AI coding agent introduces an invalid configuration or circular dependency, who catches it?

This question led me to explore Aontu, an open-source language and tool for defining constraints, validating structured data, and modeling relationships.

I installed Aontu on Ubuntu and tested it myself. My goal wasn't to explore every feature. I wanted to understand whether its approach could solve problems I might face in a real software project.

My First Impression: Easy Installation, Unfamiliar Concepts

I installed Aontu version 0.73.0 using npm. The installation succeeded without dependency audit warnings, and the CLI worked immediately through npx.

However, understanding the tool was harder than installing it.

Aontu has commands for schema validation, relationship analysis, provenance, compatibility checking, code generation, and more.

That flexibility is attractive, but it creates an onboarding problem. Someone looking for a configuration validator may feel overwhelmed before understanding the basic workflow.

Its syntax also takes adjustment. Developers familiar with JSON, YAML, or JavaScript validation libraries need to understand concepts such as unification, defaults, and map templates.

I found myself asking whether Aontu was simplifying configuration management or introducing another abstraction I would have to maintain.

The Interesting Part: Architecture as a Constraint

My first experiment involved defining two services: an API service and an authentication service.

I gave both services a common structure and specified a default tier. Aontu correctly applied the default to the API service while preserving the authentication service's explicit value.

That sounds simple, but the underlying approach matters.

Traditional configuration files primarily describe values. Aontu can describe both the values and the rules those values must satisfy.

The more compelling experiment involved circular dependencies.

I modeled an API service calling an authentication service while the authentication service called the API service.

For the relationship, I used Aontu's constraint:

calls?: rel() & acyclic()

Aontu rejected the model with a relation_cycle error.

I liked this result because circular dependencies are architectural problems, not merely incorrect data types.

In a larger project, expressing such restrictions as constraints could provide a useful safeguard during code reviews or automated changes.

However, Aontu cannot automatically understand every rule of an application. Developers must still identify and define the right constraints. An incomplete model can provide a misleading sense of confidence.

That distinction matters, particularly when AI agents are generating code.

Error Detection Was Good. Error Communication Was Mixed.

I deliberately changed a numeric configuration value to a string.

Aontu correctly rejected it and identified both the invalid value and the relevant schema declaration.

Technically, that is excellent behavior. Knowing where a conflicting value originated is much better than receiving a generic validation failure.

But the diagnostic also included:

Empty disjunction. The disjunction has no valid alternatives.

I understood that the values were incompatible, but this terminology would probably confuse a beginner.

The circular-dependency diagnostic had a similar issue. It detected the problem correctly, yet it did not display the complete api → auth → api cycle in my test.

Instead, it identified an offending relationship path and pointed to the schema constraint.

I would prefer an error message that begins with an explanation developers can act on immediately, followed by the more detailed technical reasoning.

A validation tool should not only identify what's wrong; it should make fixing the problem easier.

The Feature That Impressed Me Most

One of the most useful things I discovered was Aontu's ability to explain where configuration values came from.

When I queried the API service's tier, Aontu traced the value back to the default declaration in my source file.

This might seem like a small feature, but configuration debugging becomes difficult when teams introduce shared defaults, overrides, and multiple sources.

Usually, developers must search through files to figure out why an application received a particular value.

Aontu's provenance functionality provides that explanation directly.

I can imagine this being particularly valuable in infrastructure repositories or systems with many interconnected configuration definitions.

For me, this was one of the clearest advantages over simply storing configuration in ordinary JSON files.

A Small Problem That Says a Lot About Developer Experience

I also tried Aontu's project initialization command.

It generated a sample model, example data, and a shell script containing validation checks.

That was encouraging because it provided a working starting point.

But when I executed the generated script, it failed:

check.sh: 16: aontu: not found

The issue was straightforward. I had installed Aontu locally, while the generated script expected the executable to be available on my shell's PATH.

After adding the local npm executable directory to PATH, the script worked correctly.

This wasn't a serious technical defect, but it was unnecessary friction.

Developers often evaluate tools through their first successful experience. A starter project should account for common installation methods or clearly explain its assumptions.

Validation Coverage Is More Important Than It Sounds

My final experiment revealed another interesting feature.

Aontu can report how much input data was actually checked against a schema.

The generated example showed that all four data leaves had been constrained.

I then intentionally wrote an ineffective schema using "*" where Aontu expected its &: map-template syntax.

The result was revealing: none of the four data leaves were checked.

Normal validation reported an incomplete result. Strict coverage returned a failure and explicitly explained that validation had examined nothing.

This is a useful safeguard because successful-looking validation workflows can give developers confidence even when their rules do not cover the intended data.

I particularly appreciated that Aontu exposed this problem instead of leaving developers to discover it through unexpected behavior.

Would I Use Aontu in a Real Project?

After these experiments, I have a more balanced view.

I wouldn't introduce Aontu into every application. For a small project with straightforward configuration requirements, conventional schema validation would probably be easier to understand and maintain.

But for a system with interconnected services, complex configuration rules, and frequent automated changes, I can see its value.

The strongest features I tested were relationship validation, clear source provenance, and validation coverage.

Its main weaknesses were the learning curve, specialized diagnostic language, and small onboarding inconsistencies.

I also wouldn't treat Aontu as a complete solution for AI-generated code quality. It can reject violations of defined constraints, but it cannot replace meaningful tests, security reviews, or engineering judgement.

Final Thoughts

What interests me most about Aontu is not its connection to AI tools. It's the idea that architectural expectations can become executable constraints rather than remaining only in documentation.

My local experiments showed that this approach can catch real inconsistencies.

At the same time, powerful abstractions come with costs. Teams need to understand the language, maintain accurate models, and interpret validation results correctly.

My verdict: Aontu is worth exploring when architectural consistency is a recurring problem, but I would validate its benefits through a small proof of concept before adopting it across a project.

That seems like a more meaningful reason to use it than simply adding another tool to an AI development workflow.

Project reviewed: Aontu

One Prompt Template, Three Engines That Disagree

Faisal Mehmood — Sat, 08 Aug 2026 07:34:16 +0000

Written against main at the time of publishing. Every regex and line number is cited so you can re-check with grep -n and there's a runnable reproduction at the end that needs no build.

TL;DR

A PROMPT_TEMPLATE artifact in Apicurio Registry is rendered by three
different pieces of code that don't share an engine and don't agree on what a template means beyond a plain {{name}}. Add a space, a dot, or an {{#if}} block and the same stored template renders three different ways. If you're going to build anything on top of prompt rendering a UI playground,a new client you have to know which of the three you're actually rendering against.

Storing a prompt template looks simple

You save some text with {{variable}} holes in it, hand it a set of arguments, and get a rendered string back. One artifact, one render.

Except the registry doesn't render it in one place. It renders it in three,and those three don't share an engine. A template that renders correctly over the
REST API can come back untouched over the MCP server, and be flagged as having novariables at all by the validator that gated it on the way in.

A renderer that returns a result is not the same as a renderer that returns a consistent one. This post walks through exactly where the three surfaces diverge, using the real classes and the real regexes.

The three-surface model

A PROMPT_TEMPLATE artifact is consumed by three independent pieces of code:

Surface	Class	Job
REST	`PromptRenderingService`	Renders a template to a string for HTTP clients
MCP	`PromptTemplateConverter`	Renders a template for Model Context Protocol clients, including `{{#if}}` blocks
Validator	`PromptTemplateContentValidator`	On write, decides which variables the template "declares"

They live in three different modules (app, mcp, schema-util). None of them calls the others. Each one carries its own idea of what a template is encoded in its own regular expression.

The objects involved

There is exactly one source of truth: the stored artifact content. Everything downstream is a consumer reading the same bytes.

                    ┌──────────────────────────────┐
                    │  Stored PROMPT_TEMPLATE       │
                    │  content:  "Hi {{ name }}"    │   ← one source of truth
                    └───────────────┬──────────────┘
                                    │  same bytes, three consumers
           ┌────────────────────────┼────────────────────────┐
           ▼                        ▼                        ▼
   ┌───────────────┐       ┌────────────────┐       ┌──────────────────┐
   │ REST          │       │ MCP            │       │ Validator        │
   │ PromptRender- │       │ PromptTemplate-│       │ PromptTemplate-  │
   │ ingService    │       │ Converter      │       │ ContentValidator │
   ├───────────────┤       ├────────────────┤       ├──────────────────┤
   │ \{\{([^}]+)\}\}│      │ key spliced    │       │ \{\{(\w+)\}\}    │
   │ + .trim()     │       │ unescaped      │       │  (strict)        │
   └───────┬───────┘       └───────┬────────┘       └────────┬─────────┘
           ▼                       ▼                         ▼
       "Hi Ada"            "Hi {{ name }}"            declares: (nothing)
        renders            whitespace breaks it       name not recognized

That single picture is the whole story. The rest of this post is just proving
each of those three boxes really behaves that way.

A small template example

Take the simplest possible template and one argument:

template:  Hi {{name}}
args:      { "name": "Ada" }

All three surfaces agree here. REST renders Hi Ada, MCP renders Hi Ada, and
the validator sees one declared variable, name. Good. This is the case everyone
tests, and it's why the divergence hides so well.

Now change one thing at a time.

Two grammars, not one

The REST renderer matches variables with this pattern, and then trims the capture:

// PromptRenderingService.java:27
private static final Pattern VARIABLE_PATTERN =
        Pattern.compile("\\{\\{([^}]+)\\}\\}");

// PromptRenderingService.java:361
String varName = matcher.group(1).trim();

[^}]+ means "one or more characters that aren't a closing brace." That is a
generous grammar. It matches whitespace. It matches dots. It matches # and
/. And because of the .trim(), {{ name }} and {{name}} are treated as the
same variable.

The validator — the code that decides, on write, which variables a template
declares — uses a different, stricter pattern:

// PromptTemplateContentValidator.java:30
private static final Pattern TEMPLATE_VARIABLE_PATTERN =
        Pattern.compile("\\{\\{(\\w+)\\}\\}");

\w+ is "word characters only." No spaces, no dots, no symbols. So the set of
variables the server accepts as declared and the set of variables the server
will actually substitute are defined by two different regexes in two different
modules. The write path and the render path do not speak the same language.

What happens with whitespace

Add a space:

template:  Hi {{ name }}
args:      { "name": "Ada" }

REST → Hi Ada. [^}]+ captures name, .trim() makes it name, substituted.
MCP → Hi {{ name }}. Unchanged. (Why, in the next section.)
Validator → declares nothing. \w+ never matched name.

Same template. One surface renders it, one leaves it raw, and the gatekeeper
thinks it has no variables at all.

Why MCP leaves it raw — the substitution nobody escapes

MCP declares a VARIABLE_PATTERN at the top of the file, exactly like the others:

// PromptTemplateConverter.java:25  — declared but never referenced
private static final Pattern VARIABLE_PATTERN =
        Pattern.compile("\\{\\{(\\w+)\\}\\}");

It's never used. The real substitution doesn't compile a pattern for the whole
template. It loops over the arguments and builds a regex per key, on the fly:

// PromptTemplateConverter.java:441
String placeholder = "\\{\\{" + entry.getKey() + "\\}\\}";
// :443
rendered = rendered.replaceAll(placeholder, Matcher.quoteReplacement(value));

Two things fall out of this:

It builds a regex that matches {{name}} exactly — no [^}]+, no .trim(). So {{ name }} with spaces never matches, and the placeholder survives into the output. That's the whitespace result above.
The replacement value is escaped with Matcher.quoteReplacement, but the key is spliced straight into the pattern with no Pattern.quote. The key becomes regex source. For an ordinary name that's harmless; for a key with regex metacharacters it is not the same string match REST would do.

The triple-brace and the dotted path

Two more probes, to show it isn't only whitespace.

template:  Raw: {{{name}}}     args: { "name": "Ada" }
  REST → Raw: {{{name}}}       (the greedy match lands on {name, no such arg → left literal)
  MCP  → Raw: {Ada}            ({{name}} is found *inside* the braces and replaced)

template:  Hi {{user.email}}   args: { "user.email": "a@x" }
  REST → Hi a@x                ([^}]+ matches the dot)
  MCP  → Hi a@x                (the unescaped '.' happens to match the literal dot)
  Validator → declares nothing (\w+ rejects the dot)

The dotted-path row is the sneaky one: REST and MCP agree on the output, and
it's the validator that's the odd one out — it never considered user.email
a declared variable in the first place. So "the surfaces disagree" isn't even a
clean two-against-one; which surface is the outlier depends on the construct.

The full divergence table

This is the output of the reproduction script (verify_divergence.py), which
re-implements each surface using its exact on-main regex:

probe          REST                          MCP              validator sees
--------------------------------------------------------------------------------
plain          Hi Ada                        Hi Ada           name
whitespace     Hi Ada                        Hi {{ name }}    (none)
triple-stache  Raw: {{{name}}}               Raw: {Ada}       name
if-block       {{#if premium}}VIP Ada{{/if}} VIP Ada          name
dotted-path    Hi a@x                        Hi a@x           (none)

Only the first row — plain {{name}} — is unanimous. Every other construct
produces at least one disagreement. And {{#if}} blocks only exist on MCP at
all: REST has no concept of them, so it emits the raw {{#if}} and {{/if}}
tags into the output.

So is this a bug?

Some of these divergences may be intentional; {{#if}} on MCP but not REST could
be a deliberate feature-gap, not an oversight. I'm not calling the code broken.
The point that survives either way is narrower and more useful:

The same stored template does not have a single, well-defined rendering. What
it means depends on which surface serves it.

That's a fact about the architecture, and it's the fact anyone building on top of prompt rendering needs to design around.

Why I care: building a UI Playground on top

I'm proposing a Prompt Template Playground in the Registry UI a panel where you edit a template, fill in variables, and see the rendered result before you save.

The table above is the reason this feature is harder than it looks, and the reason it's worth doing carefully. A playground has to render the preview somehow. If it quietly reimplements a fourth regex in TypeScript, it becomes a fourth
dialect now there are four answers to "what does this template mean." The correct design is the opposite: the playground must render against the surface the
user is actually going to call, and be explicit about which one. Anything else is a preview that lies.
That's also why the first useful contributions here are backend-shaped, not just
UI polish: before a playground can tell the truth, the surfaces have to agree on what the truth is.

What to remember

A PROMPT_TEMPLATE is rendered by three independent surfaces (REST, MCP, validator) that do not share an engine.
They encode three different grammars: [^}]++trim (REST), exact-key splice (MCP), strict \w+ (validator). Only plain {{name}} renders the same everywhere.
Before you build anything on top of prompt rendering, pin down which surface you're rendering against or you'll ship a fourth dialect.

Reproduce it yourself

No build required the repo re-implements each surface with its exact on-main regex and prints the table above:

git clone https://github.com/Faisal77666/prompt-template-render-divergence
cd prompt-template-render-divergence
python3 verify_divergence.py

Source it's checking against:

PromptRenderingService.java REST renderer (:27, :361)
PromptTemplateConverter.java MCP renderer (:25, :441)
PromptTemplateContentValidator.java write-time validator (:30)

Line numbers reflect main at the time of writing. If they've drifted, a quick
grep -n on the patterns above will find them.