Plan, apply and roll back changes to a production ontology, with a blast radius report and a proof an auditor can re-check.
Rust ai-nativedescription-logicsformal-verificationinfrastructure-as-codeisabelle-languageknowledge-graphleanlean4mcpmcp-serverontologyowlowl2reasoningrustshaclsparqltheorem-proving
//! Apache Ossie ontology documents -> OWL 2 DL + SHACL (#ossie).
//!
//! [Apache Ossie](https://ossie.apache.org/) (incubating, formerly Open Semantic
//! Interchange) is the vendor-neutral semantic-model specification backed by
//! Snowflake, Salesforce, Databricks, dbt Labs and around fifty other data
//! platforms. Its `ontology/ontology.md` 0.2.0.dev0 module is a fact-based
//! conceptual model: `EntityType` / `ValueType` concepts, relationships carrying
//! ordered roles with multiplicities and verbalizations, preferred identifiers,
//! derivation rules and population constraints.
//!
//! The Ossie ontology spec references neither RDF, OWL, SKOS nor SHACL, so an
//! Ossie ontology is invisible to every reasoner and validator in the semantic
//! web stack. This module closes that gap: it compiles an Ossie ontology document
//! into OWL 2 DL plus SHACL shapes, which the rest of this crate can then reason
//! over (`reason`, `tableaux`), validate against (`shacl`), diff (`drift`) and
//! audit (`vocab_check`).
//!
//! # What OWL cannot take
//!
//! Four Ossie constructs have no OWL 2 DL expression. These are properties of the
//! logic, not gaps in this implementation, and each one is why SHACL is emitted
//! alongside the OWL rather than instead of it.
//!
//! 1. **`OneToOne` onto a `ValueType`** is `InverseFunctionalDataProperty`, which
//! OWL 2 DL forbids because it costs decidability; it exists only in OWL Full.
//! This is the *common* case rather than a corner: in fact-based modelling the
//! preferred identifier of an entity type is by construction a relationship to
//! a value type. Emitted as a SHACL SPARQL uniqueness constraint.
//! 2. **`ManyToOne` on a relationship of arity >= 3** is a functional dependency
//! across a tuple of roles. OWL cardinality restrictions constrain one property
//! at a time. Emitted as a SHACL SPARQL constraint.
//! 3. **`derived_by`** is a recursive rule language. OWL has no rule construct.
//! Preserved as an annotation, unenforced.
//! 4. **`requires`** is an ungrammared SQL expression string. Only the scalar
//! comparison fragment (`0 < SocialSecurityNr`) becomes an XSD facet; the rest
//! is preserved verbatim rather than guessed at.
//!
//! Nothing is discarded. Every construct the target cannot enforce is also written
//! to an `ossie:` annotation property in a reserved namespace, all of them
//! declared `owl:AnnotationProperty` so the emitted graph stays inside OWL 2 DL.
use serde::{Deserialize, Serialize};
use std::collections::BTreeMap;
use std::fmt::Write as _;
/// Reserved namespace for the provenance annotations.
pub const OSSIE_NS: &str = "https://ossie.apache.org/ns/ontology#";
/// Default base for generated terms when the caller supplies none.
pub const DEFAULT_BASE: &str = "https://ossie.apache.org/ontology/";
// --------------------------------------------------------------------------- //
// Source document
// --------------------------------------------------------------------------- //
#[derive(Debug, Deserialize)]
pub struct OssieDocument {
#[serde(default)]
pub version: Option<String>,
pub name: String,
#[serde(default)]
pub description: Option<String>,
#[serde(default)]
pub ai_context: Option<serde_json::Value>,
#[serde(default)]
pub requires: Vec<String>,
pub ontology: Vec<Component>,
#[serde(default)]
pub ontology_mappings: Option<serde_json::Value>,
}
#[derive(Debug, Deserialize)]
pub struct Component {
pub concept: String,
#[serde(rename = "type")]
pub concept_type: String,
#[serde(default)]
pub description: Option<String>,
#[serde(default)]
pub extends: Vec<String>,
#[serde(default)]
pub derived_by: Vec<String>,
#[serde(default)]
pub identify_by: Vec<String>,
#[serde(default)]
pub requires: Vec<String>,
#[serde(default)]
pub relationships: Vec<Relationship>,
}
#[derive(Debug, Deserialize)]
pub struct Relationship {
pub name: String,
#[serde(default)]
pub description: Option<String>,
#[serde(default)]
pub roles: Vec<Role>,
#[serde(default)]
pub multiplicity: Option<String>,
#[serde(default)]
pub derived_by: Vec<String>,
#[serde(default)]
pub requires: Vec<String>,
#[serde(default)]
pub verbalizes: Vec<String>,
}
#[derive(Debug, Deserialize)]
pub struct Role {
pub concept: String,
#[serde(default)]
pub name: Option<String>,
}
// --------------------------------------------------------------------------- //
// Result
// --------------------------------------------------------------------------- //
/// A construct that survived the conversion as an annotation but that the target
/// formalism cannot enforce.
#[derive(Debug, Clone, Serialize)]
pub struct Issue {
pub kind: &'static str,
pub element: String,
pub detail: &'static str,
}
#[derive(Debug, Serialize)]
pub struct OssieConversion {
/// OWL 2 DL terminology plus SHACL shapes, as Turtle.
pub turtle: String,
/// Base IRI the terms were minted under.
pub base_iri: String,
pub concepts: usize,
pub entity_types: usize,
pub value_types: usize,
pub relationships: usize,
/// SHACL SPARQL constraints carrying what OWL could not state.
pub sparql_constraints: usize,
pub issues: Vec<Issue>,
}
// --------------------------------------------------------------------------- //
// Built-ins
// --------------------------------------------------------------------------- //
/// Ossie built-in value types and their XSD counterparts.
///
/// `Float` maps to `xsd:double`, not `xsd:float`: the Ossie core spec calls
/// `Float` approximate with unspecified width, and `xsd:double` is the wider of
/// the two IEEE 754 binary types, so the mapping never narrows a value.
fn builtin_xsd(name: &str) -> Option<&'static str> {
Some(match name {
"Boolean" => "http://www.w3.org/2001/XMLSchema#boolean",
"Date" => "http://www.w3.org/2001/XMLSchema#date",
"DateTime" => "http://www.w3.org/2001/XMLSchema#dateTime",
"Decimal" => "http://www.w3.org/2001/XMLSchema#decimal",
"Float" => "http://www.w3.org/2001/XMLSchema#double",
"Integer" => "http://www.w3.org/2001/XMLSchema#integer",
"String" => "http://www.w3.org/2001/XMLSchema#string",
_ => return None,
})
}
// --------------------------------------------------------------------------- //
// requires -> XSD facet
// --------------------------------------------------------------------------- //
/// One XSD facet derived from a recognised `requires` expression.
#[derive(Debug, Clone)]
pub struct Facet {
pub subject: String,
/// Facet local name: `minInclusive`, `maxInclusive`, `minExclusive`, `maxExclusive`.
pub facet: &'static str,
/// The bound, already rendered as a typed Turtle literal.
pub literal: String,
}
fn is_identifier(text: &str) -> bool {
let mut chars = text.chars();
match chars.next() {
Some(c) if c.is_ascii_alphabetic() || c == '_' => {}
_ => return false,
}
chars.all(|c| c.is_ascii_alphanumeric() || c == '_')
}
fn numeric_literal(text: &str) -> Option<String> {
let candidate = text.trim();
if candidate.is_empty() {
return None;
}
if candidate.parse::<i64>().is_ok() {
return Some(format!(
"\"{candidate}\"^^<http://www.w3.org/2001/XMLSchema#integer>"
));
}
if candidate.parse::<f64>().is_ok() && !candidate.contains(['e', 'E']) {
return Some(format!(
"\"{candidate}\"^^<http://www.w3.org/2001/XMLSchema#decimal>"
));
}
None
}
/// Parse one `requires` expression into a [`Facet`], or `None` if unrecognised.
///
/// Only a comparison between a bare identifier and a numeric literal is
/// recognised. Compound expressions, function calls and relationship navigation
/// (`Item.offers_in(Store)`) all return `None`; the caller preserves those
/// verbatim rather than translating them wrongly.
pub fn parse_requires(expression: &str) -> Option<Facet> {
// Longest operators first so "<=" is not read as "<".
const OPERATORS: &[&str] = &["<=", ">=", "<", ">"];
for op in OPERATORS {
// Reject anything carrying a second comparison or an (in)equality.
if expression.contains("==") || expression.contains("!=") {
return None;
}
let Some(index) = expression.find(op) else {
continue;
};
let (lhs, rest) = expression.split_at(index);
let rhs = &rest[op.len()..];
if rhs.contains('<') || rhs.contains('>') {
return None;
}
let (lhs, rhs) = (lhs.trim(), rhs.trim());
let (subject, literal, subject_on_left) = if is_identifier(lhs) && !is_identifier(rhs) {
(lhs, numeric_literal(rhs)?, true)
} else if is_identifier(rhs) && !is_identifier(lhs) {
(rhs, numeric_literal(lhs)?, false)
} else {
return None;
};
// `0 < X` means `X > 0`, so the facet flips when the subject is on the right.
let facet = match (*op, subject_on_left) {
("<", true) | (">", false) => "maxExclusive",
("<=", true) | (">=", false) => "maxInclusive",
(">", true) | ("<", false) => "minExclusive",
(">=", true) | ("<=", false) => "minInclusive",
_ => unreachable!("operator table is exhaustive"),
};
return Some(Facet {
subject: subject.to_string(),
facet,
literal,
});
}
None
}
// --------------------------------------------------------------------------- //
// Turtle helpers
// --------------------------------------------------------------------------- //
fn escape_literal(text: &str) -> String {
let mut out = String::with_capacity(text.len() + 8);
for ch in text.chars() {
match ch {
'\\' => out.push_str("\\\\"),
'"' => out.push_str("\\\""),
'\n' => out.push_str("\\n"),
'\r' => out.push_str("\\r"),
'\t' => out.push_str("\\t"),
_ => out.push(ch),
}
}
out
}
fn quote(text: &str) -> String {
format!("\"{}\"", escape_literal(text))
}
/// Percent-encode an Ossie name for use as an IRI local part.
///
/// `.` is deliberately left alone so the `Concept.name` relationship identifier
/// survives intact, and the delimiters that would end an IRI are escaped.
fn iri_escape(name: &str) -> String {
let mut out = String::with_capacity(name.len());
for byte in name.bytes() {
match byte {
b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'.' | b'~' => {
out.push(byte as char)
}
_ => {
let _ = write!(out, "%{byte:02X}");
}
}
}
out
}
// --------------------------------------------------------------------------- //
// Conversion
// --------------------------------------------------------------------------- //
struct Converter<'a> {
base: String,
doc: &'a OssieDocument,
by_name: BTreeMap<&'a str, &'a Component>,
facets: BTreeMap<String, Vec<Facet>>,
issues: Vec<Issue>,
sparql_constraints: usize,
out: String,
}
/// Compile an Ossie ontology document into OWL 2 DL plus SHACL shapes.
///
/// `base_iri` defaults to `https://ossie.apache.org/ontology/{name}#`.
pub fn to_owl_shacl(
doc: &OssieDocument,
base_iri: Option<&str>,
emit_shacl: bool,
) -> Result<OssieConversion, String> {
let base = base_iri
.map(str::to_string)
.unwrap_or_else(|| format!("{DEFAULT_BASE}{}#", iri_escape(&doc.name)));
let mut by_name = BTreeMap::new();
for component in &doc.ontology {
if by_name
.insert(component.concept.as_str(), component)
.is_some()
{
return Err(format!("concept {:?} declared twice", component.concept));
}
}
let mut converter = Converter {
base,
doc,
by_name,
facets: BTreeMap::new(),
issues: Vec::new(),
sparql_constraints: 0,
out: String::new(),
};
converter.run(emit_shacl)?;
let entity_types = doc
.ontology
.iter()
.filter(|c| c.concept_type != "ValueType")
.count();
let relationships = doc.ontology.iter().map(|c| c.relationships.len()).sum();
Ok(OssieConversion {
turtle: converter.out,
base_iri: converter.base,
concepts: doc.ontology.len(),
entity_types,
value_types: doc.ontology.len() - entity_types,
relationships,
sparql_constraints: converter.sparql_constraints,
issues: converter.issues,
})
}
impl<'a> Converter<'a> {
fn run(&mut self, emit_shacl: bool) -> Result<(), String> {
self.prologue();
for component in &self.doc.ontology {
self.concept(component)?;
}
for component in &self.doc.ontology {
for relationship in &component.relationships {
self.relationship(component, relationship)?;
}
}
if emit_shacl {
for component in &self.doc.ontology {
if component.concept_type != "ValueType" {
self.node_shape(component)?;
}
}
}
Ok(())
}
fn prologue(&mut self) {
let base = self.base.clone();
let out = &mut self.out;
let _ = writeln!(out, "@prefix owl: <http://www.w3.org/2002/07/owl#> .");
let _ = writeln!(out, "@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .");
let _ = writeln!(out, "@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .");
let _ = writeln!(out, "@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .");
let _ = writeln!(out, "@prefix sh: <http://www.w3.org/ns/shacl#> .");
let _ = writeln!(out, "@prefix ossie: <{OSSIE_NS}> .");
let _ = writeln!(out, "@prefix : <{base}> .");
let _ = writeln!(out);
// Declared so the provenance terms do not push the graph into OWL Full.
const ANNOTATION_PROPERTIES: &[&str] = &[
"ontologyName",
"specVersion",
"conceptName",
"conceptType",
"extends",
"relationshipName",
"declaringConcept",
"arity",
"roleIndex",
"roleName",
"roleConcept",
"multiplicity",
"verbalizes",
"derivedBy",
"requires",
"aiContext",
"linkClass",
"unaryClass",
"identifyBy",
"ontologyMappings",
"declarationIndex",
];
for term in ANNOTATION_PROPERTIES {
let _ = writeln!(out, "ossie:{term} a owl:AnnotationProperty .");
}
let _ = writeln!(out);
let ontology_iri = base.trim_end_matches(['#', '/']).to_string();
let _ = writeln!(out, "<{ontology_iri}> a owl:Ontology ;");
let _ = writeln!(out, " ossie:ontologyName {} ;", quote(&self.doc.name));
let _ = writeln!(out, " rdfs:label {} ;", quote(&self.doc.name));
if let Some(version) = &self.doc.version {
let _ = writeln!(out, " ossie:specVersion {} ;", quote(version));
}
if let Some(description) = &self.doc.description {
let _ = writeln!(out, " rdfs:comment {} ;", quote(description));
}
if let Some(ai_context) = &self.doc.ai_context {
let _ = writeln!(out, " ossie:aiContext {} ;", quote(&ai_context.to_string()));
}
if let Some(mappings) = &self.doc.ontology_mappings {
let _ = writeln!(
out,
" ossie:ontologyMappings {} ;",
quote(&mappings.to_string())
);
}
for expression in &self.doc.requires {
let _ = writeln!(out, " ossie:requires {} ;", quote(expression));
}
let _ = writeln!(out, " .");
let _ = writeln!(out);
if self.doc.ontology_mappings.is_some() {
self.issue(
"ONTOLOGY_MAPPINGS_NOT_CONVERTED",
self.doc.name.clone(),
"SQL-to-object mappings belong in R2RML; preserved verbatim",
);
}
}
// ----------------------------------------------------------- concepts
fn concept(&mut self, component: &Component) -> Result<(), String> {
if component.concept_type == "ValueType" {
self.value_type(component)
} else {
self.entity_type(component);
Ok(())
}
}
fn entity_type(&mut self, component: &Component) {
let iri = self.concept_iri(&component.concept);
let index = self.declaration_index(&component.concept);
let mut body = String::new();
let _ = writeln!(body, "{iri} a owl:Class ;");
let _ = writeln!(body, " ossie:conceptName {} ;", quote(&component.concept));
let _ = writeln!(body, " ossie:conceptType \"EntityType\" ;");
let _ = writeln!(body, " ossie:declarationIndex {index} ;");
let _ = writeln!(body, " rdfs:label {} ;", quote(&component.concept));
if let Some(description) = &component.description {
let _ = writeln!(body, " rdfs:comment {} ;", quote(description));
}
if component.extends.is_empty() {
// "every entity type implicitly extends the built-in concept Any"
let _ = writeln!(body, " rdfs:subClassOf owl:Thing ;");
} else {
for supertype in &component.extends {
let _ = writeln!(body, " ossie:extends {} ;", quote(supertype));
let target = if supertype == "Any" {
"owl:Thing".to_string()
} else {
self.concept_iri(supertype)
};
let _ = writeln!(body, " rdfs:subClassOf {target} ;");
}
}
for expression in &component.derived_by {
let _ = writeln!(body, " ossie:derivedBy {} ;", quote(expression));
}
for expression in &component.requires {
let _ = writeln!(body, " ossie:requires {} ;", quote(expression));
}
for identifier in &component.identify_by {
let _ = writeln!(body, " ossie:identifyBy {} ;", quote(identifier));
}
// owl:hasKey needs binary identifying relationships; the spec says
// identifying relationships are always binary.
let key_ok = component.identify_by.iter().all(|identifier| {
component
.relationships
.iter()
.any(|r| &r.name == identifier && r.roles.len() == 1)
});
if !component.identify_by.is_empty() && key_ok {
let key: Vec<String> = component
.identify_by
.iter()
.map(|identifier| self.relationship_iri(&component.concept, identifier))
.collect();
let _ = writeln!(body, " owl:hasKey ( {} ) ;", key.join(" "));
}
let _ = writeln!(body, " .");
let _ = writeln!(body);
self.out.push_str(&body);
for _ in &component.derived_by {
self.issue(
"DERIVATION_NOT_EXPRESSIBLE",
component.concept.clone(),
"OWL has no rule construct for deriving a class population",
);
}
for _ in &component.requires {
self.issue(
"REQUIRES_NOT_EXPRESSIBLE",
component.concept.clone(),
"constraint over an entity population is not a datatype facet",
);
}
if !component.identify_by.is_empty() && !key_ok {
self.issue(
"REQUIRES_NOT_EXPRESSIBLE",
component.concept.clone(),
"owl:hasKey needs a binary identifying relationship",
);
}
}
fn value_type(&mut self, component: &Component) -> Result<(), String> {
let iri = self.concept_iri(&component.concept);
let index = self.declaration_index(&component.concept);
let xsd_base = self.xsd_base(&component.concept, &mut Vec::new())?;
let mut own = Vec::new();
let mut unrecognised = 0usize;
for expression in &component.requires {
match parse_requires(expression) {
Some(facet) if facet.subject == component.concept => own.push(facet),
_ => unrecognised += 1,
}
}
let mut body = String::new();
let _ = writeln!(body, "{iri} a rdfs:Datatype ;");
let _ = writeln!(body, " ossie:conceptName {} ;", quote(&component.concept));
let _ = writeln!(body, " ossie:conceptType \"ValueType\" ;");
let _ = writeln!(body, " ossie:declarationIndex {index} ;");
let _ = writeln!(body, " rdfs:label {} ;", quote(&component.concept));
if let Some(description) = &component.description {
let _ = writeln!(body, " rdfs:comment {} ;", quote(description));
}
for supertype in &component.extends {
let _ = writeln!(body, " ossie:extends {} ;", quote(supertype));
}
for expression in &component.derived_by {
let _ = writeln!(body, " ossie:derivedBy {} ;", quote(expression));
}
for expression in &component.requires {
let _ = writeln!(body, " ossie:requires {} ;", quote(expression));
}
if own.is_empty() {
let _ = writeln!(body, " owl:equivalentClass <{xsd_base}> ;");
} else {
let restrictions: Vec<String> = own
.iter()
.map(|facet| format!("[ xsd:{} {} ]", facet.facet, facet.literal))
.collect();
let _ = writeln!(
body,
" owl:equivalentClass [ a rdfs:Datatype ; owl:onDatatype <{xsd_base}> ;\n owl:withRestrictions ( {} ) ] ;",
restrictions.join(" ")
);
}
let _ = writeln!(body, " .");
let _ = writeln!(body);
self.out.push_str(&body);
self.facets.insert(component.concept.clone(), own);
for _ in &component.derived_by {
self.issue(
"DERIVATION_NOT_EXPRESSIBLE",
component.concept.clone(),
"OWL has no rule construct for deriving a datatype population",
);
}
for _ in 0..unrecognised {
self.issue(
"REQUIRES_NOT_EXPRESSIBLE",
component.concept.clone(),
"outside the recognised scalar-comparison fragment",
);
}
Ok(())
}
// ------------------------------------------------------ relationships
fn relationship(
&mut self,
component: &Component,
relationship: &Relationship,
) -> Result<(), String> {
match relationship.roles.len() + 1 {
1 => self.unary(component, relationship),
2 => self.binary(component, relationship)?,
_ => self.nary(component, relationship)?,
}
for _ in &relationship.derived_by {
self.issue(
"DERIVATION_NOT_EXPRESSIBLE",
format!("{}.{}", component.concept, relationship.name),
"OWL has no rule construct for deriving a relationship population",
);
}
for expression in &relationship.requires {
if parse_requires(expression).is_none() {
self.issue(
"REQUIRES_NOT_EXPRESSIBLE",
format!("{}.{}", component.concept, relationship.name),
"outside the recognised scalar-comparison fragment",
);
}
}
Ok(())
}
/// Annotations shared by every relationship shape, regardless of arity.
fn relationship_common(&self, component: &Component, relationship: &Relationship) -> String {
let index = component
.relationships
.iter()
.position(|r| r.name == relationship.name)
.unwrap_or(0);
let mut body = String::new();
let _ = writeln!(body, " ossie:relationshipName {} ;", quote(&relationship.name));
let _ = writeln!(body, " ossie:declaringConcept {} ;", quote(&component.concept));
let _ = writeln!(body, " ossie:arity {} ;", relationship.roles.len() + 1);
let _ = writeln!(body, " ossie:declarationIndex {index} ;");
let _ = writeln!(
body,
" rdfs:label {} ;",
quote(&format!("{}.{}", component.concept, relationship.name))
);
if let Some(description) = &relationship.description {
let _ = writeln!(body, " rdfs:comment {} ;", quote(description));
}
for pattern in &relationship.verbalizes {
let _ = writeln!(body, " ossie:verbalizes {} ;", quote(pattern));
}
if let Some(multiplicity) = &relationship.multiplicity {
let _ = writeln!(body, " ossie:multiplicity {} ;", quote(multiplicity));
}
for expression in &relationship.derived_by {
let _ = writeln!(body, " ossie:derivedBy {} ;", quote(expression));
}
for expression in &relationship.requires {
let _ = writeln!(body, " ossie:requires {} ;", quote(expression));
}
body
}
fn unary(&mut self, component: &Component, relationship: &Relationship) {
let iri = self.relationship_iri(&component.concept, &relationship.name);
let concept_iri = self.concept_iri(&component.concept);
let common = self.relationship_common(component, relationship);
let _ = writeln!(self.out, "{iri} a owl:Class ;");
let _ = writeln!(self.out, " ossie:unaryClass true ;");
let _ = writeln!(self.out, " rdfs:subClassOf {concept_iri} ;");
self.out.push_str(&common);
let _ = writeln!(self.out, " .");
let _ = writeln!(self.out);
self.issue(
"UNARY_RELATIONSHIP_AS_CLASS",
format!("{}.{}", component.concept, relationship.name),
"a unary fact type becomes a subclass; the relationship is no longer a property",
);
}
fn binary(&mut self, component: &Component, relationship: &Relationship) -> Result<(), String> {
let role = &relationship.roles[0];
let is_value = self.is_value_type(&role.concept)?;
let iri = self.relationship_iri(&component.concept, &relationship.name);
let concept_iri = self.concept_iri(&component.concept);
let range = self.range_iri(&role.concept);
let common = self.relationship_common(component, relationship);
let multiplicity = relationship.multiplicity.as_deref();
let mut types = vec![if is_value {
"owl:DatatypeProperty"
} else {
"owl:ObjectProperty"
}];
if matches!(multiplicity, Some("ManyToOne") | Some("OneToOne")) {
types.push("owl:FunctionalProperty");
}
if multiplicity == Some("OneToOne") && !is_value {
types.push("owl:InverseFunctionalProperty");
}
let _ = writeln!(self.out, "{iri} a {} ;", types.join(" , "));
let _ = writeln!(self.out, " rdfs:domain {concept_iri} ;");
let _ = writeln!(self.out, " rdfs:range {range} ;");
let _ = writeln!(self.out, " ossie:roleIndex 1 ;");
let _ = writeln!(self.out, " ossie:roleConcept {} ;", quote(&role.concept));
if let Some(role_name) = &role.name {
let _ = writeln!(self.out, " ossie:roleName {} ;", quote(role_name));
}
self.out.push_str(&common);
let _ = writeln!(self.out, " .");
let _ = writeln!(self.out);
if multiplicity == Some("OneToOne") && is_value {
// OWL 2 DL has no InverseFunctionalDataProperty: it costs decidability
// and exists only in OWL Full. SHACL carries the constraint instead.
self.issue(
"INVERSE_FUNCTIONAL_DATA_PROPERTY",
format!("{}.{}", component.concept, relationship.name),
"OneToOne onto a ValueType is not expressible in OWL 2 DL; emitted as sh:sparql",
);
}
Ok(())
}
fn nary(&mut self, component: &Component, relationship: &Relationship) -> Result<(), String> {
let iri = self.relationship_iri(&component.concept, &relationship.name);
let common = self.relationship_common(component, relationship);
let _ = writeln!(self.out, "{iri} a owl:Class ;");
let _ = writeln!(self.out, " ossie:linkClass true ;");
self.out.push_str(&common);
let _ = writeln!(self.out, " .");
let _ = writeln!(self.out);
for (index, (player, role_name)) in self.roles(component, relationship).iter().enumerate() {
let is_value = self.is_value_type(player)?;
let role_iri = self.role_property_iri(&component.concept, &relationship.name, index);
let range = self.range_iri(player);
let kind = if is_value {
"owl:DatatypeProperty"
} else {
"owl:ObjectProperty"
};
let _ = writeln!(self.out, "{role_iri} a {kind} , owl:FunctionalProperty ;");
let _ = writeln!(self.out, " rdfs:domain {iri} ;");
let _ = writeln!(self.out, " rdfs:range {range} ;");
let _ = writeln!(self.out, " ossie:roleIndex {index} ;");
let _ = writeln!(self.out, " ossie:roleConcept {} ;", quote(player));
if let Some(name) = role_name {
let _ = writeln!(self.out, " ossie:roleName {} ;", quote(name));
}
let _ = writeln!(self.out, " .");
let _ = writeln!(self.out);
}
self.issue(
"NARY_RELATIONSHIP_REIFIED",
format!("{}.{}", component.concept, relationship.name),
"reified into a link class (W3C n-ary relations pattern 1)",
);
if relationship.multiplicity.as_deref() == Some("ManyToOne") {
self.issue(
"NARY_MULTIPLICITY_SHACL_ONLY",
format!("{}.{}", component.concept, relationship.name),
"a tuple functional dependency is beyond OWL cardinality restrictions",
);
}
Ok(())
}
// ------------------------------------------------------------- SHACL
fn node_shape(&mut self, component: &Component) -> Result<(), String> {
let shape = format!("{}Shape", self.concept_iri(&component.concept).trim_end_matches('>'));
let shape = format!("{shape}>");
let concept_iri = self.concept_iri(&component.concept);
let mut properties = Vec::new();
for relationship in &component.relationships {
if relationship.roles.len() != 1 {
continue;
}
let role = &relationship.roles[0];
let path = self.relationship_iri(&component.concept, &relationship.name);
let mut shape_body = format!(" sh:path {path} ;\n sh:name {} ;\n", quote(&relationship.name));
if self.is_value_type(&role.concept)? {
// sh:datatype compares the literal's own datatype IRI and does no
// datatype entailment, so a user-declared value type must resolve
// to its XSD base or every real graph would be rejected. The value
// type's facets ride along on the same property shape.
let xsd_base = self.xsd_base(&role.concept, &mut Vec::new())?;
let _ = writeln!(shape_body, " sh:datatype <{xsd_base}> ;");
for facet in self.facets.get(&role.concept).into_iter().flatten() {
let _ = writeln!(shape_body, " sh:{} {} ;", facet.facet, facet.literal);
}
} else {
let _ = writeln!(shape_body, " sh:class {} ;", self.range_iri(&role.concept));
}
if matches!(
relationship.multiplicity.as_deref(),
Some("ManyToOne") | Some("OneToOne")
) {
let _ = writeln!(shape_body, " sh:maxCount 1 ;");
}
properties.push(format!(" sh:property [\n{shape_body} ] ;"));
}
let _ = writeln!(self.out, "{shape} a sh:NodeShape ;");
let _ = writeln!(self.out, " sh:targetClass {concept_iri} ;");
for property in properties {
let _ = writeln!(self.out, "{property}");
}
let _ = writeln!(self.out, " .");
let _ = writeln!(self.out);
for relationship in &component.relationships {
if relationship.roles.len() == 1
&& relationship.multiplicity.as_deref() == Some("OneToOne")
&& self.is_value_type(&relationship.roles[0].concept)?
{
self.uniqueness_constraint(component, relationship);
}
if relationship.roles.len() >= 2 {
self.link_class_shape(component, relationship)?;
}
}
Ok(())
}
/// SHACL replacement for the `InverseFunctionalDataProperty` OWL 2 DL forbids.
fn uniqueness_constraint(&mut self, component: &Component, relationship: &Relationship) {
let path = self.relationship_iri(&component.concept, &relationship.name);
let path = path.trim_start_matches('<').trim_end_matches('>').to_string();
let shape = format!(
"<{}{}.{}Unique>",
self.base,
iri_escape(&component.concept),
iri_escape(&relationship.name)
);
let concept_iri = self.concept_iri(&component.concept);
let select = format!(
"SELECT $this ?value WHERE {{ $this <{path}> ?value . ?other <{path}> ?value . FILTER (?other != $this) }}"
);
let message = format!(
"{}.{} is OneToOne: each value identifies at most one {}",
component.concept, relationship.name, component.concept
);
let _ = writeln!(self.out, "{shape} a sh:NodeShape ;");
let _ = writeln!(self.out, " sh:targetClass {concept_iri} ;");
let _ = writeln!(self.out, " sh:sparql [ a sh:SPARQLConstraint ;");
let _ = writeln!(self.out, " sh:message {} ;", quote(&message));
let _ = writeln!(self.out, " sh:select {} ] ;", quote(&select));
let _ = writeln!(self.out, " .");
let _ = writeln!(self.out);
self.sparql_constraints += 1;
}
fn link_class_shape(
&mut self,
component: &Component,
relationship: &Relationship,
) -> Result<(), String> {
let link_class = self.relationship_iri(&component.concept, &relationship.name);
let shape = format!(
"<{}{}.{}Shape>",
self.base,
iri_escape(&component.concept),
iri_escape(&relationship.name)
);
let mut relationship_facets: BTreeMap<String, Vec<&Facet>> = BTreeMap::new();
let parsed: Vec<Facet> = relationship
.requires
.iter()
.filter_map(|e| parse_requires(e))
.collect();
for facet in &parsed {
relationship_facets
.entry(facet.subject.clone())
.or_default()
.push(facet);
}
let roles = self.roles(component, relationship);
let mut properties = Vec::new();
let mut role_iris = Vec::new();
for (index, (player, role_name)) in roles.iter().enumerate() {
let role_iri = self.role_property_iri(&component.concept, &relationship.name, index);
role_iris.push(role_iri.trim_start_matches('<').trim_end_matches('>').to_string());
let label = role_name.clone().unwrap_or_else(|| player.clone());
let mut body = format!(" sh:path {role_iri} ;\n sh:name {} ;\n", quote(&label));
// Links do not contain nulls and each role is filled exactly once.
let _ = writeln!(body, " sh:minCount 1 ;");
let _ = writeln!(body, " sh:maxCount 1 ;");
if self.is_value_type(player)? {
let xsd_base = self.xsd_base(player, &mut Vec::new())?;
let _ = writeln!(body, " sh:datatype <{xsd_base}> ;");
for facet in self.facets.get(player).into_iter().flatten() {
let _ = writeln!(body, " sh:{} {} ;", facet.facet, facet.literal);
}
} else {
let _ = writeln!(body, " sh:class {} ;", self.range_iri(player));
}
for facet in relationship_facets.get(&label).into_iter().flatten() {
let _ = writeln!(body, " sh:{} {} ;", facet.facet, facet.literal);
}
properties.push(format!(" sh:property [\n{body} ] ;"));
}
let _ = writeln!(self.out, "{shape} a sh:NodeShape ;");
let _ = writeln!(self.out, " sh:targetClass {link_class} ;");
for property in properties {
let _ = writeln!(self.out, "{property}");
}
if relationship.multiplicity.as_deref() == Some("ManyToOne") && role_iris.len() >= 2 {
// The last role is functionally determined by the tuple of the others.
// OWL cardinality restrictions constrain one property at a time and
// cannot quantify over a tuple, so this is SHACL-SPARQL only.
let (dependent, determinants) = role_iris.split_last().expect("checked len >= 2");
let this_patterns: Vec<String> = determinants
.iter()
.enumerate()
.map(|(i, p)| format!("$this <{p}> ?r{i} ."))
.collect();
let other_patterns: Vec<String> = determinants
.iter()
.enumerate()
.map(|(i, p)| format!("?other <{p}> ?r{i} ."))
.collect();
let select = format!(
"SELECT $this WHERE {{ {} $this <{dependent}> ?last . {} ?other <{dependent}> ?otherLast . FILTER (?other != $this && ?otherLast != ?last) }}",
this_patterns.join(" "),
other_patterns.join(" ")
);
let message = format!(
"{}.{} is ManyToOne: the last role is functionally determined by the tuple of the preceding roles",
component.concept, relationship.name
);
let _ = writeln!(self.out, " sh:sparql [ a sh:SPARQLConstraint ;");
let _ = writeln!(self.out, " sh:message {} ;", quote(&message));
let _ = writeln!(self.out, " sh:select {} ] ;", quote(&select));
self.sparql_constraints += 1;
}
let _ = writeln!(self.out, " .");
let _ = writeln!(self.out);
Ok(())
}
// --------------------------------------------------------- utilities
fn roles(&self, component: &Component, relationship: &Relationship) -> Vec<(String, Option<String>)> {
let mut roles = vec![(component.concept.clone(), None)];
for role in &relationship.roles {
roles.push((role.concept.clone(), role.name.clone()));
}
roles
}
fn declaration_index(&self, concept: &str) -> usize {
self.doc
.ontology
.iter()
.position(|c| c.concept == concept)
.unwrap_or(0)
}
fn concept_iri(&self, name: &str) -> String {
format!("<{}{}>", self.base, iri_escape(name))
}
fn relationship_iri(&self, concept: &str, relationship: &str) -> String {
format!(
"<{}{}.{}>",
self.base,
iri_escape(concept),
iri_escape(relationship)
)
}
fn role_property_iri(&self, concept: &str, relationship: &str, index: usize) -> String {
format!(
"<{}{}.{}-role{index}>",
self.base,
iri_escape(concept),
iri_escape(relationship)
)
}
fn range_iri(&self, name: &str) -> String {
if let Some(xsd) = builtin_xsd(name) {
return format!("<{xsd}>");
}
if name == "Any" {
return "owl:Thing".to_string();
}
self.concept_iri(name)
}
fn is_value_type(&self, name: &str) -> Result<bool, String> {
if builtin_xsd(name).is_some() {
return Ok(true);
}
if name == "Any" {
return Ok(false);
}
match self.by_name.get(name) {
Some(component) => Ok(component.concept_type == "ValueType"),
None => Err(format!("role references undeclared concept {name:?}")),
}
}
/// Walk `extends` until a built-in value type is reached.
fn xsd_base(&self, name: &str, seen: &mut Vec<String>) -> Result<&'static str, String> {
if let Some(xsd) = builtin_xsd(name) {
return Ok(xsd);
}
if seen.iter().any(|s| s == name) {
return Err(format!("cyclic extends chain through value type {name:?}"));
}
seen.push(name.to_string());
let component = self
.by_name
.get(name)
.ok_or_else(|| format!("value type {name:?} is not declared"))?;
for supertype in &component.extends {
if let Ok(xsd) = self.xsd_base(supertype, seen) {
return Ok(xsd);
}
}
// "Any value type concept must either directly or indirectly extend one of
// the built-in value types", so an unrooted chain is a document error.
Err(format!(
"value type {name:?} does not extend a built-in value type"
))
}
fn issue(&mut self, kind: &'static str, element: String, detail: &'static str) {
self.issues.push(Issue {
kind,
element,
detail,
});
}
}
/// Parse an Ossie ontology document from YAML (or JSON, which is a YAML subset).
pub fn parse_document(source: &str) -> Result<OssieDocument, String> {
serde_yaml::from_str(source).map_err(|e| format!("cannot parse Ossie ontology document: {e}"))
}
#[cfg(test)]
mod tests {
use super::*;
const DOC: &str = r#"
version: 0.2.0.dev0
name: Tiny
ontology:
- concept: SocialSecurityNr
type: ValueType
extends: [Integer]
requires: ["0 < SocialSecurityNr", "SocialSecurityNr <= 999999999"]
- concept: Salary
type: ValueType
extends: [Decimal]
- concept: NrDays
type: ValueType
extends: [Integer]
- concept: Person
type: EntityType
identify_by: [nr]
relationships:
- name: nr
roles: [{concept: SocialSecurityNr}]
multiplicity: OneToOne
verbalizes: ["{Person} is identified by {SocialSecurityNr}"]
- name: earns
roles: [{concept: Salary}]
multiplicity: ManyToOne
verbalizes: ["{Person} earns {Salary}"]
- name: files_married_joint
verbalizes: ["{Person} files married filing joint"]
- concept: Store
type: EntityType
relationships:
- name: ships_to_in_days
roles:
- concept: Store
name: destination
- concept: NrDays
multiplicity: ManyToOne
verbalizes: ["{Store} ships to {Store:destination} in {NrDays}"]
"#;
fn convert() -> OssieConversion {
let doc = parse_document(DOC).expect("parses");
to_owl_shacl(&doc, Some("https://example.org/o#"), true).expect("converts")
}
#[test]
fn entity_and_value_types_land_on_the_right_owl_construct() {
let ttl = convert().turtle;
assert!(ttl.contains("<https://example.org/o#Person> a owl:Class ;"));
assert!(ttl.contains("<https://example.org/o#Salary> a rdfs:Datatype ;"));
}
#[test]
fn value_type_facets_become_a_datatype_restriction() {
let ttl = convert().turtle;
assert!(ttl.contains("owl:onDatatype <http://www.w3.org/2001/XMLSchema#integer>"));
assert!(ttl.contains("xsd:minExclusive \"0\"^^<http://www.w3.org/2001/XMLSchema#integer>"));
assert!(
ttl.contains("xsd:maxInclusive \"999999999\"^^<http://www.w3.org/2001/XMLSchema#integer>")
);
}
#[test]
fn value_type_without_facets_aliases_its_xsd_base() {
let ttl = convert().turtle;
assert!(ttl
.contains("<https://example.org/o#Salary> a rdfs:Datatype ;"));
assert!(ttl.contains("owl:equivalentClass <http://www.w3.org/2001/XMLSchema#decimal>"));
}
#[test]
fn many_to_one_is_functional() {
let ttl = convert().turtle;
assert!(ttl.contains("<https://example.org/o#Person.earns> a owl:DatatypeProperty , owl:FunctionalProperty ;"));
}
#[test]
fn one_to_one_onto_a_value_type_is_never_inverse_functional() {
let result = convert();
// OWL 2 DL forbids InverseFunctionalDataProperty.
assert!(!result.turtle.contains("owl:InverseFunctionalProperty"));
assert!(result
.issues
.iter()
.any(|i| i.kind == "INVERSE_FUNCTIONAL_DATA_PROPERTY" && i.element == "Person.nr"));
assert!(result.turtle.contains("sh:SPARQLConstraint"));
}
#[test]
fn identify_by_becomes_has_key() {
let ttl = convert().turtle;
assert!(ttl.contains("owl:hasKey ( <https://example.org/o#Person.nr> )"));
}
#[test]
fn unary_relationship_becomes_a_subclass() {
let result = convert();
assert!(result
.turtle
.contains("<https://example.org/o#Person.files_married_joint> a owl:Class ;"));
assert!(result.turtle.contains("ossie:unaryClass true"));
assert!(result.issues.iter().any(|i| i.kind == "UNARY_RELATIONSHIP_AS_CLASS"));
}
#[test]
fn ternary_relationship_is_reified_with_ordered_roles() {
let result = convert();
assert!(result.turtle.contains("ossie:linkClass true"));
assert!(result
.turtle
.contains("<https://example.org/o#Store.ships_to_in_days-role0>"));
assert!(result
.turtle
.contains("<https://example.org/o#Store.ships_to_in_days-role2>"));
assert!(result.issues.iter().any(|i| i.kind == "NARY_RELATIONSHIP_REIFIED"));
assert!(result
.issues
.iter()
.any(|i| i.kind == "NARY_MULTIPLICITY_SHACL_ONLY"));
}
#[test]
fn nary_multiplicity_emits_a_tuple_dependency() {
let ttl = convert().turtle;
assert!(ttl.contains("?otherLast != ?last"));
}
#[test]
fn role_names_survive() {
let ttl = convert().turtle;
assert!(ttl.contains("ossie:roleName \"destination\""));
}
#[test]
fn counts_are_reported() {
let result = convert();
assert_eq!(result.concepts, 5);
assert_eq!(result.entity_types, 2);
assert_eq!(result.value_types, 3);
assert_eq!(result.relationships, 4);
assert_eq!(result.sparql_constraints, 2);
}
#[test]
fn requires_parser_accepts_the_recognised_fragment() {
let facet = parse_requires("0 < X").expect("recognised");
assert_eq!(facet.subject, "X");
assert_eq!(facet.facet, "minExclusive");
let facet = parse_requires("X <= 10").expect("recognised");
assert_eq!(facet.facet, "maxInclusive");
let facet = parse_requires("Salary >= 0.0").expect("recognised");
assert_eq!(facet.facet, "minInclusive");
assert!(facet.literal.contains("decimal"));
}
#[test]
fn requires_parser_declines_everything_else() {
assert!(parse_requires("Item.offers_in(Store)").is_none());
assert!(parse_requires("A < B").is_none());
assert!(parse_requires("TaxRate == 10.0").is_none());
assert!(parse_requires("EXISTS ( Person.earns )").is_none());
}
#[test]
fn undeclared_role_concept_is_rejected() {
let doc = parse_document(
"version: 0.2.0.dev0\nname: B\nontology:\n - concept: A\n type: EntityType\n relationships:\n - name: r\n roles: [{concept: Missing}]\n verbalizes: [\"x\"]\n",
)
.expect("parses");
let err = to_owl_shacl(&doc, None, true).expect_err("must fail");
assert!(err.contains("undeclared concept"));
}
#[test]
fn unrooted_value_type_is_rejected() {
let doc = parse_document(
"version: 0.2.0.dev0\nname: B\nontology:\n - concept: V\n type: ValueType\n",
)
.expect("parses");
let err = to_owl_shacl(&doc, None, true).expect_err("must fail");
assert!(err.contains("does not extend a built-in value type"));
}
#[test]
fn emitted_turtle_parses_into_the_store() {
// The whole point is that the rest of this crate can consume the output,
// so the emitted Turtle must survive oxigraph's parser verbatim.
let result = convert();
let store = crate::graph::GraphStore::new();
let triples = store
.load_turtle(&result.turtle, None)
.expect("emitted Turtle must parse");
assert!(
triples > 50,
"expected a substantial graph, got {triples} triples"
);
}
#[test]
fn literals_are_escaped() {
let doc = parse_document(
"version: 0.2.0.dev0\nname: B\nontology:\n - concept: A\n type: EntityType\n description: 'has \"quotes\" and \\ backslash'\n",
)
.expect("parses");
let ttl = to_owl_shacl(&doc, Some("https://example.org/o#"), true)
.expect("converts")
.turtle;
assert!(ttl.contains("\\\"quotes\\\""));
assert!(ttl.contains("\\\\ backslash"));
}
}