reqvire-ontology-authoring

name

reqvire-ontology-authoring

description

Expert workflow for creating, extending, and validating Reqvire structural ontology elements for IT engineering, systems engineering, MBSE, and system-of-interest modeling. Use for competency-question-driven OWL/Turtle vocabulary, semantic-contract boundaries, ontology hierarchy, domain/range/property modeling, individuals, axioms, SHACL target vocabulary, structural-to-concept bridges, and Reqvire validation; trigger when Codex needs to add or revise ontology elements, author

Reqvire Ontology Authoring

Author Reqvire structural ontology content as reusable OWL/RDFS building blocks for system-of-interest models, not implementation detail. Reqvire managed-project ontologies are primarily for IT engineering, systems engineering, MBSE, architecture, interfaces, verification, operations, and other system model concerns. Keep curated conceptual vocabulary in native concept-scheme and concept elements using reqvire-concept-authoring; keep this skill focused on OWL classes, properties, individuals, axioms, SHACL target vocabulary, and structural-to-concept bridges. Use requirements for obligations; use semantic-contract elements for reusable SHACL profiles that explicitly use ontology and constrain requirements.

Use reqvire-syseng instead when the main change is to capabilities, requirements, specifications, verification elements, evidence, coverage, change-impact workflows, or broader model refactoring. This skill may update semantic contracts and ontology links that constrain those elements, but should not replace the system-engineering workflow for changing their behavior.

Reqvire Operations for Ontology Authoring

Use Reqvire as the source-of-truth runtime when authoring or changing OWL/RDFS ontology elements and SHACL semantic contracts.

