> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rafflesia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Identity & namespaces

> How the ontology gives every column a declared kind, namespace, and coordinate system so look-alike values never match by accident.

Everything else in the ontology rests on one idea: a column is not just a name
and a type, it carries a declared **kind**, and — where it matters — an
**identifier namespace** or a **coordinate system**. Two values are only the same
identity when those declarations agree. This is what lets a join be certified
instead of guessed.

The whole catalog lives in one declarative file, `ontology.v1.json`, which
versions the entity types, namespaces, coordinate systems, and relations
together. Its SHA-256 digest is folded into every query identity, so a query
cannot silently acquire different semantic validation.

## Column kinds

Every physical column declares a `value_kind`:

| Kind          | Meaning                                    |
| ------------- | ------------------------------------------ |
| `identifier`  | Names an entity; carries a namespace       |
| `coordinate`  | A position; carries a coordinate system    |
| `measurement` | A computed or observed value               |
| `provenance`  | Which dataset and version produced the row |

The kind is what stops two columns that both hold small integers from being
joined just because the numbers line up — a `coordinate` is never treated as a
`measurement`, and two coordinates in different systems never match.

## Identifier namespaces

A namespace records *which authority mints an identifier*. The ontology declares
seven, so the same protein addressed two ways is never compared as a raw string:

| Namespace                    | What it identifies                            |
| ---------------------------- | --------------------------------------------- |
| `pdb_entry`                  | A Protein Data Bank entry                     |
| `uniprot_accession`          | A UniProt protein accession                   |
| `structure_source_accession` | An accession from a declared structure source |
| `rafflesia_structure`        | A content-addressed Rafflesia structure id    |
| `source_record`              | An id assigned by an imported sequence source |
| `gene_ontology`              | A Gene Ontology term                          |
| `ncbi_taxonomy`              | An NCBI Taxonomy id                           |

There is deliberately no canonical sequence-identifier namespace. Sequence ids
reach the lake as whatever the source FASTA header or importer supplied, and
nothing resolves them to a common authority, so `source_sequence_records.sequence_id`
is declared `source_record` — a source-assigned id, not a Rafflesia-minted one.
The content address of a sequence is `sequence_sha256`. This is why the
sequence-search relations declare no identifier namespace on their query and
subject ids: those values are raw aligner output, and claiming otherwise would
license a join that silently returns wrong rows.

## Coordinate systems

A coordinate system records *what a position is measured against*. These are the
single most common way a biology query goes silently wrong, because they all look
like plain 1-based integers:

| Coordinate system                                         | What the number means                                                              |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `structure_residue_number`                                | Author (PDB) residue number in a modeled chain — may be non-contiguous or negative |
| `protein_sequence_position`                               | 1-based position along a protein's canonical sequence                              |
| `genome_reference_position`                               | 1-based coordinate on a named genomic reference                                    |
| `cdna_position`                                           | 1-based position along a coding cDNA/transcript                                    |
| `msa_column`                                              | 1-based column index in a multiple sequence alignment                              |
| `alignment_query_position` / `alignment_subject_position` | Residue position on the query / subject side of a pairwise alignment               |

A `structure_residue_number` and a `protein_sequence_position` can point at the
same residue, but they are **different coordinate systems**. Equating them
directly is the classic silently-wrong join — the ontology treats them as
distinct until a mapping relates them.

<Note>
  **Entities behind the columns**

  Columns are grounded in seventeen declared entity types — protein, structure,
  residue, sequence, variant, ligand, pocket, interface, taxon, and more — so a
  relation always knows which kind of thing each identifier and coordinate
  belongs to.
</Note>

## The rule in one sentence

> Two values refer to the same thing only when their kind, namespace, and
> coordinate system agree — or when the ontology declares a
> [relationship](/ontology/joins) that maps one to the other.
> Everything else stays distinct.

Next: [Lossy & range mappings](/ontology/equivalences) — how the
ontology relates identities that are the *same but imperfect* across sources.