Ontologies

Ontologies are Reqvire's reusable semantic vocabulary layer. They define domain meaning, model terms, relationships, and semantic rules as first-class OWL/Turtle content with explicit boundary metadata.

What Belongs Here

Reusable meaning

Use ontology when content says that X is a Y, X has property Z, X relates to Y, or a domain term has stable meaning across requirements.

Semantic vocabulary

Ontology elements define classes, object properties, datatype properties, subclass relations, domain and range, restrictions, labels, comments, inverse properties, and property chains.

Not implementation behavior

Commands, fields, URI patterns, workflow steps, file paths, emitted outputs, and reject/write behavior belong in specifications, behaviors, states, input-output contracts, or semantic contracts.

Reachability Model

Reqvire keeps ontology orthogonal to capability and requirement hierarchy. Non-ontology elements reference ontology terms explicitly; semantic contracts use ontology through use relations.

Author shared ontology elements under the ontology plane, commonly requirements/Ontologies.
Capabilities, requirements, refinements, verification objectives, and concrete verifications use Concept References for ontology term bindings.
Semantic contracts do not author Concept References; they use ontology through explicit use relations.
Requirement attachments are for reusable requirement-owned non-semantic-contract refinements.
Ontology hierarchy uses derive or derivedFrom only with other ontology elements.
Ontology elements do not author attachments.

Ontology Element

An ontology element carries one #### Ontology Turtle block.

### Access Token Ontology

Defines access token domain meaning.

#### Metadata
  * type: ontology
  * ontology_base: https://example.org/ontology/auth
  * ontology_prefix: auth

#### Ontology
```turtle
@prefix auth: <https://example.org/ontology/auth#> .
@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .

<https://example.org/ontology/auth> a owl:Ontology .

auth:AccessToken a owl:Class ;
  rdfs:label "Access token" ;
  rdfs:comment "Bearer credential presented to access protected resources." .

auth:subject a owl:ObjectProperty ;
  rdfs:domain auth:AccessToken .
```

Concept References

Concept references let non-ontology prose stay readable while binding terms to declared ontology CURIEs or IRIs. The referenced term must be declared by an ontology element in the model.

### API Authentication

API authentication capability.

#### Metadata
  * type: capability

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

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

---

### API Access Token Validation
The system shall reject API requests whose access token is invalid.

#### Metadata
  * type: requirement

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

#### Relations
  * specify: [API Authentication](#api-authentication)

Semantic Contracts

Semantic contracts are reusable SHACL profiles that explicitly use ontology and constrain requirements. They make obligations machine-checkable without redefining ontology locally.

semantic-contract may constrain zero, one, or many requirements.
semantic-contract requires one Shapes block.
semantic-contract must not contain an Ontology block.
semantic-contract must not contain Concept References.
semantic-contract must use ontology through explicit use relations, and SHACL references must resolve through that used ontology graph.

### Access Token Validation Shape Contract

#### Metadata
  * type: semantic-contract

#### Relations
  * constrain: [API Access Token Validation](#api-access-token-validation)
  * use: [Auth Ontology](#auth-ontology)

#### Shapes
```turtle
@prefix auth: <urn:reqvire:auth:> .
@prefix sh: <http://www.w3.org/ns/shacl#> .

auth:AccessTokenValidationShape
  a sh:NodeShape ;
  sh:targetClass auth:AccessToken ;
  sh:property [
    sh:path auth:subject ;
    sh:minCount 1 ;
  ] .
```

Validation

Turtle parsing

Malformed ontology Turtle is rejected during validation.

Declaration conflicts

Duplicate or incompatible declarations for the same ontology term are rejected.

SHACL reachability

A SHACL reference must point to a term declared by the semantic contract's explicit ontology-use graph. Missing or outside-context references are validation errors.

Change impact

Ontology and semantic-contract dependencies remain explicit so trace and change-impact reports can show what must be reviewed after changes.

Export and Tools

The ontology command collects authored ontology and SHACL content by default. That default output is the reusable semantic vocabulary document. Full mode adds generated Reqvire model context triples for downstream graph/database consumers, including relations, attachments, concept references, term declarations, shape references, and ontology projection facts.

Use reqvire ontologies when a tool needs the clean ontology and SHACL document.
Use reqvire ontologies --full when a graph/database should also know which model elements reference ontology terms.
Concept References appear in full export as model-context facts such as conceptReference and referencesTerm; they do not rewrite authored OWL/SHACL semantics.
Concept References are model-context term-reference edges, not generated OntologyConstruct records. OntologyConstruct is reserved for projected OWL/RDFS/SHACL patterns such as subclass, membership, restriction, property-chain, inverse-property, and shape-overlay constructs.

reqvire ontologies
reqvire ontologies --output ontologies.ttl
reqvire ontologies --jsonld --output ontologies.jsonld
reqvire ontologies --full

# MCP tool
reqvire.ontologies({ "format": "turtle", "full": true })