# 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"
}
```

### Internal ID

At the data layer of the Airalogy Platform, every Airalogy Protocol is automatically assigned an **internal ID** (called the **Protocol UUID**, `protocol_uuid`). This UUID is independent of Lab, Project, or other context—making it globally unique and stable even if the associated Lab or Project changes. Although this ID is not normally shown to end-users, it is used internally for global indexing. Its format is:

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

## 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>`       |
