Relationships

Relationships describe how things are connected.

They express meaning, not behavior. They do not imply hierarchy, containment, or execution.

A relationship simply says: this is related to that.

Declaring a relationship

A relationship is declared using a relates block:

relates TomatoPlant and WateringCan { }

This states that TomatoPlant and WateringCan are meaningfully connected in this universe.

No direction or behavior is implied unless you choose to describe it.

Relationships do not require structure

Relationships can be declared as soon as concepts exist.

You do not need:

• containers
• hierarchy
• categories
• or paths

For example:

universe Greenhouse {
  concept TomatoPlant { }
  concept WateringCan { }

  relates TomatoPlant and WateringCan { }
}

Structure can come later. The relationship remains valid.

Adding meaning

Relationships can include a shared description:

relates TomatoPlant and WateringCan {
  describe {
    Tomato plants can be watered by watering cans.
  }
}

Descriptions exist for humans. They do not enforce behavior.

Perspectives

Sometimes it helps to describe the relationship from the perspective of one member.

You can do that using from blocks.

Each from block may add:

• relationship labels (as strings)
• and an optional description from that perspective

For example:

relates TomatoPlant and WateringCan {
  from TomatoPlant {
    relationships { 'is watered by' }

    describe {
      Tomato plants can be watered by watering cans.
    }
  }

  from WateringCan {
    relationships { 'waters' }
    describe {
      Watering cans are used to water tomato plants.
    }
  }
}

Perspective blocks do not change what exists in the universe. They clarify how you talk about the connection. They add language, not structure.

Multiple relationship labels

The relationships block is always plural, even when expressing a single relationship.

If a concept has multiple relationships, they can be expressed as a list -

relates Seeds and Plants {
  from Seeds {
    relationships {
      'become'
      'are produced by'
    }
  }
}

Symmetry and direction

A relationship connects two entities regardless of whether you provide perspective.

• Without from, the relationship is a simple connection.
• With from, you can describe directionality as language, from each side.

Sprig does not infer direction. If direction matters, you express it explicitly using perspective.

Relationships vs containers

Relationships describe connections. Containers describe organization.

A relationship does not place one thing inside another. A container does not imply a relationship.

These concerns are intentionally separate.

Declared relationships

In addition to relates blocks, relationships may also be declared explicitly.

Declared relationships provide shared vocabulary and optional description that can be reused throughout a universe.

They are descriptive only, and do not introduce enforcement.

Relationship block

The relationship block declares a relationship by name.

Relationships may be symmetric:

relationship friend {
  describe {
    Teams have a peer relationship with no hierarchy.
  }
}

Or directional, with two linguistic sides:

relationship owns and ownedBy {
  describe {
    Ownership expresses long-term responsibility.
  }

  from ownedBy {
    label { 'owned by' }
  }
}

In both cases, the relationship itself is bidirectional. Direction exists only to support natural language.

Relationships block

Entities may declare local relationships using a relationships block.

team FrontendTeam {
  relationships {
    hasMember {
      Bryan
      Michael
    }

    owns {
      PaymentsApi
      WebApp
    }
  }
}

Each entry describes how the current entity relates to others.

Individual relationship instances may include additional description:

relationships {
  hasMember {
    Matt {
      describe {
        Matt is temporarily embedded with the team.
      }
    }
  }
}

Relationship intent

Declared relationships exist to:

• improve readability
• share meaning
• support projections and alternative views

They do not replace relates, and they do not constrain behavior.

What comes next

Once relationships exist, you may want to group and organize entities.

That organization is expressed using containers and hierarchy, which introduce structure without changing meaning.