Relationship definitions

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.

Structure of a relationship definition

{
  "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 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