Skip to main content
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.
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.

​
Structure of a relationship definition

{
  "key": "provider-facility",
  "from": {
    "profileKey": "provider",
    "includeKey": "worksAt",
    "cardinality": "0:*"
  },
  "to": {
    "profileKey": "facility",
    "includeKey": "staff",
    "cardinality": "0:*"
  },
  "data": {
    "effective": {
      "type": "period"
    },
    "roles": {
      "type": "array",
      "items": {
        "type": "code"
      }
    }
  }
}
  • key — Stable identifier referenced by ingestion APIs and downstream partitions.
  • 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 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 and expose adjacent attributes in search.

​
Keep exploring

Data sources

Understand how relationships inherit provenance from their parent source.

Profiles

Revisit the schemas that relationships connect.

Partition traversal

Learn how relationship includes become searchable attributes.