Operational Ontology Contract (OOC) — ArcaQ Semantic Enforcement Layer

§1 — Three Pillars of an OOC

An OOC goes beyond schema validation. It encodes formal semantics that an AI reasoner can act on.

🌐

Multilingual Native Definitions

Every concept carries definitions as first-class RDF language literals — not translations from English. rdfs:label and skos:definition in Arabic, French, English, and any required language. AI agents query the same OWL class through any language's skos:altLabel.

🧠

OWL Logical Axioms

Property characteristics are formal axioms, not labels. Declaring isPartOf as Transitive instructs the reasoner to materialize the full transitivity chain. Functional, Asymmetric, Inverse — each characteristic enables a class of inferences your AI can make without guesswork.

🛡️

Runtime SHACL Enforcement

SHACL NodeShapes compiled from the OOC enforce constraints at ingestion time. Every entity written to the Jena graph is validated against sh:minCount, sh:pattern, sh:datatype, and sh:in (allowed values). Violations are rejected with structured, multilingual error messages — not silently accepted.

§2 — OOC vs. Data Contract

Both serve quality. Only one serves meaning.

Capability	Data Contract	OOC
Field type & nullability enforcement	✓	✓ (SHACL sh:datatype / sh:minCount)
Value pattern (regex)	✓	✓ (SHACL sh:pattern)
Multilingual concept definitions	✗	✓ (rdfs:label / skos:definition per lang tag)
OWL property characteristics	✗	✓ (Transitive, Asymmetric, Functional, Inverse)
Allowed-value enumeration (closed world)	⚠ ad hoc	✓ (owl:oneOf + sh:in)
Interoperability alignments (ISO, RML)	✗	✓ (interoperability section)
OLM lifecycle governance	✗	✓ (draft → review → approved → deprecated)
Compiled into graph artifacts (OWL + SHACL)	✗	✓ (generated on demand, loaded into Jena)

§3 — Compile Pipeline

YAML is the source of truth. OWL and SHACL are derived artifacts generated on demand.

Source

OOC YAML

→

Compile

POST /compile

→

T-Box

OWL Turtle

+

A-Box

SHACL Turtle

→

Loaded into

Apache Jena

Breaking changes require four-eyes approval before the new compiled artifacts replace the current version in the graph.

§4 — OOC Structure: Five Sections

Every OOC YAML follows a canonical five-section structure that maps directly to compiled OWL and SHACL constructs.

§ 1

metadata

Contract identity: id, title, domain, version, status, multilingual labels, authors, changelog. Drives the OLM registry entry.

§ 2

semantics

OWL namespace, classes (with multilingual labels/definitions), object properties (domain, range, characteristics: Transitive / Asymmetric / Functional / Inverse), datatype properties (range, allowedValues → owl:oneOf). Compiled into OWL Turtle.

§ 3

data_integrity

SHACL shapes: per-class sh:NodeShape with property constraints — sh:minCount, sh:maxCount, sh:pattern, sh:datatype, sh:in, severity, multilingual sh:message. Compiled into SHACL Turtle.

§ 4

versioning_control

Policy (STRICT / RELAXED), breaking-change requirements (four_eyes_approval, graph_migration_plan), compatibility strategy (BACKWARD / FULL). Governs OLM transition rules.

§ 5

interoperability

Standard alignments (ISO-10303, ISO-15926, RML mappings, W3C standards) with mapped class/property and SKOS relationship (exactMatch, closeMatch, broadMatch). Enables cross-standard reasoning.

§5 — Minimal OOC Example

A turbine component contract with Transitive + Asymmetric isPartOf, functional serial number, and SHACL constraint.

metadata:
  id: ooc-turbine-2026-v1
  title: Industrial Turbine Component
  domain: industrial-equipment
  version: "1.0.0"
  status: approved
  labels:
    en: Industrial Turbine Component
    fr: Composant Turbine Industrielle
    ar: مكوّن التوربين الصناعي

semantics:
  namespace: https://arcaq.com/ontology/turbine#
  classes:
    - id: TurbineComponent
      labels: { en: Turbine Component, fr: Composant de Turbine, ar: مكوّن التوربين }
  object_properties:
    - id: isPartOf
      domain: TurbineComponent
      range: TurbineComponent
      characteristics: [Transitive, Asymmetric]
  datatype_properties:
    - id: operationalStatus
      range: xsd:string
      allowedValues: [OPERATIONAL, STANDBY, UNDER_MAINTENANCE, DECOMMISSIONED]

data_integrity:
  shapes:
    - target: TurbineComponent
      constraints:
        - property: serial_number
          minCount: 1
          maxCount: 1
          pattern: "^[A-Z]{2}-[0-9]{6}$"
          severity: Violation
          message:
            en: Serial number must match format XX-NNNNNN
            fr: Le numéro de série doit correspondre au format XX-NNNNNN

versioning_control:
  policy: STRICT
  breaking_change_requires: [four_eyes_approval, graph_migration_plan]

interoperability:
  standard_alignments:
    - standard: ISO-10303-239
      mapped_class: TurbineComponent
      relationship: skos:exactMatch

This YAML compiles into an OWL Turtle declaring owl:TransitiveProperty, owl:AsymmetricProperty, owl:oneOf for operationalStatus, and a SHACL NodeShape enforcing the serial number pattern — all loaded into Jena on approval.

§6 — OOC Registry API

All OOC operations are exposed through ArcaQ's REST API. No CLI, no manual TTL authoring.

Method	Endpoint	Description
GET	/api/v1/ooc/contracts	List all OOC contracts (filter by status / domain)
GET	/api/v1/ooc/contracts/{id}	Retrieve a single OOC with full YAML content
POST	/api/v1/ooc/contracts	Create a new OOC contract (starts in DRAFT)
PUT	/api/v1/ooc/contracts/{id}	Update YAML content of an existing contract
POST	/api/v1/ooc/contracts/{id}/compile	Compile YAML → OWL TTL + SHACL TTL
POST	/api/v1/ooc/contracts/{id}/validate	Run SHACL shapes against the current graph population
GET	/api/v1/ooc/contracts/{id}/export	Export as YAML, Turtle, or JSON-LD
POST	/api/v1/ooc/upload	Upload a YAML file and auto-register to the OOC registry