Reqvire Modeling Language

Reqvire uses semi-structured Markdown as a lightweight semantic engineering and MBSE modeling language. Models stay readable in Git while still forming a machine-validated, queryable, traceable engineering knowledge graph for humans and AI assistants.

Core Elements

Ontologies - first-class OWL/Turtle vocabulary and reusable semantic model terms.

Capabilities - coherent operational, product, business, regulatory, or system abilities.

Requirements - implementable obligations, constraints, guarantees, and behavioral expectations that specify capabilities.

Semantic contracts - reusable SHACL profiles that use ontology vocabulary and constrain requirements.

Refinements - requirement-owned source, specification, constraint, behavior, state, and input-output detail.

Verifications - tests, proofs, analysis, inspection, or demonstrations linked to the capability or requirement they verify.

Relations - explicit links between model elements and implementation or evidence artifacts.

Elements are defined with ### Markdown headers. Metadata, relations, details, attachments, ontology blocks, shapes, queries, and concept references use reserved #### subsections.

Document Shape

Model files begin with either a multi-element file or a single-element file. Element names must be globally unique; stable identifiers let links survive file moves and renames.

Multi-element file

# Elements

### API Authentication

API authentication capability.

#### Metadata
  * type: capability

#### Attachments
  * [Access Token Ontology](AuthOntology.md#access-token-ontology)

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

Single-element file

# Element

## Metadata
  * type: specification

## Relations
  * refine: [API Access Token Validation](Requirements.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.

Physical Containment

The logical graph is defined by metadata and relations. Folders and files provide review boundaries, navigation, and ownership context. The layout below is a suggested convention, not a schema obligation.

<model-root>/
  <Area>/<CapabilityName>/
  Ontologies/
  Verifications/

<Area>/<CapabilityName>/ - root-level capability subgraphs with child capabilities, specifying requirements, and requirement-owned refinements.

Ontologies/ - reusable ontology elements referenced by model elements instead of nested into unrelated capability files.

Verifications/ - verification elements grouped by domain and linked through verify or verifiedBy.

Minimal Example

### API Access Token Validation
The system shall reject API requests whose access token does not conform to the access token semantic contract.

#### Metadata
  * type: requirement

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

#### Relations
  * specify: [API Authentication](#api-authentication)
  * constrainedBy: [Access Token Validation Shape Contract](#access-token-validation-shape-contract)
  * verifiedBy: [Access Token Contract Test](#access-token-contract-test)
  * satisfiedBy: [auth_middleware.rs](../src/auth_middleware.rs)

---

### 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 ;
  ] .
```