Acore language

Acore is the declarative language you use to author AxiomCore contracts and applications. One .acore file describes data, endpoints, user interfaces or database schemas, and the Axiom CLI checks it and builds an artifact. Acore is an independent language and does not need a Pkl runtime.

How a .acore file is evaluated

Diagram source

flowchart LR
  A[".acore source"] --> B["Select profile from AxiomDeps.toml"]
  B --> C["Parse"]
  C --> D["Resolve import, amends and use"]
  D --> E["Evaluate and check types"]
  E --> F["Validate for the profile"]
  F --> G[".axiom contract"]
  F --> H[".axiom package"]
  F --> I[".axiomapp application"]
  F --> J["axiom eval output"]

1. Select the profile. The type in the nearest AxiomDeps.toml selects the grammar and rules. A file with no manifest type is a general module. Older backend sources that start with profile backend 1 are still read.
2. Parse. The parser keeps source spans so diagnostics and editors point at the authored text.
3. Resolve. import and amends load other source or extractor input. use contract reads a compiled .axiom through the manifest and lock. An import cycle is an error.
4. Evaluate. Properties are lazy: a value is computed when something references or renders it. Source order is not execution order. Type annotations and constraints are checked.
5. Validate. The profile applies its own rules, such as backend validators, domain and security analysis, or UI checks.
6. Output. The command decides what is written or printed. A backend build validates the contract schema and writes the canonical .axiom; it does not dump arbitrary JSON. Acore UI lowers to a UI graph and a target bundle. For backend contracts, one named variant is applied before output.

Profiles

A declaration accepted by one profile is not automatically valid in another.

Database sources go through the offline database compiler. General evaluation of a database source fails with ADB158, because evaluation cannot acquire migration authority.

Minimal sources

project(id: "hello-api", version: "1.0.0")
model Greeting { message: String }
endpoint hello(method: GET, path: "/hello") {
  response(type: Models.Greeting)
}

module example.hello.ui
app Hello { route "/" => Home }
page Home {
  view {
    SafeArea { Text("Hello from Acore") }
  }
}

amends "axiom-fastapi:./main.py:app"
project(id: "tasks-api", version: "0.1.0")
policies(retry: RetryPolicy(maxAttempts: 3))

The Acore schema reference lists exact fields and defaults.

Commands that read Acore

A general module and its evaluated output:

module example.config
name = "orders"
port: Int = 8080
retry { attempts = 3 }
hidden secretSuffix = "internal"

axiom eval config.acore -f json

{
  "name": "orders",
  "port": 8080,
  "retry": {
    "attempts": 3
  }
}

Rendered output sorts keys and omits null values, hidden and local properties, names that start with _, functions and a property named output. To render one value instead of the whole module, set output { value = settings }. PCF, the default format, is the canonical text form used by the toolchain. The language library also has XML and Protocol Buffers renderers, but axiom eval does not select them. -f md is meant for contracts: it prints API documentation with a Mermaid route diagram.

Authority and imports

Evaluation runs under a security manager that controls module, file, environment and package access. A path in source is a request for access, not proof of authority. Evaluation does not fetch network modules. A compiled .axiom is not source: import and amends reject it, and you consume it with use contract through a manifest and lock. Declarative .axiom packages do not gain execution authority. An extension package carries metadata, requested capabilities and a digest for separately distributed code; running that code is a separate host decision.

Errors

Commands add their own codes for artifact, runtime, UI, package and Cloud boundaries. Use the narrowest check that does not write files, for example axiom doctor --json, axiom check, axiom domain validate, axiom security check or axiom ui check main.acore --target web. Not every source needs every check.

Reproducible builds

An artifact is reproducible only when the source, resolved dependencies, compiler version, target and build mode are all the same. Commit dependency locks and record build provenance. Matching top-level source alone does not make two builds identical.

Read the reference

Next steps

• Run your first app
• Learn the syntax
• Build a backend
• Acore UI reference