Inferal TypeSpec Versioning Ontology

The TypeSpec Versioning Ontology defines RDF terms for API versions, predecessor chains, merged ontology coverage, and version-change annotations emitted by Inferal Relay from TypeSpec versioning metadata.

This is an unofficial 0.1 Editor's Draft maintained in the Inferal ontology repository. The vocabulary mirrors the versioning model used by Inferal Relay RDF emitters and is intended to document the existing tspv namespace used in generated service ontologies.

Feedback should be sent to contact@inferal.com.

A TypeSpec versioning data graph is an RDF graph that uses the terms in this specification to describe API versions or version-scoped changes. Conforming data graphs MUST satisfy the term constraints in this document. The accompanying SHACL shapes [[SHACL]] provide a machine-checkable validation profile for the same constraints.

A TypeSpec versioning processor is software that consumes version chains or change annotations in a TypeSpec versioning data graph. A conforming processor MUST interpret tspv:previousVersion as an immediate predecessor edge and MUST NOT treat a generation timestamp as an API version unless that timestamp is explicitly modeled as a tspv:Version.

Namespace

Prefix	IRI
`tspv`	`https://relay.inferal.com/ontology/typespec/versioning/`

This namespace is intentionally retained from the Relay emitter output. The ontology library publishes the vocabulary as a module without rewriting existing generated Relay RDF.

Artifacts

The base artifact is RDFS-oriented Turtle. The OWL addendum imports the base artifact and supplies OWL class, object property, and datatype property typing for consumers that need OWL vocabulary typing.

Relationship To Generic Versioning

This module mirrors TypeSpec API version metadata emitted by Inferal Relay. It intentionally does not import [[INFERAL-VERSIONING]], does not declare tspv:Version as a subclass of ver:VersionIdentifier, and does not declare tspv:previousVersion as a subproperty of ver:greaterThanVersion.

The generic Versioning ontology requires version identifiers to state a lexical version text and exactly one version ordering. Existing Relay TypeSpec graphs do not guarantee those generic fields for every tspv:Version, so the base vocabulary avoids making all TypeSpec version nodes subject to the generic Versioning SHACL profile.

Consumers that add ver:versionText and ver:inVersionOrdering to TypeSpec version nodes MAY use queries/materialize-versioning-links.rq to materialize each tspv:previousVersion edge as a newer-to-older adjacent ver:greaterThanVersion edge within the shared ordering.

Change Annotation Scope

The change properties in this module model Relay's flattened TypeSpec versioning annotations. A property such as tspv:renamedFrom, paired with tspv:renamedInVersion, records one preserved rename assertion on the generated RDF resource. It is not a complete event log for every historical rename, type change, requiredness change, or return-type change that may have occurred across all TypeSpec versions.

Graphs that need repeated change history SHOULD mint explicit change-event resources in an extension vocabulary and link those events to tspv:Version nodes. The base Relay vocabulary keeps max-count constraints on the flattened properties so generated annotations remain unambiguous.

Term Index

This index links to the normative definition section for each term in the tspv namespace.

Term	Kind	Normative role
`tspv:Version`	Class	An API version in a TypeSpec version chain.
`tspv:VersionedResource`	Class	A generated resource or ontology artifact with TypeSpec version metadata.
`tspv:previousVersion`	Property	Immediate predecessor relation between two API versions.
`tspv:coversVersion`	Property	Associates a merged ontology with an API version it covers.
`tspv:addedInVersion`	Property	Version in which a resource was introduced.
`tspv:removedInVersion`	Property	Version in which a resource was removed.
`tspv:renamedFrom`	Property	Previous name of a renamed resource.
`tspv:renamedInVersion`	Property	Version in which a resource was renamed.
`tspv:madeOptionalInVersion`	Property	Version in which a property became optional.
`tspv:madeRequiredInVersion`	Property	Version in which a property became required.
`tspv:typeChangedFrom`	Property	Previous property type before a type change.
`tspv:typeChangedInVersion`	Property	Version in which a property type changed.
`tspv:returnTypeChangedFrom`	Property	Previous operation return type before a return type change.
`tspv:returnTypeChangedInVersion`	Property	Version in which an operation return type changed.

Term Definitions

The following sections define each vocabulary term. The RDFS artifact is the base vocabulary. The OWL addendum preserves these meanings and only adds OWL class, object property, or datatype property typing.

`tspv:Version`

IRI	`https://relay.inferal.com/ontology/typespec/versioning/Version`
RDFS kind	`rdfs:Class`
OWL addendum kind	`owl:Class`

A tspv:Version is one concrete API version from a TypeSpec version set. It represents a service API version such as v2024.01 or v10.4.3, not an Inferal Relay build timestamp and not a publication date for the generated RDF.

Instances of this class are the only conforming objects for version-valued tspv properties. A graph SHOULD use stable IRIs for version instances so change annotations, merged ontologies, and predecessor chains can all refer to the same version nodes.

`tspv:VersionedResource`

