Skip to content

Commit

Permalink
update relationship docs to add some information about default value
Browse files Browse the repository at this point in the history
  • Loading branch information
BeArchiTek committed Dec 23, 2024
1 parent 4d32ce6 commit 79549d7
Showing 1 changed file with 52 additions and 34 deletions.
86 changes: 52 additions & 34 deletions docs/docs/topics/schema.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -254,26 +254,32 @@ Direction and identifier both constitute critical qualities for good relationshi

The **direction** attribute defines the flow of the relationship:

- **Bidirectional**: Supports traversal in both directions.
- **Bidirectional**: Supports traversal in both directions. This is the **default value** if no direction is indicated.
- **Outbound**: Defines a relationship that runs from the source node to the target node.
- **Inbound**: Defines a relationship that flows from the target node to the source node.

Even if a relationship is `bidirectional`, you still have to create it on both nodes to allow you to easily traverse them in both directions.

For detailed information, see the [Relationship Reference Guide](/reference/schema/relationship#direction)

##### Identifier

To maintain consistent traversal, the **identifier** serves as the relationship's unique key and must match on both ends.
If no identifier is provided, one will be generated automatically. It is encouraged to establish distinct ones for clarity and maintenance.

If no identifier is specified, one will be automatically generated in the format `<node_kind_a>__<node_kind_z>`.
Example: `infraautonomoussystem__organizationgeneric`

For detailed information, see the [Relationship Reference Guide](/reference/schema/relationship#identifier)

##### Examples

:::info Example 1: Bidirectional Relationship with `device__interfaces`
<details>
<summary>Example 1: Bidirectional Relationship with `device__interfaces`</summary>

Here's an example schema that uses the identifier `device__interfaces` in a bidirectional connection to ensure that devices and interfaces can refer to each other seamlessly.

```yaml
```yaml {6,15} showLineNumbers
- name: Interface
namespace: Infra
relationships:
Expand All @@ -294,62 +300,74 @@ Here's an example schema that uses the identifier `device__interfaces` in a bidi
kind: Component
```

:::
</details>

:::info Example 2: Relationships in InfraBGPGroup
<details>
<summary>Example 2: Relationships in InfraBGPGroup</summary>

`InfraBGPGroup` has two relationships with the same node, `InfraAutonomousSystem`. To avoid issues with the auto-generated identifiers, we should specifically specify the ones we want.
By including `bgppeergroup__local_as` and `bgppeergroup__remote_as`, we can clearly represent each relationship role.

```yaml
```yaml {5-6,11-12} showLineNumbers
- name: BGPGroup
namespace: Infra
relationships:
- name: local_as
identifier: bgppeergroup__local_as
identifier: "bgppeergroup__local_as"
peer: InfraAutonomousSystem
optional: true
cardinality: one
kind: Attribute
- name: remote_as
identifier: bgppeergroup__remote_as
identifier: "bgppeergroup__remote_as"
peer: InfraAutonomousSystem
optional: true
cardinality: one
kind: Attribute
```

:::
</details>

:::info Example 3: Reflexive Relationships in IpamVLAN
<details>
<summary>info Example 3: Reflexive Relationships in Employee</summary>

This example shows how direction (`inbound` for `svlan` and `outbound` for `cvlan`) distinguishes connections within the same node type `ipamVLAN`.
The `vlan__qinq` identifier connects the `svlan` and `cvlan` relationships while keeping their separate functions.
Because both sides of the relationship have the same `Kind`, we must avoid the default `bidrectional` assumption, therefore we have to specify a direction.
This example demonstrates how direction (`inbound` for `leader` and `outbound` for `team_members`) distinguishes connections within the same node type `OrganizationEmployee`.
The `employee_team_relationship` identifier connects the `leader` and `team_members` relationships while maintaining their distinct roles.
Since both sides of the relationship share the same `Kind`, we must avoid the default `bidrectional` assumption, therefore we have to specify a direction.

```yaml
- name: VLAN
namespace: Ipam
relationships:
- name: svlan
label: Supplier VLAN
peer: IpamVLAN
optional: true
direction: inbound
identifier: vlan__qinq
cardinality: one
kind: Attribute
- name: cvlan
label: Customer VLAN(s)
peer: IpamVLAN
optional: true
direction: outbound
identifier: vlan__qinq
cardinality: many
kind: Attribute
```yaml {15-16,24-25} showLineNumbers
nodes:
- name: Employee
namespace: Organization
description: "An employee in the organization with leadership and team relationships."
label: "Employee"
attributes:
- name: name
kind: Text
unique: true
description: "Name of the employee."
relationships:
- name: leader
label: Leader
peer: OrganizationEmployee
direction: inbound
identifier: "employee_team_relationship"
cardinality: one
kind: Attribute
optional: true
description: "The leader guiding this team member."
- name: team_members
label: Team Members
peer: OrganizationEmployee
direction: outbound
identifier: "employee_team_relationship"
cardinality: many
kind: Attribute
optional: true
description: "Employees who are part of this leader's team."
````
:::
</details>
<!-- vale off -->
### Uniqueness Constraints
Expand Down

0 comments on commit 79549d7

Please sign in to comment.