From 79549d73595e84434ccd431716616f73c6aaf1c6 Mon Sep 17 00:00:00 2001 From: Bearchitek Date: Mon, 23 Dec 2024 15:30:36 +0100 Subject: [PATCH] update relationship docs to add some information about default value --- docs/docs/topics/schema.mdx | 86 ++++++++++++++++++++++--------------- 1 file changed, 52 insertions(+), 34 deletions(-) diff --git a/docs/docs/topics/schema.mdx b/docs/docs/topics/schema.mdx index b62f113953..fedb1c7700 100644 --- a/docs/docs/topics/schema.mdx +++ b/docs/docs/topics/schema.mdx @@ -254,10 +254,12 @@ 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 @@ -265,15 +267,19 @@ For detailed information, see the [Relationship Reference Guide](/reference/sche 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 `__`. +Example: `infraautonomoussystem__organizationgeneric` + For detailed information, see the [Relationship Reference Guide](/reference/schema/relationship#identifier) ##### Examples -:::info Example 1: Bidirectional Relationship with `device__interfaces` +
+ Example 1: Bidirectional Relationship with `device__interfaces` 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: @@ -294,62 +300,74 @@ Here's an example schema that uses the identifier `device__interfaces` in a bidi kind: Component ``` -::: +
-:::info Example 2: Relationships in InfraBGPGroup +
+ Example 2: Relationships in InfraBGPGroup `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 ``` -::: +
-:::info Example 3: Reflexive Relationships in IpamVLAN +
+ info Example 3: Reflexive Relationships in Employee -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." ```` -::: +
### Uniqueness Constraints