IRI	`https://relay.inferal.com/ontology/typespec/versioning/VersionedResource`
RDFS kind	`rdfs:Class`
OWL addendum kind	`owl:Class`
SHACL target	`tspv:VersionedResource`

A tspv:VersionedResource is a generated RDF resource or ontology artifact that carries TypeSpec version coverage or flattened change metadata. This class provides the shared domain for tspv:coversVersion and the change annotation properties.

The class does not require the resource to be a TypeSpec type, operation, or property. Merged ontology artifacts that use tspv:coversVersion are also versioned resources in this profile.

`tspv:previousVersion`

IRI	`https://relay.inferal.com/ontology/typespec/versioning/previousVersion`
RDFS kind	`rdf:Property`
OWL addendum kind	`owl:ObjectProperty`
Domain	`tspv:Version`
Range	`tspv:Version`

tspv:previousVersion links a version to the immediately previous version in the same TypeSpec version chain. It is a direct predecessor edge, not a transitive closure edge and not a generic compatibility relationship.

A conforming graph MUST use a tspv:Version subject and a tspv:Version object for this property. Each version node MUST have no more than one tspv:previousVersion value, and the predecessor graph MUST NOT contain cycles. The initial version in a chain has no previous-version value.

`tspv:coversVersion`

IRI	`https://relay.inferal.com/ontology/typespec/versioning/coversVersion`
RDFS kind	`rdf:Property`
OWL addendum kind	`owl:ObjectProperty`
SHACL target	Subjects of `tspv:coversVersion`
Domain	`tspv:VersionedResource`
Range	`tspv:Version`

tspv:coversVersion states that an ontology artifact covers the named API version. Inferal Relay uses this for merged service ontologies that contain terms or annotations for more than one TypeSpec API version.

A conforming object MUST be a tspv:Version. Multiple values are allowed because one merged ontology can cover multiple API versions. Version-specific ontology artifacts MAY use this property with a single covered version.

`tspv:addedInVersion`

IRI	`https://relay.inferal.com/ontology/typespec/versioning/addedInVersion`
RDFS kind	`rdf:Property`
OWL addendum kind	`owl:ObjectProperty`
Domain	`tspv:VersionedResource`
Range	`tspv:Version`

tspv:addedInVersion identifies the API version in which the subject resource was introduced. The subject can be a generated class, property, operation, parameter, response, or other RDF resource produced from TypeSpec.

A conforming object MUST be a tspv:Version. A subject MUST have no more than one tspv:addedInVersion value. If the property is absent, the graph does not state when the resource was introduced.

`tspv:removedInVersion`

IRI	`https://relay.inferal.com/ontology/typespec/versioning/removedInVersion`
RDFS kind	`rdf:Property`
OWL addendum kind	`owl:ObjectProperty`
Domain	`tspv:VersionedResource`
Range	`tspv:Version`

tspv:removedInVersion identifies the API version in which the subject resource was removed from the TypeSpec API surface.

A conforming object MUST be a tspv:Version. A subject MUST have no more than one tspv:removedInVersion value. The assertion does not delete the RDF resource; it records the API version at which the resource ceased to be part of the service API.

`tspv:renamedFrom`

IRI	`https://relay.inferal.com/ontology/typespec/versioning/renamedFrom`
RDFS kind	`rdf:Property`
OWL addendum kind	`owl:DatatypeProperty`
Domain	`tspv:VersionedResource`
Range	`xsd:string`

tspv:renamedFrom records the previous TypeSpec name for the subject resource. It is the old lexical name, not an IRI and not a pointer to the old RDF term.

A conforming value MUST be a string literal. A subject with this property MUST have exactly one tspv:renamedFrom value and exactly one matching tspv:renamedInVersion value naming when the rename occurred.

`tspv:renamedInVersion`

IRI	`https://relay.inferal.com/ontology/typespec/versioning/renamedInVersion`
RDFS kind	`rdf:Property`
OWL addendum kind	`owl:ObjectProperty`
Domain	`tspv:VersionedResource`
Range	`tspv:Version`

tspv:renamedInVersion identifies the API version in which the subject resource was renamed.

A conforming object MUST be a tspv:Version. A subject that uses tspv:renamedFrom MUST have exactly one tspv:renamedInVersion value. A rename assertion is complete only when the graph gives both the previous name and the version in which the new name took effect.

`tspv:madeOptionalInVersion`

IRI	`https://relay.inferal.com/ontology/typespec/versioning/madeOptionalInVersion`
RDFS kind	`rdf:Property`
OWL addendum kind	`owl:ObjectProperty`
Domain	`tspv:VersionedResource`
Range	`tspv:Version`

tspv:madeOptionalInVersion identifies the API version in which the subject property became optional in the TypeSpec model.

A conforming object MUST be a tspv:Version. A subject MUST have no more than one tspv:madeOptionalInVersion value. This term records optionality change timing; it does not by itself describe the property's current cardinality outside the versioning context.

`tspv:madeRequiredInVersion`

