Containers and hierarchy

Containers organize meaning.

They provide structure once concepts and relationships exist, without changing what those things mean.

Hierarchy in sprig is organizational, not semantic.

What a container is

A container groups related things.

It answers questions like:

• Where does this belong?
• What is this part of?
• How should this be presented or navigated?

A container does not:

• redefine meaning
• enforce behavior
• imply ownership
• change relationships

It only provides context.

Containers come after meaning

Containers are intentionally introduced after concepts and relationships.

This reflects how understanding usually develops:

1. You notice things.
2. You notice how they relate.
3. You decide how to organize them.

Sprig encourages this order.

You do not need containers to begin describing a universe.

Common containers

Sprig provides a small set of container types to help organize meaning:

• anthology
• series
• book
• chapter

These containers are structural conveniences. They exist to help humans navigate and understand large universes.

Aside from their descriptive role, containers behave the same way.

Declaring containers

Containers can be declared using nesting:

universe Greenhouse {
  series Gardening {
    book Plants { }
  }
}

Or using in to reference an existing parent:

series Gardening in Greenhouse { }

book Plants in Gardening { }

Both forms are equivalent.

The choice is about readability and organization, not meaning.

Containers do not define identity

An entity’s identity does not change when it moves between containers.

You can:

• reorganize hierarchy
• split or merge containers
• promote or flatten structure

…without redefining the underlying concepts.

This makes it safe to evolve structure as understanding grows.

Multiple levels of hierarchy

Containers may be nested to any depth:

anthology GardenSystems {
  series Greenhouse {
    book SeasonalCare {
      chapter Spring { }
    }
  }
}

Hierarchy should remain shallow where possible.

Deep nesting is allowed, but not required.

Containers and relationships are separate

Containers describe where things are grouped. Relationships describe how things are connected.

Neither replaces the other.

A relationship does not imply containment. Containment does not imply a relationship.

This separation is intentional.

When hierarchy becomes useful

Hierarchy becomes helpful when:

• a universe grows large
• navigation becomes difficult
• concepts need contextual grouping
• multiple audiences view the same universe differently

If hierarchy does not help, you can avoid it.

Ordering

Ordering controls how a container’s direct children are presented. It does not change meaning, identity, or relationships.

series OrderedSeries {
  ordering {
    FirstBook
    SecondBook
  }

  book FirstBook { }
}

book SecondBook in OrderedSeries { }

What comes next

Once hierarchy exists, names may begin to overlap.

Resolving ambiguity and expressing clear paths is handled through names and scoping, which builds on containers without changing meaning.