Application

The application node is the root of every Terranova specification file. It defines global settings, entities, and deployment profiles for your API.

application "TaskManager" version="1.0" email="admin@example.com" license="MIT" namespace="/api/" serve-docs=true {
    entity "User" protected=true {
        schema {
            pk "id" type="int"
            field "username" type="string" unique=true
            field "email" type="string"
        }
    }

    entity "Task" {
        schema {
            pk "id" type="int"
            field "title" type="string"
            field "completed" type="bool"
            belongs-to "User" as="owner" on="id"
        }
    }

    profile "dev" default=true {
        listen address="127.0.0.1" port=8080
    }

    profile "prod" {
        listen address="0.0.0.0" port=443 cert="server.crt" key="server.key"
    }
}

Attributes

All attributes are written directly on the application node as key‑value pairs.

Attribute	Type	Required	Default	Description
`name`	string	✓	–	Application name (used in logs and UI)
`version`	string		`"1.0.0"`	Semantic version string
`email`	string		`"example@terranova.com"`	Contact email for the API
`license`	string		`"MIT"`	License identifier
`namespace`	string		`"/"`	Base URL prefix for all routes
`serve-docs`	bool		`true`	Whether to serve interactive API docs at `/docs.html` & `/docs.yaml`

Note: Attribute names are case‑sensitive. Use serve-docs (kebab-case) as shown.

Sub‑blocks

`entity`

Each entity defines a data model.

Example:

entity "User" {
    schema { ... }
    queries { ... }
    views { ... }
}

See Entities for the full reference.

`profile`

Each profile defines an environment‑specific server configuration. At least one profile must exist. If exactly one profile is defined, it is used automatically. If multiple exist, set default=true on one profile, or specify the profile name when running terranova serve --profile <name>.

Example:

profile "dev" default=true {
    listen address="0.0.0.0" port=80
}

profile "prod" {
    listen address="0.0.0.0" port=443 domain="example.com"
}

See Profiles for details.

Complete Example

application "BlogEngine" version="2.0" email="blog@example.com" license="AGPL-3.0" namespace="/v1/" serve-docs=false {
    entity "Author" {
        schema {
            pk "id" type="int"
            field "name" type="string"
            field "bio" type="string" optional=true
        }
    }

    entity "Post" {
        schema {
            pk "id" type="int"
            field "title" type="string"
            field "content" type="string"
            field "published_at" type="datetime" optional=true
            belongs-to "Author" as="author" on="id"
            has-many "Comment" as="comments" on-delete="cascade"
        }
    }

    entity "Comment" {
        schema {
            pk "id" type="int"
            field "body" type="string"
            belongs-to "Post" as="post" on="id"
        }
    }

    profile "development" default=true {
        listen address="127.0.0.1" port=8080
    }

    profile "production" {
        listen address="0.0.0.0" port=443 cert="server.crt" key="server.key"
    }
}

What Terranova Does With the Application

Validates that at least one profile exists.
Merges profiles: the selected profile’s listen nodes determine the server’s ports and TLS settings.
Prefixes all api routes (auto generated cruds & custom queries) with the namespace (e.g., /v1/post).
Generates OpenAPI documentation at /docs.html if serve-docs is true.