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

# Relationship definitions

> Model how profiles connect, including include keys, cardinalities, and relationship properties.

Relationship definitions capture the graph structure between resources managed by a data source. They describe which profiles can be connected, what each side of the relationship is called, and which properties travel with the connection itself.

## Core concepts

* **Include keys** — Human-readable aliases that expose relationships in APIs and partitions (for example `worksAt`, `staff`). They appear in `includes`, traversed properties, and search filters.
* **Cardinality** — Expresses how many instances can exist from each side (`0:1`, `0:*`, `1:1`, etc.). Cardinality guides data quality rules during ingestion.
* **Relationship properties** — Optional attributes stored alongside the link, such as effective periods or metadata about the connection.

<Note>
  Relationship definitions are scoped to a data source. When the same profiles exist in multiple sources, declare the relationship separately in each to keep provenance clean.
</Note>

## Structure of a relationship definition

```json theme={null}
{
  "key": "provider-facility",
  "from": {
    "profileKey": "provider",
    "includeKey": "worksAt",
    "cardinality": "0:*"
  },
  "to": {
    "profileKey": "facility",
    "includeKey": "staff",
    "cardinality": "0:*"
  },
  "properties": {
    "effective": {
      "type": "period"
    },
    "roles": {
      "type": "array",
      "items": {
        "type": "code"
      }
    }
  }
}
```

* `from` / `to` — Anchor each side to a profile, set the include key name, and declare cardinality.
* `properties` — Optional structure that uses the same [data types](/explanation/data-types/base-types) available to profiles.

## Designing effective relationships

* **Name includes for consumers** — Choose verbs or nouns that make sense in queries (`worksAt`, `offeredServices`) so search configurations are intuitive.
* **Validate business rules** — Cardinalities should mirror real-world constraints. Use ingestion tests to verify they reject invalid scenarios early.
* **Prepare for partitions** — Clearly defined include keys make it straightforward to configure [traversed properties](/explanation/partitions/mdm-partition#traversed-property-notation) and expose adjacent attributes in search.

## Keep exploring

<CardGroup cols={2}>
  <Card title="Data sources" icon="circle-stack" href="/explanation/sources/data-source">
    Understand how relationships inherit provenance from their parent source.
  </Card>

  <Card title="Profiles" icon="identification" href="/explanation/sources/profile">
    Revisit the schemas that relationships connect.
  </Card>

  <Card title="Partition traversal" icon="arrows-pointing-out" href="/explanation/partitions/mdm-partition#traversed-property-notation">
    Learn how relationship includes become searchable attributes.
  </Card>
</CardGroup>