IRI	`https://relay.inferal.com/ontology/typespec/versioning/madeRequiredInVersion`
RDFS kind	`rdf:Property`
OWL addendum kind	`owl:ObjectProperty`
Domain	`tspv:VersionedResource`
Range	`tspv:Version`

tspv:madeRequiredInVersion identifies the API version in which the subject property became required in the TypeSpec model.

A conforming object MUST be a tspv:Version. A subject MUST have no more than one tspv:madeRequiredInVersion value. This term records requiredness change timing; it does not by itself describe the property's current cardinality outside the versioning context.

`tspv:typeChangedFrom`

IRI	`https://relay.inferal.com/ontology/typespec/versioning/typeChangedFrom`
RDFS kind	`rdf:Property`
OWL addendum kind	`owl:DatatypeProperty`
Domain	`tspv:VersionedResource`
Range	`xsd:string`

tspv:typeChangedFrom records the previous TypeSpec type expression for a subject property before its type changed.

A conforming value MUST be a string literal. A subject with this property MUST have exactly one tspv:typeChangedFrom value and exactly one matching tspv:typeChangedInVersion value. The literal is an emitter-preserved TypeSpec type name or expression, not an RDF range assertion.

`tspv:typeChangedInVersion`

IRI	`https://relay.inferal.com/ontology/typespec/versioning/typeChangedInVersion`
RDFS kind	`rdf:Property`
OWL addendum kind	`owl:ObjectProperty`
Domain	`tspv:VersionedResource`
Range	`tspv:Version`

tspv:typeChangedInVersion identifies the API version in which the subject property's TypeSpec type changed.

A conforming object MUST be a tspv:Version. A subject that uses tspv:typeChangedFrom MUST have exactly one tspv:typeChangedInVersion value. A type-change assertion is complete only when the graph gives both the previous TypeSpec type expression and the version in which the new type took effect.

`tspv:returnTypeChangedFrom`

IRI	`https://relay.inferal.com/ontology/typespec/versioning/returnTypeChangedFrom`
RDFS kind	`rdf:Property`
OWL addendum kind	`owl:DatatypeProperty`
Domain	`tspv:VersionedResource`
Range	`xsd:string`

tspv:returnTypeChangedFrom records the previous TypeSpec return type expression for a subject operation before its return type changed.

A conforming value MUST be a string literal. A subject with this property MUST have exactly one tspv:returnTypeChangedFrom value and exactly one matching tspv:returnTypeChangedInVersion value. The literal is an emitter-preserved TypeSpec return type name or expression, not an RDF range assertion.

`tspv:returnTypeChangedInVersion`

IRI	`https://relay.inferal.com/ontology/typespec/versioning/returnTypeChangedInVersion`
RDFS kind	`rdf:Property`
OWL addendum kind	`owl:ObjectProperty`
Domain	`tspv:VersionedResource`
Range	`tspv:Version`

tspv:returnTypeChangedInVersion identifies the API version in which the subject operation's TypeSpec return type changed.

A conforming object MUST be a tspv:Version. A subject that uses tspv:returnTypeChangedFrom MUST have exactly one tspv:returnTypeChangedInVersion value. A return type change assertion is complete only when the graph gives both the previous TypeSpec return type expression and the version in which the new return type took effect.

Version Chains

A version chain is represented with one tspv:Version node per API version. Each non-initial version SHOULD have at most one tspv:previousVersion edge to the immediately previous API version. Version chains MUST NOT contain cycles.

@prefix ex: <https://example.com/typespec-versioning/> .
@prefix tspv: <https://relay.inferal.com/ontology/typespec/versioning/> .

ex:v2024_01 a tspv:Version .

ex:v2024_04
    a tspv:Version ;
    tspv:previousVersion ex:v2024_01 .

Change Annotations

Change annotations attach TypeSpec versioning events to RDF resources emitted from TypeSpec types, properties, operations, and generated ontology artifacts. Version-valued annotations SHOULD point at tspv:Version instances in the service's version chain.

Rename, type-change, and return-type-change annotations have two parts: a literal source value and a version resource naming when the change occurred. Data that uses tspv:renamedFrom MUST also provide tspv:renamedInVersion. Data that uses tspv:typeChangedFrom MUST also provide tspv:typeChangedInVersion. Data that uses tspv:returnTypeChangedFrom MUST also provide tspv:returnTypeChangedInVersion.

@prefix ex: <https://example.com/typespec-versioning/> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix tspv: <https://relay.inferal.com/ontology/typespec/versioning/> .

ex:CustomerSegment
    a rdfs:Class ;
    rdfs:label "Customer segment" ;
    tspv:addedInVersion ex:v2024_04 ;
    tspv:renamedFrom "BuyerSegment" ;
    tspv:renamedInVersion ex:v2024_07 .

Validation

The SHACL artifact validates the core profile used by Inferal Relay: version predecessor edges point at tspv:Version nodes, predecessor chains are acyclic, version-valued annotations have at most one value, and paired literal/version change annotations are complete.