# Airalogy IDs

This document describes the identifier (ID) system used across the Airalogy platform.

## Airalogy Objects

Data in Airalogy is organised as **objects**. Key object types include:

- **Airalogy Protocol**
- **Airalogy Record**
- **Airalogy User**: a registered platform user
- **Airalogy Lab**: a laboratory workspace
- **Airalogy Project**: a project within a lab
- **Airalogy File**: any file uploaded to Airalogy

## General ID Format

Every object has a globally unique **Airalogy ID** with the form:

```txt
airalogy.id.<type>.<…>
```

| Segment | Meaning |
| - | -  |
| `airalogy.id` | Constant prefix denoting an Airalogy ID |
| `<type>` | Object type namespace (`user`, `lab`, `project`, `protocol`, `record`, etc.) |
| `…` | Type-specific content (UUIDs, names, versions, etc.) |

This structure prevents collisions by namespaces.

### `snake_case` Naming Rules

Certain IDs allow user-defined segments written in `snake_case`, which **must**:

1. Contain only lowercase letters `a–z`, digits `0–9`, and underscores `_`
2. Start with a letter
3. Never have consecutive underscores (`__`)
4. Be ≤ 32 characters long

   > (A UUID is 32 hex characters—36 with hyphens—so capping at 32 keeps overall length manageable.)

## User, Lab, and Project IDs

These IDs follow the `snake_case` rules.

| Scope | Uniqueness | ID Format |
| - | - | - |
| **User** | Global | `airalogy.id.user.<user_id>` |
| **Lab** | Global | `airalogy.id.lab.<lab_id>` |
| **Project** | Unique within its lab | `<project_id>` |

To globally address a project uniquely you must supply both its lab ID and project ID:

```txt
airalogy.id.lab.<lab_id>.project.<project_id>
```

### Short IDs vs Airalogy IDs

- Fields named like `<type>_id` store the **short ID** relevant within that namespace:

  ```json
  {
    "lab_id": "lab_demo",
    "project_id": "project_demo"
  }
  ```

- Fields named `airalogy_<type>_id` store the **full Airalogy ID**, which is globally unique and self-describing:

  ```json
  {
    "airalogy_lab_id": "airalogy.id.lab.lab_demo",
    "airalogy_project_id": "airalogy.id.lab.lab_demo.project.project_demo"
  }
  ```

## 4 · Airalogy Protocol ID (Global)

Protocols share an ID with their **protocol repository**:

```txt
airalogy.id.lab.<lab_id>.project.<project_id>.protocol.<protocol_id>.v.<protocol_version>
```

Example:

```txt
airalogy.id.lab.lab_demo.project.project_demo.protocol.protocol_demo.v.0.0.1
```

| Segment | Notes |
| - | - |
| `<protocol_id>` | An ID following `snake_case` rules |
| `<protocol_version>` | Semantic version `x.y.z` (`x`, `y`, `z` = non-negative integers) |

### Database Optimization

Protocols are typically stored with five fields:

```json
{
  "airalogy_protocol_id": "airalogy.id.lab.lab_demo.project.project_demo.protocol.protocol_demo.v.0.0.1",
  "lab_id": "lab_demo",
  "project_id": "project_demo",
  "protocol_id": "protocol_demo",
  "protocol_version": "0.0.1"
}
```

### 4.2 · Internal Protocol ID

Internally, each protocol also receives a UUID-based ID:

```txt
airalogy.id.protocol.<uuid>.v.<protocol_version>
```

This ID is not exposed to end-users.

## Airalogy Record ID (Global)

Records are generated by applying a protocol, so their IDs are wholly system-assigned:

```txt
airalogy.id.record.<record_uuid>.v.<record_version>
```

- `<record_uuid>` A UUID generated by Airalogy
- `<record_version>` Positive integer, auto-incremented on edits

Example:

```txt
airalogy.id.record.123e4567-e89b-12d3-a456-426614174000.v.1
```

### Database Optimization

```json
{
  "airalogy_record_id": "airalogy.id.record.123e4567-e89b-12d3-a456-426614174000.v.1",
  "record_id": "123e4567-e89b-12d3-a456-426614174000",
  "record_version": 1
}
```

## Airalogy File ID (Global)

```txt
airalogy.id.file.<uuid>.<file_extension>
```

Including the extension enforces format constraints and ensures a downloaded file can be opened immediately.

Supported extensions include:

- **Images**: `png`, `jpg`, `svg`, `webp`, `tiff`
- **Video**: `mp4`
- **Audio**: `mp3`
- **Documents / data**: `txt`, `md`, `remd`, `csv`, `tsv`, `json`, `yml`, `pdf`, `docx`, `xlsx`, `pptx`

## Other Global IDs

| Object           | Format                          |
| ---------------- | ------------------------------- |
| **Discussion**   | `airalogy.id.discussion.<uuid>` |
| **Chat Session** | `airalogy.id.chat.<uuid>`       |
