OpenParable
Skip to content
← Back to skills

Add Relationship

Development
add-relationship

Add Relationship is an Agent Skill for development published in the cartography-cncf/cartography repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Define a `CartographyRelSchema` (standard relationship), one-to-many edge, or `MatchLink` connecting existing nodes. Use when the user asks to add a relationship, link nodes, set a `RESOURCE` / `MEMBER_OF` / `ASSOCIATED_WITH` edge, share a node across modules, or model a composite node from two intel sources.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/cartography-cncf/cartography/blob/HEAD/.agents/skills/add-relationship/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/add-relationship, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

add-relationship

Add a relationship between Cartography nodes. Cover three flavours:

  1. Standard relationship on a node schema (other_relationships or sub_resource_relationship).
  2. One-to-many with PropertyRef(..., one_to_many=True).
  3. MatchLink for connecting two already-existing nodes — use sparingly.

Critical rules

  1. Prefer standard relationships in node schemas. MatchLinks have a real performance cost (extra MATCH reads).
  2. Use MatchLinks only when: the relationship data comes from a separate source and connects two existing node types, or the relationship needs rich metadata that doesn't belong on either node.
  3. MatchLink relationship properties must include lastupdated, _sub_resource_label, _sub_resource_id (all set_in_kwargs=True).
  4. Always implement cleanup. Standard rels: GraphJob.from_node_schema(). MatchLinks: GraphJob.from_matchlink().
  5. sub_resource_relationship always points to a tenant-like node. See the add-node-type skill.

Instructions

Step 1 — Standard relationship

Define rel properties (typically just lastupdated) and the relationship itself, then attach it to a node schema via sub_resource_relationship (tenant link) or other_relationships (business link).

from cartography.models.core.relationships import (
    CartographyRelSchema, CartographyRelProperties, LinkDirection,
    make_target_node_matcher, TargetNodeMatcher,
)


@dataclass(frozen=True)
class YourServiceTenantToUserRelProperties(CartographyRelProperties):
    lastupdated: PropertyRef = PropertyRef("lastupdated", set_in_kwargs=True)


@dataclass(frozen=True)
class YourServiceTenantToUserRel(CartographyRelSchema):
    target_node_label: str = "YourServiceTenant"
    target_node_matcher: TargetNodeMatcher = make_target_node_matcher({
        "id": PropertyRef("TENANT_ID", set_in_kwargs=True),
    })
    direction: LinkDirection = LinkDirection.OUTWARD
    rel_label: str = "RESOURCE"
    properties: YourServiceTenantToUserRelProperties = YourServiceTenantToUserRelProperties()

Step 2 — Pick a direction

  • LinkDirection.OUTWARD: (:Source)-[:REL]->(:Target)
  • LinkDirection.INWARD: (:Source)<-[:REL]-(:Target)

Sub-resource relationships use INWARD ((:Tenant)-[:RESOURCE]->(:Resource) from the tenant's POV is INWARD for the resource side).

Step 3 — One-to-many

Flatten target IDs in transform() and use one_to_many=True:

# transform
{"id": "rtb-123", "subnet_ids": ["subnet-abc", "subnet-def"]}

# rel
@dataclass(frozen=True)
class RouteTableToSubnetRel(CartographyRelSchema):
    target_node_label: str = "AWSEC2Subnet"
    target_node_matcher: TargetNodeMatcher = make_target_node_matcher({
        "subnet_id": PropertyRef("subnet_ids", one_to_many=True),
    })
    direction: LinkDirection = LinkDirection.OUTWARD
    rel_label: str = "ASSOCIATED_WITH"
    properties: RouteTableToSubnetRelProperties = RouteTableToSubnetRelProperties()

Cartography expands one_to_many into one edge per ID in the list.

Step 4 — Decide whether you need a MatchLink

Use a MatchLink when:

  • The relationship comes from a separate API call / data source that maps two already-loaded node types.
  • The relationship needs rich metadata (e.g. CVE remediation details, fix version, file path) that doesn't belong on either node.

Don't use MatchLinks for:

  • Standard parent-child relationships (use other_relationships).
  • Simple one-to-many (use one_to_many=True).
  • Cases where the relationship can be defined inside the node schema.
  • Performance-critical paths.

Step 5 — MatchLink schema

from cartography.models.core.relationships import (
    CartographyRelSchema, CartographyRelProperties, LinkDirection,
    make_target_node_matcher, TargetNodeMatcher,
    make_source_node_matcher, SourceNodeMatcher,
)


@dataclass(frozen=True)
class RoleAssignmentRelProperties(CartographyRelProperties):
    lastupdated: PropertyRef = PropertyRef("lastupdated", set_in_kwargs=True)
    _sub_resource_label: PropertyRef = PropertyRef("_sub_resource_label", set_in_kwargs=True)
    _sub_resource_id: PropertyRef = PropertyRef("_sub_resource_id", set_in_kwargs=True)


@dataclass(frozen=True)
class RoleAssignmentAllowedByMatchLink(CartographyRelSchema):
    target_node_label: str = "AWSRole"
    target_node_matcher: TargetNodeMatcher = make_target_node_matcher({
        "arn": PropertyRef("RoleArn"),
    })
    source_node_label: str = "AWSSSOUser"
    source_node_matcher: SourceNodeMatcher = make_source_node_matcher({
        "id": PropertyRef("UserId"),
    })
    direction: LinkDirection = LinkDirection.OUTWARD
    rel_label: str = "ALLOWED_BY"
    properties: RoleAssignmentRelProperties = RoleAssignmentRelProperties()

Step 6 — Load + cleanup MatchLinks

load_matchlinks(
    neo4j_session,
    RoleAssignmentAllowedByMatchLink(),
    role_assignments,
    lastupdated=update_tag,
    _sub_resource_label="AWSAccount",
    _sub_resource_id=aws_account_id,
)


def cleanup(neo4j_session, common_job_parameters):
    GraphJob.from_node_schema(YourNodeSchema(), common_job_parameters).run(neo4j_session)
    GraphJob.from_matchlink(
        YourMatchLinkSchema(),
        "AWSAccount",                      # _sub_resource_label
        common_job_parameters["AWS_ID"],   # _sub_resource_id
        common_job_parameters["UPDATE_TAG"],
    ).run(neo4j_session)

For richer MatchLink scenarios (rich rel properties, optional MatchLinkSubResource scoping, multi-module composite nodes), see references/matchlinks.md and references/multi-module-patterns.md.

Common issues

  • Relationship not created — the target node didn't exist when the rel was loaded. Load parent nodes first.
  • Matcher property mismatch — target_node_matcher keys must match the target node's property names (e.g. id, arn).
  • MatchLink misses — both source and target nodes must already exist before load_matchlinks().
  • Cleanup deletes too much — confirm _sub_resource_id and UPDATE_TAG in common_job_parameters.

For the full troubleshooting list, see the troubleshooting skill.

References (load on demand)

  • references/matchlinks.md — MatchLink performance impact, rich-property example (Inspector findings), MatchLinkSubResource scoping.
  • references/multi-module-patterns.md — simple-relationship vs composite-node patterns when multiple intel modules touch the same node label.