What the OWL Coder Knows: The IR Map, the Extras, the Ledger

Ask a schema converter what it does with owl:Restriction and you learn most of what you need to know about it. Many treat OWL as a serialization problem — emit classes and properties, drop the axioms — so "required" and "single-valued" evaporate at the border. CoreModels treats it as a semantics problem: required and cardinality ride as owl:Restriction subclass axioms, OWL's own carrier, in both directions. That decision propagates through everything below.

This is the complete reference for the owl format key: what maps structurally, what rides in the annotation extras, the full lossiness inventory, and what a round trip preserves.

Everything on the CoreModels transform surface passes through one intermediate representation: Types (with single inheritance), Elements (typed, owned by types, carrying required and cardinality), Taxonomies (ordered term trees), Relations, Components, and an annotation bag per node holding provenance, cross-standard mapsTo assertions, and dotted-key extras. The OWL coder bridges that model and a Turtle document, both ways.

The structural map

IR construct	OWL/Turtle form
Schema	an owl:Ontology subject (a full IRI minted under the entity namespace from the schema label) with rdfs:label
Type	owl:Class with rdfs:label, plus rdfs:comment when known
Type inheritance	rdfs:subClassOf between two named classes
Element with a primitive value	owl:DatatypeProperty with an xsd: rdfs:range
Element referencing a Type or Taxonomy	owl:ObjectProperty with that class as rdfs:range
Element owned by one Type	rdfs:domain naming the owning class
Element reused across Types	rdfs:domain [ a owl:Class ; owl:unionOf ( … ) ]
Required	rdfs:subClassOf [ a owl:Restriction ; owl:onProperty p ; owl:minCardinality "1"^^xsd:nonNegativeInteger ]
Single-valued	the same shape with owl:maxCardinality "1"^^xsd:nonNegativeInteger
Collection with a max bound	owl:maxCardinality "n"^^xsd:nonNegativeInteger
Taxonomy	a skos:ConceptScheme plus an owl:Class that is rdfs:subClassOf skos:Concept
Taxonomy term	an individual typed with both the taxonomy class and skos:Concept, carrying skos:inScheme and skos:prefLabel
Term hierarchy	skos:broader
Term cross-reference	skos:exactMatch
mapsTo on a Type or Element	the entity's own IRI, plus owl:equivalentClass / owl:equivalentProperty for the remainder
Relation	narrowed to rdfs:seeAlso between the endpoints, with a ledger record
Component	not exported; recorded as a structural drop

Decoding runs the same table backwards, with one classification step first: a class declaring rdfs:subClassOf skos:Concept becomes a Taxonomy, and everything else typed owl:Class becomes a Type. Taxonomies are built before types and properties, so an rdfs:range naming a concept class resolves to a taxonomy reference rather than a type reference.

Identity: every entity is already an IRI

This is the property OWL has that no other format on the surface does, and the coder leans on it in both directions.

Decoding. Each class and property contributes its own expanded IRI to the node's mapsTo set, recorded under the prefix it was written with. owl:equivalentClass, owl:equivalentProperty, and skos:exactMatch objects are added alongside under the standard owl. Decode ex:Product a owl:Class ; owl:equivalentClass schema:Product and the resulting Type carries both https://example.org/catalog#Product (standard ex) and https://schema.org/Product (standard owl) — identity you can match on later when aligning against another model.

Encoding. The entity IRI is chosen by three rules in order:

1. If the node's id already has the shape of a prefixed name, it is used as-is. This is what makes decode-then-encode exact.
2. Otherwise, the node's mapsTo URIs are reversed into a compact prefixed name via the longest matching namespace in the prefix map. A Type that arrived from JSON Schema carrying mapsTo → https://schema.org/Article therefore exports as schema:Article: the identity assertion becomes the name.
3. Otherwise a fresh name is minted by PascalCasing the label under the coder's own entity namespace, written here as ex: → https://coremodels.example.com/ns/.

A mapsTo URI that no namespace covers is emitted as a full IRI in angle brackets — owl:equivalentClass <http://purl.org/dc/dcmitype/Text>. The node's own IRI is skipped in the equivalence list, since naming the entity by it already asserts that identity.

The prefix map is assembled in layers: built-in defaults (rdf, rdfs, owl, xsd, skos, schema for schema.org, and the ex: minting namespace), overlaid with any prefixes the JSON-LD coder preserved — read, never written, so a model that arrived as JSON-LD exports under the prefixes it came with — overlaid with this coder's own preserved prefixes. Only prefixes actually used in the output appear in the header, sorted — plus the four core declarations (rdf, rdfs, owl, xsd), which are always emitted. The prefixed-name test in rule 1 is intentionally narrow — a colon after position zero, and no space, pipe, or dot — so that identifiers from other coders are never mistaken for prefixed names.

Cardinality: open world, honest bounds

The open-world default. A decoded property with no restrictions is optional and multi-valued. That is not a converter preference; it is what an unrestricted property means in RDF. If a downstream format shows a surprising optional array, the ontology never said otherwise.

Restrictions are the carrier, both directions. owl:minCardinality of 1 or more makes the element required. owl:maxCardinality 1 makes it single-valued; a larger maximum becomes the collection's upper bound. owl:cardinality n sets both bounds at once. Multiple restriction axioms on the same property merge strongest-wins: the largest minimum, the smallest maximum. A minimum above 1 is also carried through as the collection's lower bound.

One honest gap on the way out. OWL can say "at least one" through minCardinality 1, but a collection whose lower bound is higher — at least two keywords, say — has no carrier the encoder emits beyond that floor. The bound is relaxed and a ConstraintRelaxation record names the exact element:

