Skip to main content
The App Definition is one JSON document that fully describes an application. The runtime, the UI renderer, the standalone generator and the publish pipeline all read this and nothing else. It says what the app is. What the app offers to everything outside it — its purpose, the events it announces, the actions it accepts — is a second compiled document, the App Contract. You don’t write it. You write semantic source, and the compiler produces this.

​
Why there are two formats

Because they answer to different readers. A real app makes that concrete. The Budget Planner corpus app is 98 source files totalling about 133 KB, and it compiles to a single 225 KB JSON document. Size isn’t the interesting part. Ninety-eight files that each describe one thing can be reviewed one at a time. A 225 KB document can’t be.

​
The same entity, both ways

In source, fields is a map and the field key is the map key. In the App Definition, fields is an array and every item carries its own key. Maps read better and can’t hold a duplicate key. Arrays preserve order, which is what a schema validator and a code generator want.

​
The envelope

Five things are required at the top level: schemaVersion, key, name, version and entities. An app with no entities isn’t an app.
Everything else is optional, and each optional block is a concern the app may or may not have:
​
the data model
What the app stores and how records point at each other.
​
the interface
Block trees, the screens they compose into, and how the app looks.
​
behaviour
Lifecycles, the actions that move between states, and what happens automatically.
​
access
Who may read and write what.
​
metadata
What kind of application this is, and what it is for.

​
Where you’ll meet it

Mostly you won’t. Three places you might: cordango build writes it under .cordango/build/<key>/. It’s deterministic, so the same source produces the same bytes. cordango import goes the other way. Hand it an existing App Definition and it produces source files you can edit.
cordango publish sends one to an instance. It builds from source rather than from .cordango/, because a build artifact is a cache, and a cache isn’t an authority.
.cordango/ is build output. Editing the compiled App Definition in there won’t change your app, because the next build overwrites it. Change the source.

​
Comparing definitions

Two App Definitions with identical meaning can differ byte for byte, because storing one as jsonb reorders its keys. Compare them by their definition hash rather than by their text.

​
Next

The schema

The formal contract, how it is composed, and how to validate against it.

Targets

What turns an App Definition into a running application.