---
summary: Namespaces, models, versions, variants, and files.
title: Resource model
path: concepts/resource-model
status: published
---

# Resource model

Everything in ScaiAtlas is addressed by a short hierarchy. Understanding it is 90%
of understanding the API.

```
namespace  →  model  →  version  →  variant  →  files
```

## Namespace

A **namespace** is an ownership and access-control boundary — one team, org, or
project. It owns models and holds the member roster.

| Field | Meaning |
|---|---|
| `name` | Unique slug, 2–64 chars, `^[a-z0-9][a-z0-9-]*[a-z0-9]$` (e.g. `poolnoodle`). |
| `display_name` | Human-friendly name. |
| `visibility` | `public` (anyone), `tenant` (same ScaiKey tenant), or `private` (explicit members only). |
| `owner_tenant_id` | The tenant that owns the namespace. |
| `model_count` | Number of models inside. |

Visibility drives default read access; per-member **roles** (owner → admin → member
→ viewer) grant finer permissions. See [Authentication](/docs/scaiatlas/concepts/authentication).

## Model

A **model** is a named product inside a namespace (`poolnoodle/noodletron`). It carries
metadata that's stable across versions.

| Field | Meaning |
|---|---|
| `name` | Slug, 1–128 chars, `^[a-zA-Z0-9][a-zA-Z0-9._-]*$`. |
| `full_name` | `namespace/name` (e.g. `poolnoodle/noodletron`). |
| `type` | One of the [model types](/docs/scaiatlas/reference/formats#model-types) — `llm`, `embedding`, `vision_language`, … (**required**). |
| `license` | SPDX-style license id, optional. |
| `capabilities` | Free-form JSON describing what the model can do. |
| `modalities` | `{input: [...], output: [...]}` modality lists. |
| `tags` | Free-form labels for search and filtering. |
| `version_count`, `download_count` | Rollup counters. |

## Version

A **version** is an immutable, semantically-versioned release of a model.

| Field | Meaning |
|---|---|
| `version` | Semver: `^\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?$` (`1.0.0`, `2.1.0-beta.1`). |
| `full_name` | `namespace/model:version`. |
| `format` | Primary format of the upload (`safetensors`, `gguf`, `onnx`, …). |
| `release_notes` | Human-readable notes for the release. |
| `requirements` | Free-form JSON of runtime requirements. |
| `files` | The file list, each with `path`, `size`, `checksum_sha256`. |
| `total_size`, `checksum_sha256` | Aggregate size and manifest checksum. |
| `status` | Lifecycle — see below. |
| `variant_count` | Number of format variants attached. |

### Version lifecycle (`status`)

```
uploading → processing → ready
                    ↘ failed
ready → deprecated → deleted
```

- `uploading` — created, files being pushed.
- `processing` — server finalizing/validating.
- `ready` — available for download. (The API also accepts the legacy value `available`, which is normalized to `ready`.)
- `deprecated` — still downloadable, discouraged.
- `deleted` — soft-deleted.
- `failed` — upload/finalize failed.

## Variant

A **variant** is an alternative representation of a version — typically a different
format or quantization. The original upload is the **primary** variant; conversions
(e.g. a GGUF Q4_K_M build of a safetensors original) are additional variants.

| Field | Meaning |
|---|---|
| `variant_name` | Slug, ≤64 chars (e.g. `gguf-q4_k_m`, `awq-int4`). |
| `format` | `safetensors`, `pytorch`, `gguf`, `onnx`, `other`. |
| `quantization` | Quantization label, if any (`Q4_K_M`, `int4`). |
| `is_primary` | `true` for the original upload. |
| `status` | `pending` → `converting` → `available` (or `failed`). |
| `files` | The variant's files with checksums. |

## Files

The leaf level. Every file records a `path` (relative within the version/variant),
a `size` in bytes, and a `checksum_sha256`. Downloads verify these checksums; the
registry never hands out files whose bytes don't match.

## Putting it together

```python
client.namespaces.get("poolnoodle")                       # namespace
client.models.get("poolnoodle", "noodletron")             # model
client.versions.get("poolnoodle", "noodletron", "1.0.0")  # version (use "latest" for newest)
client.variants.list("poolnoodle", "noodletron", "1.0.0") # variants
```

> **Tip:** anywhere a version string is expected, the literal `latest` resolves to
> the highest semantic version.