How to use the Owns section

How-To Use spec sections Beginner 1061004HOWTO-1061004

HOWTO-1061004Use spec sectionsBeginner

This guide shows you how to use the Owns section in a SpecDD .sdd file.

Owns lists files, directories, symbols, concepts, or responsibilities governed by the spec. It is one of the most important sections for review because it tells humans and agents what the local contract is about.

Short answer

Use Owns to declare what the spec governs. List owned files or paths with explicit prefixes, and list owned concepts or responsibilities as clear prose. Only one spec should own a specific item at a given time. If Can modify is absent, Owns also acts as the modification boundary.

Syntax

Owns:
  ./itinerary.js
  ./itinerary.test.js
  Itinerary behavior for trip planning.

Rules:

Owns is a mixed-entry body section.
It may contain paths, symbols, key-value lines, or prose.
It must not have inline text after Owns:.
Body entries use two spaces.

Steps

1. List what the spec governs

For a simple local spec:

Owns:
  ./itinerary.js
  ./itinerary.test.js

For responsibility ownership:

Owns:
  Itinerary validation behavior.
  Itinerary ordering behavior.

Use both when helpful.

2. Keep ownership local

Good:

Owns:
  ./itinerary.js
  ./itinerary.test.js

Too broad:

Owns:
  ../trips/*
  ../destinations/*
  ../booking/*

Broad ownership makes review harder and can authorize changes that should belong to separate specs.

3. Separate ownership from read context

If a module needs another module for context, do not put the other module in Owns.

Use:

Owns:
  ./itinerary.js

Can read:
  ../storage/trip-storage.sdd

Can read and References do not grant edit permission.

4. Add `Can modify` when writable scope differs

If the spec owns a responsibility but only some files may change, add Can modify:

Owns:
  Itinerary validation behavior.
  ./itinerary.js
  ./itinerary.fixtures.json

Can modify:
  ./itinerary.js
  ./itinerary.test.js

When Can modify is present, use it for write authority.

5. Avoid overlapping ownership

Only one spec should own a specific item at a given time. If two specs appear to own the same file or behavior, clarify the boundary before implementation.

Common mistakes

Putting every imported file in Owns.
Letting two local specs own the same behavior.
Treating Owns as a human team-owner field.
Using broad globs to avoid deciding the real boundary.
Forgetting that Owns becomes the write boundary when Can modify is absent.

How to verify the result

The Owns section is clear when:

each entry belongs to the local subject
file paths are explicit
read-only context is not listed as owned
ownership does not overlap confusingly with another spec
reviewers can tell what the spec governs

Language reference

← Use spec sections guides