Schema System

schema_id: "users"
schema_version: "v1"

metadata/schemas/schema_<schema_id>_<version>.json

````

### Rules
- One file per schema version
- Schema files are immutable once written
- Deleting or modifying a schema file is forbidden
- Missing schema files cause startup failure

---

## Schema File Format

Schemas are defined using a **strict JSON-based DSL**.

### Top-Level Structure

```json
{
  "schema_id": "users",
  "schema_version": "v1",
  "description": "User account records",
  "fields": {
    "_id": {
      "type": "string",
      "required": true
    },
    "email": {
      "type": "string",
      "required": true
    },
    "age": {
      "type": "int",
      "required": false
    }
  }
}
````

---

## Field Definition Rules

Each field definition must specify:

| Property   | Required | Description                   |
| ---------- | -------- | ----------------------------- |
| `type`     | Yes      | Field data type               |
| `required` | Yes      | Whether field must be present |

No other properties are allowed in Phase 0.

---

## Supported Field Types (Phase 0)

| Type     | Description                                      |
| -------- | ------------------------------------------------ |
| `string` | UTF-8 string                                     |
| `int`    | 64-bit signed integer                            |
| `bool`   | Boolean                                          |
| `float`  | 64-bit floating point                            |
| `object` | Nested object with its own schema                |
| `array`  | Homogeneous array (single declared element type) |

### Notes

* Arrays must declare a single element type
* Objects must declare nested field schemas explicitly
* No union types
* No polymorphism

---

## Primary Key Rules

### `_id` Field

* Every schema **must** define an `_id` field
* `_id` must be:

  * Required
  * Unique within the collection
  * Immutable after insertion

The `_id` field is the primary key.

---

## Schema Validation Rules

### Validation Timing

* Validation occurs **before WAL append**
* Invalid data must never enter WAL or storage

---

### Validation Semantics

A document is valid if and only if:

1. All required fields are present
2. No undeclared fields exist
3. Field types exactly match schema types
4. `_id` is present and valid
5. Schema version exists and is known

Failure of any rule causes write rejection.

---

## Forbidden Behaviors

The following are strictly forbidden:

* Missing required fields
* Extra undeclared fields
* Implicit type coercion
* Default values
* Null values unless explicitly allowed (Phase 0: null forbidden)
* Partial validation

---

## Schema Versioning Rules

### Immutability

Once a schema version is created:

* It must never change
* It must never be overwritten
* It must never be deleted

Any change requires a **new schema version**.

---

### Creating a New Version

A new schema version must:

* Have a new `schema_version` identifier
* Be stored as a new schema file
* Not affect existing documents

No automatic migration occurs in Phase 0.

---

## Write-Time Schema Binding

Every write operation must explicitly specify:

* `schema_id`
* `schema_version`

Example write payload:

```json
{
  "schema_id": "users",
  "schema_version": "v1",
  "document": {
    "_id": "u123",
    "email": "user@example.com",
    "age": 30
  }
}