Quick Tip: Runtime Version and Business Central Version Are Not the Same Thing

Ask a new AL developer what version of Business Central they are targeting and you will usually get an app.json screenshot and a shrug. Business Central exposes at least three different numbers for what people casually call “the version,” and only one of them controls what code you are allowed to write.

Three numbers, three meanings

Platform or internal version, such as 28.2. The actual build of the service. Shows up in the admin center and KB articles.
Release wave name, such as 2026 release wave 1. A marketing label tied to a specific internal major version. Tells you roughly when a feature set shipped, nothing more.
Runtime version, set as "runtime": "17.0" in app.json. The number that matters to you as a developer, since it determines which AL language features and compiler behaviors are available.

These numbers are related but do not move in lockstep. The runtime version is deliberately allowed to lag behind the platform version.

What the runtime version controls

Set it too low and features you assume are available will fail to compile.
Set it too high and you unknowingly require a platform version your customer has not reached yet.
An extension publishes only to environments running the same runtime or a later one, never an earlier one.
Leave the property out entirely and the compiler defaults to the latest major version it supports, which shifts every time VS Code or the AL Language extension updates.

Same or later runtime only.

That single rule is why runtime choice is a compatibility decision, not a formatting detail.

See Microsoft’s documentation on choosing a runtime version.

The current mapping

Runtime version	Shipped with	Internal version
15.0	Business Central 2025 release wave 1	26.0
16.0	Business Central 2025 release wave 2	27.0
17.0	Business Central 2026 release wave 1	28.0

Runtime 17.0 ships with internal version 28.0, an eleven point gap that is neither a typo nor fixed. Runtime numbering restarted at 1.0 with the April 2018 release while internal platform numbering kept counting from an earlier point. Do not expect the two to track by a constant offset.

Why pick an older runtime on purpose

In partner organizations serving customers on staggered update schedules, you often want the lowest runtime that still gives you the features you need, not the newest one available in VS Code.

Benefit: avoids accidentally using a language feature that only exists in a newer runtime, which would block installation on customers a wave or two behind.
Cost: no access to newer AL capabilities until you raise the runtime, plus the discipline of testing against a platform version you are not actively developing on.

Run a periodic build against the latest runtime even while app.json targets an older one. It catches new compiler diagnostics before they surprise you at upgrade time.

Mistakes worth naming

Assuming the runtime property is optional because the extension compiles without it. It compiles, but silently binds you to whatever runtime is latest at compile time.
Assuming a higher runtime number means more compatible. It means the opposite: it raises your minimum required platform version.
Confusing a KB build number, such as 28.2.51034, with the runtime number that belongs in app.json. They are not interchangeable.
Never revisiting the runtime property after the initial scaffold, even as the extension’s actual requirements change.

The practical takeaway

Treat runtime version as a compatibility contract you actively manage, not a field VS Code fills in for you.

Know the lowest runtime your extension genuinely needs, set it explicitly, and revisit that choice when new AL capabilities become worth the trade off.

The platform version tells you what Microsoft shipped. The runtime version tells you what your code is allowed to assume.