axis.json Reference

axis.json is the machine-readable project manifest — the contract between tooling (axs add, axs feature, axs doctor, AI assistants) and your project. Its conceptual overview is The axis.json Manifest; this page is the field-by-field reference for schema v1.

Top-level fields

Field	Type	Notes
$schema	string	Frozen, versioned URL: https://axs.axis-tech.dev/schema/axs.v1.json
framework	string	Always @axis-tech-co/axis-framework.
frameworkVersion	string	The framework major line, e.g. 1.x.
starter	enum	rest-v1 | rest-v2 | graphql | bare | worker.
layout	enum	module | feature. See the matrix below for supported pairings.
wiring	enum	manual (or absent) | composer.
paths	object	Where generated code goes — see below.
conventions	object	How code is grouped — see below.
selections	object	Composer only: which stacks/groups are on, and each stack’s mode.
tokens	object	Composer only: lets axs feature <name>=on re-emit pruned config.

Unknown fields are ignored (additionalProperties: true) — v1 is additive.

paths

Field	module value	feature value
lambdas	lambdas/modules	lambdas/features
lambdaConfigs	config/lambda-configs	config/lambda-configs
tables	config/tables	config/tables
stacks	cdk/lib/stacks	cdk/lib/stacks

paths.tables is the registry path and is identical in both layouts. Where the individual table files sit is governed by conventions.tableLocation: central layout puts them directly under config/tables/, feature layout puts them at lambdas/features/<feature>/tables/<table>.ts and re-exports them through that same central registry.

conventions

Field	module value	feature value	Notes
lambdaGrouping	module-then-kind	feature-then-name	Required.
tableLocation	central	colocated	Required.
resolverLocation	central	colocated	Optional; graphql starter only.

lambdaGrouping controls how handler directories nest under paths.lambdas. module-then-kind produces <module>/<kind>/<name>/, where kind is one of api, worker, cron, edge. feature-then-name produces <feature>/<name>/ with no kind tier — the lambda config’s own kind field is the source of truth instead.

resolverLocation records where AppSync resolver artifacts (.vtl and .js mapping-template and code files) live. It is emitted for the graphql starter only. central means assets/resolvers/; colocated means lambdas/features/<feature>/resolvers/, referenced by project-root-relative paths from the central config. An absent resolverLocation means central, so manifests written before the field existed keep working unchanged. axs doctor reports a finding when a project’s resolver artifacts don’t conform to the declared value.

The starter × layout matrix

Starter	module	feature
rest-v1	✅	✅
rest-v2	✅	✅
graphql	✅	✅
worker	✅	✅
bare	✅	❌ by design

bare is module-only deliberately, not pending — it exists as a minimal starting point with no feature scaffolding to group. Every other starter supports both layouts.

Passing an unsupported pairing to axs new fails with an error generated from this matrix, so the message never names a stale starter list.

Versioning

The v1 schema is frozen and additive: new fields may appear in v1, and readers ignore unknown fields. A breaking change ships as v2 with a new $schema URL, so old readers fail loudly rather than misread silently.

Who reads it

Tooling reads axis.json; the framework runtime never does. Its only contract with your code is the registries (Project Structure) — your deployed infrastructure can never depend on this metadata file.