[ConstraintRelaxation] Type[Doc].keyword: minItems 2 has no OWL carrier beyond the
min-cardinality-1 restriction; the bound is relaxed.

Datatypes

Decode: xsd: → IR	Encode: IR → xsd:
integer, int, long, short, nonNegativeInteger → Integer	Integer → xsd:integer
double, decimal, float → Double	Double → xsd:double
boolean → Boolean	Boolean → xsd:boolean
dateTime, date, time → DateTime	DateTime → xsd:dateTime
everything else, including string and anyURI → String	String and RichText → xsd:string

The encode column looks lossier than it is: the decoder stashes the original range verbatim and the encoder prefers it. A property declared rdfs:range xsd:decimal decodes to the Double primitive and keeps xsd:decimal in the extras, so re-export says xsd:decimal. The generic column applies only to models that never came from OWL.

What rides the extras

Fidelity beyond the structural map travels in dotted, coder-prefixed extras — never smuggled into another format's output, always available for exact re-emit.

Key	Scope	Carries
owl.prefix.<prefix>	schema	each prefix → namespace IRI from the decoded document
owl.comment	any node	the rdfs:comment text, re-emitted verbatim
owl.range	element	the original rdfs:range exactly as written, whenever the range is not a decoded class
owl.scheme	taxonomy	a skos:ConceptScheme IRI that differs from the default naming convention
jsonld.context.<prefix>	schema	read (never written) from the JSON-LD coder, for prefix continuity

The comment channel cooperates across coders on export: with no preserved OWL comment, the encoder falls back to a description another coder stashed, then to a SQL column comment, then to the node's instruction annotation — so human documentation reaches rdfs:comment whatever format the model came from.

The lossiness inventory

Export — what OWL cannot carry:

Trigger	Kind	What the record says
Component	StructuralDrop	OWL has no curated-view construct; the component projection is not exported
Element owned by no Type	StructuralDrop	exported without an rdfs:domain
RichText value	TypeApproximation	rich text approximated as xsd:string
Collection lower bound above the required floor	ConstraintRelaxation	the bound is relaxed
Taxonomy marked external-reference	ConstraintRelaxation	the directive has no OWL carrier; exported as a full concept scheme
Every Relation	SemanticNarrowing	narrowed to rdfs:seeAlso; the group's semantics are not expressible in OWL

Import — what real-world Turtle brings:

Trigger	Kind	Behavior
Well-formed triples outside the schema vocabulary	SemanticNarrowing	counted, reported as one summarized record — never an error
Language-tagged or repeated labels/comments	SemanticNarrowing	first lexical form kept, alternatives recorded
Several rdfs:subClassOf parents	SemanticNarrowing	narrowed to the single IR parent
rdfs:subClassOf or rdfs:domain target that is not a decoded class	SemanticNarrowing	the link or membership is dropped, naming the target
Several rdfs:range values	SemanticNarrowing	the first is kept, and named
rdfs:range outside xsd: that is not a decoded class	TypeApproximation	approximated as String, original kept in owl.range
Object property with no rdfs:range	TypeApproximation	approximated as String
skos:broader target outside the taxonomy	SemanticNarrowing	the hierarchy link is dropped

Errors are reserved for documents that cannot be parsed at all — an empty file, an unterminated literal, an unclosed IRI, a truncated statement. They arrive on path $ — with a line number whenever there is a line to point at, for example Line 1: Unclosed IRI reference (missing '>'). — and never as an exception.

Round-trip fidelity

Encode a model to Turtle, decode it, and encode it again: the second document is byte-identical to the first. What survives a cycle exactly: labels; comments; the parent/child class link; required and single-valued facts, through the restriction axioms; a collection's upper bound; every mapsTo URI on types, elements, and terms; shared-element ownership across several types, through the union domain; the taxonomy's terms, hierarchy, and skos:exactMatch links; and the prefixes for every namespace the output uses.

What normalizes harmlessly: a bare owl:minCardinality 1 is re-emitted as "1"^^xsd:nonNegativeInteger; comma-separated rdfs:subClassOf lists become separate ; clauses; and a prefix declared but unused is not re-emitted.

Edge cases worth knowing

• A plain-SKOS document decodes. A skos:ConceptScheme with no owl:Class carrier still becomes a taxonomy — the scheme itself plays that role, and its members are the concepts pointing at it with skos:inScheme.
• rdfs:subClassOf owl:Thing is ignored, not reported. It says nothing.
• rdfs:seeAlso closes the loop. Relations export as rdfs:seeAlso; on import, rdfs:seeAlso between two decoded schema nodes is rebuilt into a relation group, deduplicated. The wire form round-trips even though the export still records the narrowing — the group's original meaning genuinely is gone.
• The default : prefix is a lossy choice. An entity written as :Person decodes with the id :Person, but a leading colon fails the prefixed-name test, so its IRI is not lifted into mapsTo and export re-mints it under ex:. Declare a named prefix and the identity survives.
• Declare the namespaces you intend to map into. The encoder emits @prefix lines only for prefixes it can resolve from the model's preserved prefix map, so a mapping that retargets entities into a namespace your source never declared will use that prefix without declaring it. Adding the declaration to the source — even unused — makes the output self-contained.
• Unrecognized blank nodes are counted, not guessed at. A blank node under rdfs:subClassOf that is not a restriction stays unconsumed and joins the summarized ignored-triple count.

The theme across all of it: OWL is expressive enough to carry most of the model natively, and wherever either side falls short the gap is written down — in the ledger, or in an extras key that lets export restore what decode had to approximate.

For hands-on usage of this coder over HTTP and MCP, start with the OWL quickstart in the CoreModels documentation.