Announcing Concerto v4.0

We’re excited to announce the release of Concerto V4! – a significant project milestone, and a major step forward for everyone who builds with data models. Before we begin to look at the latest and greatest additions, a big thank you to all in the open source community, whose contributions, both directly and indirectly, made this release possible.

If you’re new here: Concerto is an open-source data modeling language and runtime, maintained as part of the Accord Project. It lets you define schemas such as concepts, assets, participants, transactions, and then validate data, generate code, and serialize objects against them across JavaScript, JSON Schema, C# and many other language targets. It’s the data backbone of the Accord Project’s smart legal contracts stack, and adopted and used at scale by Docusign to define the data structures required for agreement generation and verification. Concerto is useful anywhere you need a portable, language-neutral way to describe your domain.

With the V4 major release, Concerto modernizes the codebase with TypeScript, ships two brand-new packages, and changes several long-standing defaults to be stricter and faster. And to top it off: most of your existing .cto model syntax still works as-is. The main thing to plan for is your application code, anything calling the Concerto JavaScript API will likely need a few updates. We’ll walk you through this, and more, below.

See also v4.0.0 release notes and the v4.0.0 migration guide.

What’s new

TypeScript, end to end

Every Concerto package now ships with TypeScript configurations and type definitions. If you build with TypeScript, you get proper IntelliSense, autocomplete, and compile-time type checking against the Concerto API out of the box; there is no longer a need for a separate @types package!

Two new packages – concertino & concerto-linter

@accordproject/concertino is a new lightweight package for client applications that need to introspect Concerto models without pulling in the full SDK. It offers a flatter model representation with denormalized inheritance, a smaller bundle size, and lossless conversion to and from the Concerto metamodel. If you’ve ever wanted Concerto’s modeling power in a browser app without the weight, this is for you.

@accordproject/concerto-linter brings linting to your model files. Built on customizable Spectral rulesets, it ships with a default rule set covering best practices: things like string length validation, PascalCase decorator conventions, and reserved keyword checks.

Maps and import aliasing are now standard

Two features that previously required feature flags or environment variables are now enabled by default: Maps and import aliasing. Use them straight away, no additional configuration needed!

Faster by default

Concerto v4 includes a round of performance work: parsing is faster (more on the reason for that below), decorator management uses an optimized deep-copy path, and several core operations have a reduced memory footprint.

Breaking changes – read before upgrading

With a new major version, comes major changes. Here’s what to plan for.

Node.js 22+ required

The minimum supported Node.js version is now 22.x. Concerto 4.0 supports the 22.x (LTS) and 24.x lines. Support for Node.js 16, 18, and 20 has been removed.

Always Strict – There’s no opt out anymore

In 3.x, strict mode was off by default, which allowed unversioned namespaces and wildcard imports. In v4.0, strict mode is on by default – versioned namespaces and explicit imports are required.

This is the change most likely to affect your model files. The fix is fairly straightforward, simply add version numbers to your namespaces and replace wildcard imports with explicit type imports.

The functional Concerto class has been removed

The Concerto class that wrapped a functional-style API is gone. Use ModelManager, Factory, and Serializer directly instead.

Location nodes skipped by default

To speed up parsing, the parser no longer attaches source location information (line and column numbers) to the AST by default. If you build tooling that needs source mapping, for example editors, linters, error highlighters – you can always opt back in:

Get Started! Upgrade your Project

Bump your @accordproject/concerto-* dependencies to ^4.0.0:

In summary:

• Environment – move to Node.js 22.x or later, and npm 10+.
• Dependencies – update all @accordproject/concerto-* packages to ^4.0.0 and reinstall.
• Model files – add versions to your namespaces, and swap wildcard imports for explicit ones.
• Application code – drop any use of the Concerto class; add skipLocationNodes: false if you need AST locations.
• Testing – run your full test suite and validate your models with strict mode on.

See the full migration guide for more detail.

Thank you to all of our contributors

Concerto v4.0 is the result of a sustained modernization effort. The move to npm workspaces, full TypeScript integration, the introduction of two new packages, and a lot of careful testing – it would not exist without the Accord Project community. Thank you to everyone who contributed code, reviewed PRs, opened issues, and shared ideas. 🎉

Get involved

• 🛝 Try it instantly in the new Concerto Playground – no install required
• 📦 Install from npm or browse the source on GitHub
• 📖 Read the documentation
• 🐛 Report bugs or ask for help via GitHub Issues

💬 Join the conversation on the Accord Project Discord

The fastest way to see what’s new is the new Concerto Playground – write a single Concerto schema in your browser and watch it generate TypeScript, Java, Python, Go, JSON Schema and more, live. It’s the quickest way to get a feel for the modeling language, with no set up required! Give Concerto 4.0 a try, and let us know what you build.