`.apsorc` Configuration

The CLI reads .apsorc from the current directory or a parent directory. Keep this JSON file at the project root and commit it with the generated source.

Complete shape

.apsorc


{
  "version": 2,
  "language": "typescript",
  "rootFolder": "src",
  "apiType": "Rest",
  "http": true,
  "emitEvents": false,
  "coAuthor": true,
  "auth": {
    "provider": "better-auth"
  },
  "entities": [
    {
      "name": "Project",
      "table": "projects",
      "primaryKeyType": "uuid",
      "created_at": true,
      "updated_at": true,
      "scopeBy": "workspaceId",
      "fields": [
        { "name": "name", "type": "text" },
        { "name": "status", "type": "enum", "values": ["Active", "Archived"], "default": "Active" }
      ],
      "indexes": [],
      "uniques": []
    },
    {
      "name": "Task",
      "fields": [
        { "name": "title", "type": "text" },
        { "name": "priority", "type": "integer", "default": 3 }
      ]
    }
  ],
  "relationships": [
    { "from": "Task", "to": "Project", "type": "ManyToOne", "cascadeDelete": true }
  ]
}

Only include auth, scoping, event, and table settings that the service needs.

Top-level properties

Property	Type	Default	Use
`version`	number	`1` for legacy files	Set `2` for new projects.
`language`	string	prompt	Select `typescript`, `python`, or `go`. `apso generate --language` can override it.
`rootFolder`	string	`src`	Select the generated source root.
`apiType`	string	`Rest`	Select REST or, where supported, GraphQL generation.
`entities`	array	`[]`	Define database models and generated resource layers.
`relationships`	array	`[]`	Connect entities using version 2 relationship objects.
`auth`	object	none	Configure Better Auth, custom sessions, JWT, or application API-key auth.
`http`	boolean	`true`	Set the top-level default for generated HTTP controllers.
`emitEvents`	boolean	`false`	Set the top-level default for domain events on entity writes.
`coAuthor`	boolean	`true`	Opt out of the Apso commit co-author hook when set to `false`.

Entity properties

Property	Type	Default	Use
`name`	string	required	Set the framework class and default resource name.
`table`	string	snake-case name	Override the database table name.
`fields`	array	`[]`	Define stored columns and validation input.
`primaryKeyType`	string	`serial`	Select `serial` or `uuid`.
`created_at`	boolean	`false`	Generate a managed creation timestamp.
`updated_at`	boolean	`false`	Generate a managed update timestamp.
`indexes`	array	`[]`	Define indexes.
`uniques`	array	`[]`	Define composite unique constraints.
`scopeBy`	string or array	none	Select fields or paths used for authorization scope.
`scopeOptions`	object	defaults	Control create injection, enforced operations, and bypass roles.
`http`	boolean	top-level value	Override HTTP generation for one entity.
`emitEvents`	boolean	top-level value	Override domain-event generation for one entity.

Field shape


{
  "name": "amount",
  "type": "decimal",
  "precision": 12,
  "scale": 2,
  "nullable": false,
  "index": true
}

Fields support name, type, values, nullable, index, primary, unique, default, length, precision, scale, and is_email. See Field Types for compatibility and examples.

Relationship shape


{
  "from": "Task",
  "to": "Project",
  "type": "ManyToOne",
  "to_name": "project",
  "nullable": false,
  "cascadeDelete": true,
  "index": true
}

Supported types are OneToMany, ManyToOne, ManyToMany, and OneToOne. Define each conceptual relationship once. The generator creates the inverse side where required.

Relationship objects can also set bi_directional, joinTableName, joinColumnName, and inverseJoinColumnName for join-table control.

Validate and generate


apso schema validate
apso generate

To validate a linked project without calling the platform validator, use local-only validation:


apso schema validate --local

.apsorc is JSON. Do not add comments, trailing commas, or environment variable interpolation unless the selected generator explicitly documents it.

Review entity keys, timestamps, indexes, scoping, and controller settings

Entities

Choose direction, ownership, nullability, and join-table settings

Relationships

Configure the generated request identity boundary

Authentication

.apsorc Configuration