Idea logo Idea
Idea docs / Reference

Specification Reference

This page describes the core `.idea` file format as implemented by the parser in this repository.

View source Home

This page describes the core .idea file format as implemented by the parser in this repository.

It is a reference page, not a tutorial.

Scope

This specification covers:

  • declarations
  • literals
  • arrays and objects
  • comments
  • schema composition with use

It does not define the semantics of every possible attribute or plugin.

Lexical Elements

Strings

Strings use double quotes:

label "User"

Numbers

Integers and floats are supported:

count 1
price 9.99
offset -1

Booleans

enabled true
hidden false

Null

value null

Arrays

Arrays are space-separated:

roles ["ADMIN" "USER"]

Objects

Objects contain nested key-value pairs:

options {
  width 20
  height 20
}

Comments

Both line and block comments are supported:

// line comment
/*
  block comment
*/

Declaration Forms

use

use "./shared.idea"

Loads another schema file and merges it into the current schema.

Package-based imports are also valid:

use "stackpress/stackpress.idea"

plugin

plugin "./schema-diagram.mjs" {
  output "./generated/schema.mmd"
}

The declaration key is the module path. The block is stored as the plugin config object.

Plugin modules can also be resolved from installed packages:

plugin "stackpress-schema/transform" {
  output "./generated/schema.json"
}

prop

prop EmailField {
  type "email"
  required true
}

enum

enum Role {
  ADMIN "ADMIN"
  USER "USER"
}

type

type Address {
  street String
  city String
}

model

model User {
  id String @id
  email String @unique
}

Attributes

Attributes attach metadata to declarations and fields:

email String @required @field.email @db.varchar(255)

Declaration-level attributes are also valid on model and type:

model User @icon("user") {}

type Address @label("Address") {
  street String
}

The parser preserves attributes and their values. The core format does not assign fixed semantics to every attribute namespace.

Schema Composition

When the transformer loads a schema with use, it loads child schemas first and merges them into the parent schema.

The merge behavior includes:

  • soft merge for prop
  • soft merge for enum
  • name-based merge for type
  • name-based merge for model
  • local definitions can extend imported type and model entries
  • ! marks a local type or model as an overwrite boundary

Mutable parent types and models can absorb child columns instead of being replaced.

Parser Guarantees

The parser guarantees:

  • declaration structure
  • supported literal parsing
  • array and object parsing
  • preservation of parsed schema metadata

Non-Goals

This specification does not define:

  • what every @field.* attribute means
  • what every @db.* attribute means
  • what files plugins generate
  • framework-specific or database-specific output contracts

Those belong to plugin or project documentation.

See Also