Submodels and Subgraphs
The submodels report analyzes independent capability-rooted subgraphs and the explicit couplings between them. It is useful when reviewing architecture boundaries, attachment contracts, refactors, and AI context collection.
What Is a Submodel
A submodel is a graph rooted at a capability with no capability parent. Reqvire resolves capability hierarchy, specified requirements, requirement hierarchy, refinements, verifications, attachments, and implementation evidence from that root.
- Capability hierarchy uses derive and derivedFrom between capabilities.
- Requirements enter the graph through specify and specifiedBy.
- Requirement hierarchy uses derive and derivedFrom between requirements.
- Full mode reports each capability root as a submodel.
- Scoped mode reports the first independent branch roots below a selected capability or requirement.
Why It Matters
Boundary review
Submodels reveal whether independent capability areas are cleanly separated or coupled through hidden hierarchy links.
Attachment validation
Cross-submodel dependencies should be explicit one-way attachment contracts rather than hierarchy relations that blur ownership.
Change impact
Change-impact analysis follows native relations and explicit attachments. Clear submodel boundaries make the resulting review scope easier to interpret and route.
AI context
Assistants can collect the right capability-rooted context without dragging unrelated model areas into the prompt.
Cross-Submodel Couplings
The report includes user-authored identifier relations from one requirement to another requirement when those requirements resolve to different capability-root ownership boundaries. Attachments are not counted in this coupling list; they are explicit dependency edges with their own attachment semantics.
Use lint with auditable output when you need cleanup hints for the hierarchical subset of those problems, such as cross-boundary requirement hierarchy links that should usually be modeled with ownership-preserving hierarchy or explicit attachments instead.
reqvire submodels reqvire submodels --json reqvire submodels --from "API Authentication" reqvire lint --auditable reqvire lint --auditable --json
Output Shape
Submodels
Capability-rooted entries with requirements, refinements, verification context, and summary counts.
Cross-Submodel Couplings
Explicit links that cross capability-root boundaries and require review.
Summary
Totals for submodels, requirements, and coupling counts. JSON exposes submodels, cross_submodel_couplings, and summary.
Modeling Rule of Thumb
Keep shared domain meaning in ontology and attach it to consuming capabilities. Keep reusable obligation detail as requirement-owned contracts and attach those contracts from consuming requirements. Use hierarchy only when ownership really belongs inside the same capability-rooted subgraph.