Associations

Associations are loose connections between entities that indicate a relationship without implying dependency. They answer the question: “What is related to this, even if it doesn’t depend on it?”

What Are Associations?

An association is a bidirectional relationship between two entities that indicates they are related in some way, but one does not require the other to function. Unlike dependencies, associations do not imply that one entity will be affected if the other fails or changes.

For example:

The Q4 Migration Project is associated with the Billing API and Auth Service (the project involves these services, but the project doesn’t depend on them to exist)
The Deployment Runbook is associated with the CI/CD Platform (the runbook documents the platform, but the runbook doesn’t require the platform to function)
Alex Johnson is associated with the Q4 Migration Project (Alex is working on the project, but Alex doesn’t depend on the project)

Associations are flexible and can connect any type of entity to any other type. They provide context without creating hard requirements.

Associations vs Dependencies

The key difference between associations and dependencies is the strength of the relationship:

Dependencies:

Directional (A depends on B)
Imply a hard requirement
Used for impact analysis
If B fails, A is affected
Example: “Billing API depends on PostgreSQL”

Associations:

Bidirectional (A is associated with B, and B is associated with A)
Imply a loose connection
Used for discovery and context
If B fails, A is not affected
Example: “Q4 Migration Project is associated with Billing API”

When to use dependencies:

Service A requires Service B to function
If Service B goes down, Service A will fail
You need to track impact chains for incident response

When to use associations:

Two entities are related but independent
You want to help people discover related items
The relationship is contextual, not structural
You want to group entities without implying dependency

Examples of Good Associations

Projects and services:

A project is associated with the services it modifies or creates
The project doesn’t depend on the services (the project is temporary, the services are permanent)
But the association helps people understand what the project involves

Documentation and landmarks:

A runbook is associated with the service it documents
The runbook doesn’t depend on the service (the runbook is just text)
But the association helps people find relevant documentation

People and projects:

A person is associated with the projects they’re working on
The person doesn’t depend on the project (the person exists independently)
But the association helps people understand who’s involved

Services and tools:

A service is associated with the monitoring tools used to track it
The service doesn’t depend on the monitoring tool (the service runs without it)
But the association helps people find the right dashboards

Teams and landmarks:

A team is associated with the landmarks they frequently work with
The team doesn’t own all of them (ownership is a separate relationship)
But the association provides context about the team’s focus areas

How to Create an Association

Associations are created during entity creation or editing. In the entity wizard, Step 4 (Organization) includes a Relationships section.

To create an association:

Open the entity you want to define associations for
Click Edit to open the editing wizard
Navigate to Step 4 (Organization)
In the Relationships section, find the Related To field
Search for and select the entity (or entities) this entity is related to
Click Save to apply the changes

You can add multiple associations to a single entity. For example, the Q4 Migration Project might be associated with the Billing API, Auth Service, and PostgreSQL.

To remove an association:

Open the entity’s detail drawer
Click the Relationships tab
Find the association you want to remove
Click the trash icon next to the relationship
Confirm the deletion

Viewing Associations

Associations are visible in multiple places throughout Legend:

Entity card: The entity card shows relationship indicators, including “related to” counts. This badge gives you a quick overview of how many associations exist.

Detail drawer: The Relationships tab in the detail drawer lists all associations. You can see what the entity is related to. Click any related entity to navigate to its detail view.

Topology explorer: The topology graph visualizes associations as edges between nodes. Unlike dependencies (which are directional), associations are shown as bidirectional connections.

Search results: When you search for an entity, the search results include related entities. Associations are shown as part of the relationship graph, helping you discover connected items.

Bidirectional Nature

Associations are bidirectional. When entity A is associated with entity B:

A shows B in its “related to” list
B shows A in its “related to” list
Both entities are updated automatically

You only need to create the association once. Legend maintains both sides of the relationship.

Example: If you create an association between “Q4 Migration Project” and “Billing API”:

The Q4 Migration Project’s detail drawer shows “Billing API” in its related entities
The Billing API’s detail drawer shows “Q4 Migration Project” in its related entities
Both entity cards show the association count

Best Practices for Associations

Use associations for context, not structure: Associations should help people discover related items, not define system architecture. Use dependencies for structural relationships.

Be selective: Don’t associate everything with everything. Associations should be meaningful and help people find relevant information. Too many associations create noise.

Document the relationship: If the association is not obvious, add a note in the documentation explaining why the entities are related. This helps future maintainers understand the connection.

Review periodically: Associations can become outdated as projects complete, services change, or people move to different teams. Periodically review associations to ensure they’re still relevant.

Use associations to bridge gaps: Associations are useful for connecting entities that don’t fit into other relationship types. If two entities are related but don’t have a dependency, ownership, or membership relationship, an association is appropriate.

Associations in the Topology Explorer

The topology explorer provides a visual representation of associations. When you explore an entity, the graph shows:

The entity at the center
All entities it’s associated with (bidirectional edges)
The depth of the association chain (how many levels deep to traverse)

Associations are displayed differently from dependencies in the topology graph. Dependencies use directional arrows; associations use simple lines. This visual distinction helps you understand the nature of each relationship.

Navigating associations in topology:

Click any node to navigate to that entity
Use breadcrumbs to trace your exploration path
Zoom and pan to explore large association graphs
Use the minimap to orient yourself in complex graphs

Associations Across Entity Types

Associations can connect any entity type to any other entity type:

Landmark to Landmark: Services related to each other, projects and services, documentation and landmarks
Landmark to Person: Services and the people who work on them, projects and team members
Landmark to Team: Services and teams that frequently interact with them
Person to Person: Colleagues who work together, mentors and mentees
Person to Team: People and teams they’re affiliated with (but not formal members of)
Team to Team: Teams that collaborate frequently, parent and child teams (though hierarchy is a separate concept)

The flexibility of associations makes them useful for capturing a wide range of relationships that don’t fit into other categories.

Dependencies

Ownership

Topology Explorer