Requirements and Capabilities

Reqvire models requirements inside a semantic engineering graph. Capabilities define stable system abilities, requirements define implementable obligations, ontology defines reusable meaning, and verification and implementation links prove the model is real.

Conceptual Split

Capability - a coherent operational, product, business, regulatory, or system ability that gives scope and language to a model area.

Requirement - a testable obligation that specifies a capability and can be verified, satisfied, decomposed, and refined.

Ontology - reusable domain and model meaning: classes, properties, vocabulary, restrictions, labels, and semantic relationships.

Feature - a product or roadmap term that may be described inside capability content, but is not the primary traceability node.

Capabilities

A capability is not a weaker requirement. It answers why a system area exists, what domain context it uses, who owns the scope, and which requirements belong under that ability. Capabilities can be directly verified, but implementation coverage rolls up from their specifying requirements.

Use capability hierarchy only between capability elements with derive or derivedFrom.
Use Concept References when capability prose should bind readable labels to ontology terms.
Create child capabilities when ownership, lifecycle, verification, stakeholder scope, architecture impact, or requirement clusters differ.
Do not create one universal top capability that hides all submodel boundaries.

### API Authentication

API authentication capability and access-token domain context.

#### Metadata
  * type: capability
  * status: review
  * priority: high
  * risk: medium
  * owner: Identity Team

#### Concept References
  * Access Token: https://example.org/ontology/auth#AccessToken

#### Relations
  * specifiedBy: [API Access Token Validation](AuthRequirements.md#api-access-token-validation)

Requirements

A requirement is the obligation anchor. It should say what the system shall do, under what condition or scope, what implementation or evidence can satisfy it, and what verification proves it.

Top-level ownership

A top-level requirement uses specify to resolve to exactly one owning capability.

Requirement hierarchy

Child requirements use derive or derivedFrom inside the requirement family and inherit ownership from their parent requirement.

Implementation evidence

Requirements use satisfiedBy to link code, tests, generated reports, proof outputs, or other implementation evidence.

Verification evidence

Requirements use verifiedBy to link test, proof, analysis, inspection, or demonstration verifications.

### API Access Token Validation

The system shall reject API requests whose access token is invalid.

#### Metadata
  * type: requirement
  * status: review
  * priority: high
  * risk: medium
  * owner: Identity Team

#### Concept References
  * Access Token: auth:AccessToken

#### Relations
  * specify: [API Authentication](Auth.md#api-authentication)
  * verifiedBy: [Access Token Contract Test](../Verifications/Auth.md#access-token-contract-test)
  * satisfiedBy: [auth_middleware.rs](../../src/auth_middleware.rs)

Requirement-Owned Refinements and Semantic Contracts

Refinements carry detailed engineering contracts for a requirement. Non-semantic-contract refinements are owned through refine or refinedBy and should not author governance metadata. Semantic contracts are separate ontology-plane elements that constrain requirements through constrainedBy and constrain, and use ontology through use and usedBy.

source captures stakeholder, regulatory, policy, contractual, or external source material.
specification, constraint, behavior, state, and input-output refinements carry detailed contract content.
semantic-contract is a reusable SHACL profile over explicitly used ontology and must include Shapes.

# Element

## Metadata
  * type: specification

## Relations
  * refine: [API Access Token Validation](AuthRequirements.md#api-access-token-validation)

## Access Token Validation Specification

The access-token validator checks the token issuer, subject, audience, expiry,
and signature before the request reaches protected application logic.

Attachments as Contracts

Attachments make cross-boundary requirement contracts explicit. Ontology term usage is modeled with concept references. A requirement can import a one-way contract dependency from a compatible requirement-owned non-semantic-contract refinement in another subgraph; semantic-contract dependencies use constrainedBy/constrain and use/usedBy instead.

Concept references

Capabilities, requirements, refinements, and verifications bind prose to ontology terms with Concept References.

Requirement attachments

Requirements attach specifications, constraints, behaviors, states, and input-output refinements owned by requirement subgraphs. Semantic contracts are linked through constrainedBy/constrain.

One-way flow

The attaching requirement declares that its subgraph must fulfill the attached contract. Reciprocal cross-submodel attachment is rejected because it hides the intended dependency direction.

Review impact

Verifications provide evidence, while traces and change-impact reports show which contracts, child requirements, refinements, and implementation artifacts need review after changes.

### API Consumer Token Handling

The consumer service shall fulfill the shared access-token validation behavior.

#### Metadata
  * type: requirement

#### Attachments
  * [Access Token Validation Behavior](../Identity/AuthBehaviors.md#access-token-validation-behavior)

#### Relations
  * specify: [API Consumer](Consumer.md#api-consumer)

Governance Metadata

Governance metadata belongs on capability and requirement elements. It supports planning, ownership routing, readiness review, risk review, search filters, and assistant task generation.

Key	Values	Default
`status`	draft, review, approved	approved
`priority`	low, medium, high, critical	medium
`risk`	low, medium, high, critical	low
`owner`	free-form person, role, team, or subsystem	unassigned

Capabilities inherit missing governance fields from parent capabilities.
Top-level requirements inherit missing governance fields from their owning capability.
Child requirements inherit missing fields from the nearest parent requirement.
Refinements and verifications must not declare status, priority, risk, or owner directly.

reqvire search --filter-status review
reqvire search --filter-priority high,critical
reqvire search --filter-risk high,critical --json
reqvire search --filter-owner "Identity Team"

Model Containment

Folders and files are physical containment only. They should make the model easy to browse, but authoritative semantics come from metadata, relations, and attachments.

requirements/
  Product/
    Collaboration/
      Collaboration.md
      CollaborationRequirements.md
      CollaborationBehaviors.md
      Architecture/
        CollaborationServiceSpecifications.md
  Platform/
    Identity/
      Identity.md
      IdentityRequirements.md
  Ontologies/
    Collaboration.md
    Identity.md
  Verifications/
    Collaboration/
      CollaborationVerifications.md
    Identity/
      IdentityVerifications.md

Capabilities holds capability-rooted subgraphs with child capabilities, specifying requirements, and requirement-owned refinements.
Ontologies holds reusable semantic vocabulary referenced by model elements instead of nested into unrelated capability files.
Verifications holds verification elements grouped by domain and linked through verify or verifiedBy.
Folder names are guidance, not schema. Reqvire validates element metadata and graph relations.