• Work from the intended effective workspace root unless the user gives a different workspace; the workspace must contain at least one eligible Git worktree.
• Default CLI form: npx -y "${REQVIRE_NPX_PACKAGE:-@reqvire-org/reqvire@latest}" --workspace "$PWD" <command>.
• Inside the Reqvire source repository, cargo run -- <command> is also acceptable when the local binary is the intended target.
• Inspect authored ontology content with search --filter-type ontology --json, search --filter-type semantic-contract --json, model --filter-type ontology --json, semantic export --layer ontologies, semantic export --layer shapes, and semantic export --layer model.
• Use semantic export --layer ontologies --layer external-used or semantic export --layer model --layer external-used only when the used subset of local external ontology dependencies must be materialized.
• Prefer Reqvire CLI mutation commands for broad structural edits when available, such as add, link, relink, mv, mv-file, mv-folder, rm, and rename-element.
• Manual Markdown edits are valid for focused authoring. Preserve # Elements, ### Element Name, #### Metadata, and Reqvire relation list syntax.
• Author ontology elements with type: ontology, ontology_base, ontology_prefix, and #### Ontology; authored Turtle must declare the prefixes it uses.
• Author semantic contracts with type: semantic-contract and #### Shapes; link contracts to ontology elements with use / usedBy and to governed model elements with constrain / constrainedBy.
• Do not add #### Concept References to semantic contracts. Use SHACL shapes for closed-world validation and ontology Turtle for structural terms.
• Relation syntax is * relationName: [Target Element](path.md#target-element).
• Use ontology derivedFrom / derive for ontology hierarchy and document composition. Use reqvire:mapsToConcept in Turtle only when a structural term intentionally maps to a generated native SKOS concept.
• Do not edit generated exports as the source of truth; edit authored Markdown elements and regenerate/export through Reqvire.
• When changing ontology identity, check dependent semantic contracts, requirements constrained by shapes, concept bridges, Explorer ontology/thesaurus data, MCP semantic tools, and tests that assert exported Turtle.
• When validation is part of the task, run focused checks such as validate, semantic export --layer ontologies, semantic export --layer shapes, semantic export --layer model, and any affected fixture tests before finishing.

Workflow

1. Establish the domain-concept frame before project-specific examples.
   • Identify the system of interest and the domain viewpoints the ontology must support: product/domain, engineering/MBSE, operations, governance, interfaces, verification, assurance, or business process.
   • If terminology is still being negotiated, use reqvire-concept-authoring first to create native concept-scheme and concept elements.
   • Add OWL structural classes, properties, individuals, and axioms when the model needs formal schema, validation targets, reasoning semantics, or stable structural relationships.
   • Typical first-pass structural terms for IT/MBSE projects include SystemOfInterest, Actor, CapabilityArea, ManagedResource, BusinessArtifact, OperationalArtifact, InterfaceSurface, ExternalSystem or EnablingSystem, LifecycleState, Operation, Policy, Risk, and VerificationEvidence.
   • Check the six ontology building blocks: SKOS concepts, OWL classes, instances/individuals, properties/slots, relationships, and axioms/rules.
2. Define the system-of-interest scope and 5-10 competency questions.
   • Ask what an ontology-backed model must answer about the system, subsystems, capabilities, functions, interfaces, requirements, verification, deployment, operations, risks, or evidence.
   • Treat these questions as the litmus test for scope. The ontology should contain enough vocabulary and relationships to answer them at the required level of detail.
   • Keep the questions sketch-level; they do not need to be exhaustive.
3. Develop the class hierarchy and properties together.
   • For new ontology work, use top-down modeling by default: define the domain-level concepts first, then specialize them into project-specific concepts.
   • For refactoring existing ontology or source material, first inventory the concrete existing terms bottom-up, then reorganize them into the target top-down domain hierarchy.
   • Use a combined pass only after the top-level hierarchy exists: add important leaves from project sources, then insert middle-level concepts that make competency questions answerable.
   • For each class candidate, immediately ask what object properties and datatype properties are needed: ownership, state, allocation, interface exposure, verification evidence, operational effect, constraints, and identifiers.
4. Inspect the ontology plane:
   • reqvire search --filter-type=ontology --short
   • reqvire semantic export --layer ontologies
   • Read the existing system-model/Ontologies/*.md file that owns nearby vocabulary.
5. Decide whether to extend an existing ontology or create a new ontology element.
   • Extend when the new terms belong to an existing vocabulary root.
   • Create a new ontology when the terms form a coherent reusable vocabulary with separate ownership, lifecycle, or concept-reference scope.
6. Derive candidate OWL classes, properties, individuals, and axioms from the domain frame and competency questions. If the candidate is mainly terminology, synonymy, definition, taxonomy, or stakeholder vocabulary, switch to reqvire-concept-authoring. Structural terms can point back to native concepts through reqvire:mapsToConcept when an explicit bridge is useful.
7. For a top parent ontology element, define ontology_base and ontology_prefix metadata before authoring Turtle. Descendant ontology elements inherit both through derivedFrom hierarchy. Use the corresponding hash namespace for terms, normally <ontology_base>#, with the inherited prefix as the canonical CURIE label. When rebasing an existing ontology element, use add --override as the command path and require it to rewrite the dependent ontology boundary chain atomically, including ontology_base, ontology_prefix, inherited prefix bindings, imports, and any reachable SHACL references.
8. Place ontology elements under system-model/Ontologies.
9. Author exactly one #### Ontology fenced Turtle block per ontology element.
10. Link ontology hierarchy with derivedFrom only between ontology elements.
11. Use #### Concept References on non-ontology, non-semantic-contract elements when their prose needs explicit bindings to SKOS concepts. Do not point concept references directly at OWL classes or properties; bridge structural terms to concepts with reqvire:mapsToConcept in authored ontology when useful.
12. Add or update semantic contracts only when a closed-world SHACL profile is needed; link each contract to ontology with use/usedBy and to governed requirements with constrain/constrainedBy. Do not add #### Concept References to semantic contracts.
13. Use reqvire semantic export --layer ontologies for authored OWL/RDF ontology vocabulary, reqvire semantic export --layer shapes for semantic-contract SHACL shapes, reqvire semantic export --layer concepts for SKOS concepts, and reqvire semantic export for the combined semantic export. Reqvire generates rdfs:isDefinedBy <ontology_base> facts only for authored named ontology resources whose IRIs are inside the resolved ontology term namespace; authors do not need to repeat them, and conflicting authored rdfs:isDefinedBy targets fail validation. Reqvire does not generate rdfs:isDefinedBy ownership facts for imported External Ontology terms. Use reqvire semantic export --layer ontologies --layer external-used, reqvire semantic export --layer external-used, or MCP reqvire.semantic.export with layers: ["ontologies", "external-used"] when the used subset of local External Ontology dependencies must be materialized. Use MCP reqvire.semantic.prefixes, reqvire.semantic.vocabulary, or reqvire.semantic.sparql with include_external: true only when imported external prefixes, used vocabulary terms, or used subset triples are needed. Use MCP reqvire.semantic.vocabulary with ontology_document or ontology_base to filter authored terms to one OWL document, or with include_external: true plus ontology_document to filter used external subset terms to one external source. Use reqvire semantic export --layer model when downstream graph/database tooling also needs model facts for element relations, contract_bindings, concept references, term declarations, shape references, and ontology projection facts. Use reqvire semantic export --layer prefixes when a consumer needs generated Turtle prefix projection facts. Use reqvire semantic export --layer model --layer external-used when both the used external subset and model facts are needed. Concept references are term-reference edges, not generated OntologyConstruct records. Reqvire parses complete external ontology files internally for validation and term resolution. Use the external-used export layer for RDF materialization and helper-tool include_external only for used-subset query visibility; raw full external dependency triples remain available only in explicit full-external workflows.
14. Validate before finishing.

Ontology From Existing Model Content

Ontology work does not have to come first. If capabilities, requirements, specifications, behaviors, constraints, input/output contracts, or verifications already exist, derive ontology and semantic contracts from that authored model rather than forcing a greenfield ontology pass.

Use this workflow when a project has partial or no ontology coverage:

1. Read the existing capability and requirement subgraph first.
2. Extract repeated domain nouns, states, relation words, artifact types, payload concepts, governed tokens, and validation conditions from requirements and contracts.
3. Promote stable reusable vocabulary into ontology elements only where it improves shared meaning, queryability, impact analysis, or semantic validation.
4. Promote repeated closed-world validation rules into semantic-contract SHACL shapes only when machine-checkable constraints add value.
5. Leave requirements prose-only when ontology or SHACL formalization is not useful.
6. Link requirements to reusable shapes with constrainedBy/constrain and link shapes to ontology with use/usedBy.

Modeling Split

Structural Ontology Scope

Use this skill for the structural OWL/RDFS layer:

• Formal classes, object/datatype/annotation properties, named individuals, domain/range, subclass hierarchy, restrictions, property chains, equivalence, disjointness, and other axioms.
• Terms that SHACL shapes, SPARQL queries, semantic exports, or model operations must treat as formal schema.
• Stable domain semantics such as X is a Y, X has property Z, and X relates to Y.

Use reqvire-concept-authoring for the conceptual SKOS layer:

• Native concept-scheme and concept elements.
• Curated human/domain terms, labels, synonyms, definitions, taxonomy, search/navigation anchors, scope notes, examples, and concept mappings.
• Concept references from capabilities, requirements, contracts, and verifications to generated native SKOS concepts.

Concept vs Ontology Decision Rule

Do not use ontology class hierarchy as a shortcut for concept taxonomy. rdfs:subClassOf means formal structural subtype; SKOS broader means a broader thesaurus/navigation term. They can overlap, but only copy the relationship when it also passes the concept "is-a kind of" browse-term test.

Use native concepts for curated terminology: labels, definitions, synonyms, top concepts, broader/narrower browse structure, related terms, and cross-vocabulary concept mappings. Use ontology for formal semantics: classes, properties, individuals, domain/range, lifecycle states, statuses, constraints, and SHACL targets.

If the intended meaning is Payment hasStatus Pending, model Payment, status classes/individuals, and a status property in ontology. Do not force that into concept taxonomy unless "Pending Payment" is intentionally a narrower payment term for search or navigation. Use reqvire:mapsToConcept only as a bridge from structural terms to generated native SKOS concept IRIs.

Bridge the layers only when useful:

• Use reqvire:mapsToConcept from a structural term or model resource to a generated native SKOS concept.
• reqvire:mapsToConcept is an owl:AnnotationProperty; it does not imply OWL equivalence, SKOS mapping semantics, or that the structural subject is itself a skos:Concept.
• Do not use skos:exactMatch, skos:broadMatch, or other SKOS mapping properties for structural-to-concept anchoring by default. Reserve SKOS mapping properties for concept-to-concept mappings in reqvire-concept-authoring.

Preferred mixed structure:

Concept scheme root
  type: concept-scheme
  concept_base: https://example.org/concepts
  concept_prefix: concept
  authored with reqvire-concept-authoring

Structural ontology root
  ontology_base: https://example.org/ontology/managed-platform
  ontology_prefix: ex
  owns: owl:Class, owl:ObjectProperty, owl:DatatypeProperty,
        individuals, axioms, SHACL targets
  optional bridge: ex:StructuralTerm reqvire:mapsToConcept concept:CuratedConcept

Before adding or changing OWL classes, run the structure/concept check:

• If the work is mainly labels, synonyms, definitions, spelling variants, audience terms, broader/narrower editorial categories, or search/navigation vocabulary, use reqvire-concept-authoring.
• If the work is formal type membership, valid properties, domain/range, SHACL targets, reasoning, or graph operation semantics, create or extend OWL structural terms here.
• If an OWL class is accumulating glossary prose, aliases, search facets, and stakeholder wording, split that curation into native concepts and keep the class structural.
• If a hierarchy means "is a formal subtype of", use rdfs:subClassOf. If it means "is a broader/narrower topic than", use native concept relations through reqvire-concept-authoring.

Use ontology for:

• Reusable structural ontology vocabulary under root ontology_base and ontology_prefix metadata values.
• OWL structural classes, object properties, datatype properties, annotation properties, named individuals, stable hierarchy, and axioms.
• MBSE/system-of-interest structural terms such as system, subsystem, function, interface, port, deployment environment, operational mode, verification evidence, risk, hazard, dependency, allocation, and traceability category when those terms are formal schema.

Use requirement for implementable obligations, especially statements that naturally read as "The system shall...".

Use specification, behavior, constraint, state, or input-output for exact commands, file paths, outputs, workflows, schemas, UI behavior, and implementation-specific details.

Use semantic-contract for reusable SHACL shape profiles. A semantic contract is a first-class ontology-plane element and should be authored under system-model/Ontologies near the ontology it uses. It must have #### Shapes, use valid SHACL targets and paths over ontology terms reachable through explicit use relations, constrain requirements through constrain/constrainedBy, and must not contain #### Ontology.

For greenfield ontology creation templates and examples, read references/OntologyAuthoring.md.

For refactoring or improving existing ontology files, read references/OntologyRefactoring.md. Do not load the refactoring reference for new ontology creation unless the user explicitly asks to refactor or improve existing ontology content.

OWL 2 Authoring Mental Model

When authoring ontology Turtle, distinguish the OWL 2 syntactic roles:

• Entities are named IRI terms such as classes, object properties, datatype properties, annotation properties, and individuals. These are the primitive vocabulary terms that Reqvire elements, concept references, SHACL shapes, SPARQL queries, and semantic exports can reference.
• Expressions are complex OWL descriptions such as restrictions, unions, intersections, complements, RDF-list class expressions, and property-chain expressions. Use them only when the intended inferred meaning is stable and worth exposing to downstream semantic tooling.
• Axioms are asserted truths such as subclass, domain/range, inverse property, disjointness, equivalence, restrictions, individual typing, and property chains. Axioms affect logical meaning and future reasoning behavior.
• Annotations are labels, comments, definitions, and presentation metadata attached to entities, axioms, or ontologies. They help humans and applications render or explain the ontology, but they do not define logical meaning.

OWL and SHACL answer different questions:

• OWL is about meaning and inference: given these facts and domain truths, what else follows?
• SHACL is about validation: given these expected data shapes, is this graph acceptable?

OWL uses an open-world assumption, so missing facts are usually unknown rather than invalid. SHACL validation is closed-world for the selected shapes, so missing required facts are validation errors.

Reqvire rule of thumb:

• Use OWL entities and axioms for reusable domain meaning.
• Use SHACL semantic contracts for closed-world validation.
• Use rdfs:label and rdfs:comment for human-readable explanation, not as substitutes for formal terms.
• If queries, SHACL, exports, report payloads, or model behavior depend on a value, model it as a real class, property, individual, or axiom rather than only as annotation text.
• Do not encode required fields, cardinality checks, enum validation, parser behavior, command behavior, or report formatting as OWL axioms unless they are true domain semantics intended for reasoning.
• Do not collapse conceptual and structural layers just because they share a label. A SKOS concept named "Electric vehicle" can remain separate from an OWL class ex:ElectricVehicle; use reqvire:mapsToConcept only if an explicit bridge is useful.

Common OWL Axioms

Common OWL/RDFS axioms authored in Reqvire #### Ontology blocks:

• rdfs:subClassOf defines class hierarchy.
• rdfs:subPropertyOf defines property hierarchy.
• rdfs:domain and rdfs:range define stable subject/object or subject/literal meaning for a property.
• owl:inverseOf defines inverse object-property relationships.
• owl:equivalentClass and owl:equivalentProperty define semantic equivalence.
• owl:disjointWith defines classes that cannot share the same individual when reasoning is applied.
• owl:Restriction with owl:onProperty, owl:someValuesFrom, owl:allValuesFrom, cardinality terms, or owl:hasValue defines class expressions over property constraints.
• owl:propertyChainAxiom defines inferred relationships across a property path.
• Individual typing, such as ex:prod a ex:Environment, asserts that a named individual belongs to a class.

Use OWL axioms for reusable truths that semantic tools or future reasoners should understand. Use SHACL semantic contracts for closed-world validation rules such as required explicit fields, exact cardinality, allowed string values, and parser/report conformance checks.

Labels, Definitions, and Domain Tokens

Use rdfs:label and rdfs:comment for labels and descriptions unless the value is a true domain concept, contract token, or query/validation target. Treat them as the default for presentation text, not replacements for ontology slots.

• rdfs:label is optional presentation label text when no more specific domain property is needed.
• rdfs:comment is optional explanatory description text for a class, property, individual, or axiom.
• Create a domain class or property when a label/description value is itself system meaning that requirements, SHACL, queries, reports, or payloads depend on.
• Keep custom datatype properties only when the literal is part of the domain or model contract: authored metadata tokens, rule conditions, queryable attributes, or controlled-vocabulary payloads.
• If a SHACL shape validates a presentation-only *Name, *Label, *Meaning, or description field, refactor the SHACL sh:path to rdfs:label or rdfs:comment instead of preserving a custom property.
• Do not infer that a property is only a label because it ends with Name or only a comment because it ends with Meaning.
• Controlled-vocabulary individuals get formal semantics from their IRI, explicit owl:NamedIndividual typing, typed class membership, hierarchy, and axioms. Domain token and definition properties may still be required for validation and queries.
• Do not replace canonical domain-token properties with rdfs:label when semantic contracts, model operations, or queries depend on the literal. Delivery-surface tokens such as command names, UI route names, and report-output kind names belong in specifications or contracts unless the domain itself needs to reason over them.

OWL / SHACL Block Split

Use OWL datatype/object properties for slots and relationships with stable domain/range semantics. Use SHACL shapes for operational validation facets.

• In #### Ontology, define classes, owl:DatatypeProperty and owl:ObjectProperty declarations, stable rdfs:domain/rdfs:range, hierarchy, metadata annotations, and stable OWL axioms.
• For datatype properties, set rdfs:range to an XSD datatype such as xsd:string, xsd:boolean, xsd:integer, xsd:decimal, xsd:float, xsd:double, xsd:dateTime, or xsd:date.
• For object properties, set rdfs:domain to the subject class and rdfs:range to the object class when both are stable.
• In #### Shapes, declare sh:NodeShape or sh:PropertyShape resources, use valid SHACL targets such as sh:targetClass, sh:targetNode, sh:targetSubjectsOf, or sh:targetObjectsOf, and validate existing properties with sh:path.
• Do not redefine ex:Class a owl:Class inside a SHACL shape block. The shape consumes the ontology; it does not own the class declaration.
• Put closed-world cardinality, patterns, enumerations, numeric bounds, messages, and data-quality rules in SHACL, not in the ontology block. Use OWL cardinality restrictions only when they are true domain axioms and reasoner semantics are intended.
• Keep OWL and SHACL separable so ontology exports remain useful to OWL/RDFS tools while semantic contracts remain useful to SHACL validators.

OWL/Turtle Quick Reference

Reqvire ontology blocks are Turtle using OWL/RDFS vocabulary. Prefer compact, stable CURIEs and define terms explicitly before referencing them.

Use canonical Reqvire ontology identity boundaries:

• The top parent ontology element in an ontology subgraph must define non-empty ontology_base and ontology_prefix metadata, for example ontology_base: https://example.org/ontology/managed-platform and ontology_prefix: ex. When rebasing an existing ontology element, use add --override instead of hand-editing metadata so the rewrite chain remains atomic.
• The term namespace identifies classes, properties, and individuals and normally uses the inherited ontology base plus #, for example @prefix ex: <https://example.org/ontology/managed-platform#>. The prefix label comes from inherited ontology_prefix; the namespace comes from inherited ontology_base.
• Authored Turtle that uses the inherited prefix must explicitly declare it to <ontology_base>#; missing or conflicting declarations fail validation.
• The root ontology Turtle block should declare <ontology_base> a owl:Ontology for authored OWL document identity. Child ontology blocks normally define vocabulary terms only. Do not manually model the ontology itself as a vocabulary term inside the term namespace, such as ex:ManagedPlatformOntology a owl:Ontology.
• Reqvire generates rdfs:isDefinedBy <ontology_base> ownership facts only for authored named ontology resources whose IRIs are inside the resolved term namespace. Do not hand-author these on every term; if present on an authored in-namespace resource, they must match the generated ontology document IRI or validation fails. Imported External Ontology terms do not receive Reqvire-generated rdfs:isDefinedBy.
• Link ontology hierarchy with derivedFrom between ontology elements. Reqvire derives one ontology document declaration per resolved ontology_base; same-base derivedFrom contributes to the same document, while cross-base hierarchy can become owl:imports.
• Use repeatable #### External Ontology sections on ontology elements for local external Turtle/TTL, RDF/XML, or JSON-LD vocabularies that are not authored by the Reqvire model. Each section requires prefix, namespace, resource, and source; format defaults to Turtle and supports turtle, ttl, rdf, rdfxml, rdf+xml, and jsonld. format: rdf is RDF/XML for local .rdf ontology files. Sources must be local files, not network fetches. These sections make imported terms available to that ontology context and to semantic contracts that use it, but they do not inject prefixes or triples into authored Turtle and do not promote imported terms to authored Reqvire ontology terms. Full source files are internal dependency inputs; include_external exposes only the used external subset unless you specifically request explicit full-external mode. Do not add external sections for standard OWL/RDF/RDFS/XSD built-in vocabulary or core SHACL shape syntax; Reqvire recognizes those language vocabularies internally. Use External Ontology only for additional local vocabularies, such as project-specific exported ontologies or SHACL extension vocabularies.
• SKOS is available as a Reqvire built-in external ontology source for structural annotations or deliberate bridge vocabulary. Authors may use @prefix skos: <http://www.w3.org/2004/02/skos/core#> . in ontology Turtle without adding a local #### External Ontology section for SKOS, but Turtle must still explicitly declare the prefix it uses. Do not use ontology Turtle as the normal authoring path for Reqvire-native concept schemes or concepts.

Native conceptual layer example:

### Engineering Concepts

Curated engineering terminology for system-model authoring.

#### Metadata
  * type: concept-scheme
  * concept_base: https://example.org/concepts
  * concept_prefix: concept
---

### Traceability

The conceptual practice of connecting intent, implementation, verification, and evidence.

#### Metadata
  * type: concept

#### Relations
  * derivedFrom: [Engineering Concepts](Thesaurus.md#engineering-concepts)

#### Labels
  * altLabel: Trace link analysis

Structural layer with optional concept bridge:

@prefix ex: <https://example.org/ontology/managed-platform#> .
@prefix concept: <https://example.org/concepts#> .
@prefix reqvire: <https://www.reqvire.org/ontology#> .
@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .

ex:TraceLink a owl:Class ;
  rdfs:comment "Structural relationship record connecting model elements for impact and coverage analysis." ;
  reqvire:mapsToConcept concept:Traceability .

Connected concept-root pattern:

### Engineering Concepts

Curated concept scheme for engineering system-model terms.

#### Metadata
  * type: concept-scheme
  * concept_base: https://example.org/concepts
  * concept_prefix: concept

### Managed Platform Structural Ontology

#### Metadata
  * type: ontology
  * ontology_base: https://example.org/ontology/managed-platform
  * ontology_prefix: ex

#### Ontology
```turtle
@prefix concept: <https://example.org/concepts#> .
@prefix ex: <https://example.org/ontology/managed-platform#> .
@prefix reqvire: <https://www.reqvire.org/ontology#> .
@prefix owl: <http://www.w3.org/2002/07/owl#> .

<https://example.org/ontology/managed-platform>
  a owl:Ontology .

ex:TraceLink a owl:Class ;
  reqvire:mapsToConcept concept:Traceability .
```

@prefix ex: <https://example.org/ontology/managed-platform#> .
@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

ex:ManagedResource a owl:Class .

ex:Deployment a owl:Class ;
  rdfs:subClassOf ex:ManagedResource .

ex:Environment a owl:Class ;
  rdfs:subClassOf ex:ManagedResource .

ex:InterfaceSurface a owl:Class .
ex:PublicApiSurface a owl:Class ;
  rdfs:subClassOf ex:InterfaceSurface .
ex:PrivateApiSurface a owl:Class ;
  rdfs:subClassOf ex:InterfaceSurface .

ex:productionEnvironment a owl:NamedIndividual, ex:Environment ;
  ex:resourceIdentifier "env-prod" .

ex:resourceIdentifier a owl:DatatypeProperty ;
  rdfs:domain ex:ManagedResource ;
  rdfs:range xsd:string .

ex:deploymentBelongsToEnvironment a owl:ObjectProperty ;
  rdfs:domain ex:Deployment ;
  rdfs:range ex:Environment ;
  owl:inverseOf ex:environmentHostsDeployment .

ex:environmentHostsDeployment a owl:ObjectProperty ;
  rdfs:domain ex:Environment ;
  rdfs:range ex:Deployment .

ex:DeploymentWithEnvironment a owl:Class ;
  rdfs:subClassOf ex:Deployment,
    [ a owl:Restriction ;
      owl:onProperty ex:deploymentBelongsToEnvironment ;
      owl:someValuesFrom ex:Environment ] .

ex:IntegrationBoundary a owl:Class ;
  owl:equivalentClass ex:InterfaceSurface .

ex:interfaceExposesResource a owl:ObjectProperty .
ex:exposesResource a owl:ObjectProperty ;
  owl:equivalentProperty ex:interfaceExposesResource .

ex:environmentHasPolicy a owl:ObjectProperty .
ex:resourceImpactedByPolicy a owl:ObjectProperty ;
  owl:propertyChainAxiom (ex:deploymentBelongsToEnvironment ex:environmentHasPolicy) .

ex:PublicApiSurface owl:disjointWith ex:PrivateApiSurface .

Use skos:Concept for curated conceptual vocabulary, owl:Class for structural classes, explicit owl:NamedIndividual plus domain-class typing for stable vocabulary records, owl:DatatypeProperty for literal slots, owl:ObjectProperty for relationship slots, rdfs:subClassOf for is-a hierarchy, rdfs:domain/rdfs:range for stable slot semantics and allowed values, and OWL axioms such as owl:Restriction, owl:inverseOf, owl:equivalentClass, owl:equivalentProperty, owl:disjointWith, and owl:propertyChainAxiom only when the semantics are true. Use reqvire:mapsToConcept as an optional annotation bridge from structural terms to SKOS concepts. Use SHACL shapes for closed-world validation such as required fields, cardinality, enumerations, or datatype checks.

Validation

Run focused validation after ontology edits:

npx -y "${REQVIRE_NPX_PACKAGE:-@reqvire-org/reqvire@latest}" --workspace "$PWD" validate
npx -y "${REQVIRE_NPX_PACKAGE:-@reqvire-org/reqvire@latest}" --workspace "$PWD" semantic export --layer ontologies

When working in the Reqvire source repository, the local Rust CLI is also acceptable:

cargo run -q -p reqvire-cli -- --workspace "$PWD" validate

Guardrails

• Keep ontology text reusable and implementation-independent.
• Start from the domain frame and competency questions, and remove ontology terms that do not help answer them or support future system-of-interest modeling.
• Declare referenced ontology terms before SHACL shapes reference them.
• Prefer deterministic IRIs and stable CURIE prefixes.
• Avoid random UUIDs in authored ontology unless the domain truly requires non-semantic identifiers.
• Do not put governance metadata on ontology elements.
• Do not claim implementation satisfaction from ontology elements.
• If adding many property semantics, include domain/range only when the domain and range are stable and not misleadingly broad.