Inferal Git Ontology

The Inferal Git Ontology defines RDF terms for Git's content-addressed object graph and reference graph while keeping object payload custody external. It represents SHA-1 and SHA-256 repositories, four Git object kinds, byte-preserving tree entries, ordered commit parents, annotated tags, direct and symbolic references, and resolvable object stores. Commit-parent topology is aligned with broad precedence in the Inferal Ordering Ontology without asserting order-theoretic adjacency.

This is an unofficial 0.1 Editor's Draft maintained by Inferal.

Feedback should be sent to contact@inferal.com.

Introduction

Git repositories are usually exposed through commands, filesystem layouts, or hosting APIs. Those interfaces are excellent for operating one repository, but they make it difficult to join Git structure with provenance, software inventories, build evidence, archival custody, or other RDF datasets. Treating a commit merely as a version string loses its tree, ordered parents, object-format domain, tag structure, and the distinction between references and immutable objects.

This ontology supplies a small semantic layer over Git's native content-addressed graph. It does not replace Git object storage. The RDF graph records immutable identifiers, topology, reference state, and payload-resolution declarations. A compatible processor resolves bytes from an object store and asks Git to verify the declared identifier. This division permits useful graph queries without embedding every blob or pretending that RDF literals are a new Git transport.

Motivation and rationale

Hash-only description is deliberate. A large binary blob may already be held in an origin repository, partial-clone cache, archival mirror, or content-addressed object service. Copying it into RDF would increase storage and transfer costs without strengthening identity: Git's hash verification is the authoritative check. Store declarations keep custody explicit, while object-specific overrides support split or migrated storage.

Ordered occurrence resources are also deliberate. RDF predicates do not order repeated values, while Git commit parent order and tree entry order contribute to exact object payloads. CommitParent and TreeEntry preserve those occurrences with integer indices and avoid relying on blank-node RDF collections in public data.

Conceptual overview

A repository selects one object-format algorithm.
Repository objects carry immutable identifiers and one native object kind.
Trees, commits, and annotated tags expose their identity-bearing topology.
Direct and symbolic references describe mutable names separately from objects.
Payload stores state where object bytes can be resolved without embedding them.
Validation checks the closed-world representation; materialization verifies bytes with Git.

Audience

The intended audience is ontology authors, repository archivists, software-supply-chain systems, provenance systems, build and release tooling, and processors that need to join Git topology with RDF data. Implementers are expected to understand Git objects and references; RDF consumers need not understand Git's loose-object or pack encoding.

Design goals

Preserve SHA-1 and SHA-256 object identities without conflating their domains.
Represent topology precisely enough to detect a false tree, parent, or tag projection.
Keep binary payload custody separate and resolvable.
Represent merge-parent and tree-entry ordering without positional property names.
Distinguish annotated tag objects from lightweight tag references.
Represent unborn symbolic HEAD and external submodule gitlinks without inventing local objects.
Remain useful to ordinary SPARQL processors and SHACL validators.

Non-goals

This ontology is not a replacement object database, pack format, or network protocol.
It does not infer a filename character encoding from Git's byte-oriented tree names.
It does not expose commit authors, messages, signatures, or arbitrary headers in version 0.1.
It does not claim that a declared access IRI is currently reachable or authorized.
It does not model worktree, index, configuration, hook, or reflog state.

Competency questions

Which object does symbolic HEAD select through its named direct reference?
Which commits are the ordered parents of a merge, and which is the first parent?
Which commits broadly precede or follow one another through parent ancestry?
Which tree and exact entry-name bytes does a commit select?
Which entries are regular files, executable files, symbolic links, subtrees, or gitlinks?
Is a named tag lightweight, or does it select an annotated tag object?
Which repository objects are unreachable from every direct reference?
Which payload store applies to an object after override precedence?
Can all locally described objects currently be resolved and hash-verified?
Does an RDF tree, commit-parent, or tag projection agree with the resolved Git payload?
Does a gitlink identify an external commit without falsely asserting local availability?

This specification defines three conformance classes.

A structural Git graph identifies a repository's known objects and references and satisfies the topology and validation rules in this specification. It need not contain object payloads.

A materializable Git graph is a structural Git graph for which every object resolves through its explicit object store or the repository default. A materializer MUST reject a resolved payload when Git computes an identifier different from git:objectId.

A Git graph validator checks object-format identifier syntax, unique object and reference identity, ordered occurrence indices, object kinds, tree modes, and object-store resolution declarations.

Namespace

https://ontology.inferal.com/modules/git/, conventionally abbreviated git:.

Term overview

Term	Kind	Role
`git:Repository`	Class	One described Git object and reference domain.
`git:ObjectStore`	Class	Resolver for object payloads by identifier.
`git:GitObject`	Class	Content-addressed Git object identity.
`git:Blob`	Class	Uninterpreted file-content object.
`git:Tree`	Class	Ordered tree-entry object.
`git:Commit`	Class	Locally described commit object.
`git:CommitAncestryOrdering`	Individual	Canonical partial ordering of Git commit ancestry.
`git:Tag`	Class	Annotated tag object.
`git:GitlinkCommit`	Class	External commit identity selected by a gitlink.
`git:TreeEntry`	Class	Ordered name, mode, and target occurrence.
`git:CommitParent`	Class	Ordered parent occurrence.
`git:Reference`	Class	Named mutable reference.
`git:DirectReference`	Class	Reference whose value is an object ID.
`git:SymbolicReference`	Class	Reference whose value is another reference name.
`git:objectFormat`	Property	Repository object-ID algorithm.
`git:hasObject`	Property	Object present in the described object database.
`git:hasReference`	Property	Reference in the described reference graph.
`git:defaultObjectStore`	Property	Inherited payload resolver.
`git:payloadStore`	Property	Per-object payload resolver override.
`git:accessIRI`	Property	Processor-accessible store location.
`git:objectId`	Property	Lowercase hexadecimal object identifier.
`git:hasTreeEntry`	Property	Tree-to-entry occurrence relation.
`git:entryIndex`	Property	Zero-based tree-entry order.
`git:entryNameBytes`	Property	Exact base64-encoded path-component bytes.
`git:entryMode`	Property	Canonical Git tree mode.
`git:entryObject`	Property	Object selected by a tree entry.
`git:commitTree`	Property	Commit root tree.
`git:hasParent`	Property	Commit-to-parent occurrence relation.
`git:parentIndex`	Property	Zero-based commit-parent order.
`git:parentCommit`	Property	Commit selected by a parent occurrence.
`git:hasParentCommit`	Property	Derived child-to-parent relation specializing broad `ord:follows`.
`git:tagTarget`	Property	Object selected by an annotated tag.
`git:referenceName`	Property	Complete Git reference name.
`git:pointsToObject`	Property	Object value of a direct reference.
`git:symbolicTargetName`	Property	Name value of a symbolic reference.

Repository and storage model

git:Repository describes one object-format domain. Its git:objectFormat value MUST be sha1 or sha256. git:hasObject and git:hasReference enumerate the described graph; they do not assert physical co-location.

All objects connected by hasObject MUST use identifiers from the repository's object-format domain. Two equal hexadecimal strings under different algorithms are not interchangeable object identities. A repository object MUST have exactly one native kind—Blob, Tree, Commit, or Tag—and MUST NOT be a GitlinkCommit. A producer SHOULD use stable content-derived IRIs such as an algorithm and object-ID URN, but conformance depends on objectId, not on a particular RDF subject naming convention.

git:ObjectStore identifies a content resolver and has one or more git:accessIRI values. An object's git:payloadStore overrides its repository's git:defaultObjectStore.

An access IRI identifies a location, not a universal retrieval protocol. A consumer MUST understand the IRI scheme and the store's service contract before dereferencing it. Multiple access IRIs are alternatives; this specification does not rank them or infer availability.

Objects

git:GitObject is the superclass of git:Blob, git:Tree, git:Commit, and git:Tag. Every object has exactly one lowercase hexadecimal git:objectId of the length selected by the repository object format.

Blob payload bytes are intentionally opaque to this ontology. Tree, commit, and tag payloads are also retained by Git rather than copied into RDF; their selected identity-bearing edges are projected for querying. Commit authors, committers, messages, encodings, signatures, and unknown extension headers remain recoverable through the payload but are not first-class terms in this version.

Trees and entry modes

A tree uses git:hasTreeEntry to select git:TreeEntry occurrences. Each occurrence has a contiguous zero-based git:entryIndex, exact git:entryNameBytes, git:entryMode, and one git:entryObject. A 160000 entry may select a git:GitlinkCommit, which records the identity of a commit absent from the containing repository's object database. This is the structural gitlink used for submodules and does not assert that the external commit topology is known. A gitlink identity resource is scoped to this repository description and MUST NOT be reused as the RDF node for a complete Commit description in another repository graph; both resources may carry the same hexadecimal identifier without asserting RDF identity.

Mode	Required target kind	Meaning
`100644`	Blob	Regular non-executable file.
`100755`	Blob	Regular executable file.
`120000`	Blob	Symbolic-link target bytes.
`40000`	Tree	Nested tree.
`160000`	Commit or GitlinkCommit	Submodule gitlink.

entryNameBytes contains one path-component byte sequence, not a slash-separated repository path. Consumers MUST NOT assume UTF-8. A display name or decoded path is an application view and is outside the identity-preserving graph.

Commits and ordered ancestry

A commit has exactly one git:commitTree. Each git:hasParent value is a git:CommitParent occurrence with a contiguous git:parentIndex and one git:parentCommit. Parent order MUST NOT be discarded because it contributes to commit identity.

A root commit has no hasParent values. A non-merge commit normally has index zero only. A merge commit has two or more occurrences; index zero is Git's first parent. Indices MUST be unique and contiguous from zero so a graph cannot omit an intermediate parent while appearing ordered.

git:CommitAncestryOrdering is the canonical ord:PartialOrdering for Git ancestry. The OWL addendum places every Commit in this ordering and derives git:hasParentCommit from the hasParent followed by parentCommit path.

hasParentCommit specializes ord:follows. With the Ordering OWL addendum, a child that has a parent commit therefore follows that parent, and the parent precedes the child. This alignment intentionally does not assert ord:immediatelyFollows or ord:immediatelyPrecedes: a recorded Git parent can also be reachable through another recorded parent. Other chronological, topological, or presentation orderings SHOULD use separate participation resources rather than assigning the commit resource another ord:inOrdering value.

Annotated and lightweight tags

An annotated tag object has exactly one git:tagTarget. A lightweight tag is represented only as a reference.

The object selected by tagTarget MUST be present in the described repository object graph. Tag names, tagger headers, messages, and signatures remain in the verified tag payload in this version.

References

Every git:Reference has one complete git:referenceName. A git:DirectReference has one git:pointsToObject. A git:SymbolicReference instead has one git:symbolicTargetName. The symbolic target may be unborn and therefore need not occur as a described reference.

A direct reference target MUST be a repository object. A producer SHOULD preserve complete names such as refs/heads/main rather than local display names such as main. Validators enforce cardinality and repository membership; materializers MUST additionally ask Git to reject reference names that violate the active Git implementation's reference-format rules.

Symbolic resolution is a name join: find a reference whose referenceName equals the source reference's symbolicTargetName. Absence of that target is not a contradiction; it represents an unborn symbolic reference such as HEAD before the first commit.

Payload resolution and materialization

A conforming materializer applies the following procedure:

Select payloadStore when present; otherwise select defaultObjectStore.
Try understood and authorized accessIRI alternatives in a deterministic order until the payload resolves.
Resolve the native object payload using its object kind and objectId.
Ask Git to hash the native object header and payload using objectFormat.
Reject the payload unless the computed identifier exactly equals objectId.
For trees, commits, and tags, parse the payload and compare its projected edges and order with the RDF graph.
Write verified objects before creating direct and symbolic references in a staging repository.
Publish the completed repository atomically and leave the requested destination absent when any earlier step fails.

Hash verification alone is insufficient to validate the semantic projection: a graph could attach a correct commit ID to the wrong commitTree. Conversely, matching topology alone is insufficient to reconstruct signatures, unknown headers, messages, or blob bytes. A materializer therefore verifies both native identity and projected topology.

A structural graph may remain temporarily non-materializable when an access location is offline or credentials are unavailable. Such failure does not change object identity. A graph that omits every applicable store declaration is not conformant to this version's repository shape.

Examples

@prefix git: <https://ontology.inferal.com/modules/git/> .
@prefix ex: <https://example.com/git/spec/> .

ex:repo
    a git:Repository ;
    git:objectFormat "sha1" ;
    git:defaultObjectStore ex:origin ;
    git:hasObject ex:blob .

ex:origin
    a git:ObjectStore ;
    git:accessIRI "https://objects.example/project.git"^^<http://www.w3.org/2001/XMLSchema#anyURI> .

ex:blob
    a git:Blob ;
    git:objectId "ce013625030ba8dba906f756967f9e9ca394464a" .

@prefix git: <https://ontology.inferal.com/modules/git/> .
@prefix ex: <https://example.com/git/spec/merge/> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

ex:repository
    a git:Repository ;
    git:objectFormat "sha1" ;
    git:defaultObjectStore ex:origin ;
    git:hasObject ex:root-tree, ex:first-parent, ex:second-parent, ex:merge .

ex:origin
    a git:ObjectStore ;
    git:accessIRI "https://objects.example/project.git"^^xsd:anyURI .

ex:root-tree
    a git:Tree ;
    git:objectId "1111111111111111111111111111111111111111" ;
    git:hasTreeEntry ex:submodule-entry .

ex:first-parent
    a git:Commit ;
    git:objectId "2222222222222222222222222222222222222222" ;
    git:commitTree ex:root-tree .

ex:second-parent
    a git:Commit ;
    git:objectId "3333333333333333333333333333333333333333" ;
    git:commitTree ex:root-tree .

ex:merge
    a git:Commit ;
    git:objectId "4444444444444444444444444444444444444444" ;
    git:commitTree ex:root-tree ;
    git:hasParent ex:first-parent-occurrence, ex:second-parent-occurrence .

ex:first-parent-occurrence
    a git:CommitParent ;
    git:parentIndex "0"^^xsd:nonNegativeInteger ;
    git:parentCommit ex:first-parent .

ex:second-parent-occurrence
    a git:CommitParent ;
    git:parentIndex "1"^^xsd:nonNegativeInteger ;
    git:parentCommit ex:second-parent .

ex:submodule-entry
    a git:TreeEntry ;
    git:entryIndex "0"^^xsd:nonNegativeInteger ;
    git:entryNameBytes "dmVuZG9y"^^xsd:base64Binary ;
    git:entryMode "160000" ;
    git:entryObject ex:external-commit .

ex:external-commit
    a git:GitlinkCommit ;
    git:objectId "5555555555555555555555555555555555555555" .

Query recipes

The following recipes illustrate questions answered directly by the model. Published query distributions include explanatory comments and conforming example data; the snippets here state their essential logic.

Resolve symbolic HEAD

PREFIX git: <https://ontology.inferal.com/modules/git/>
SELECT ?repository ?targetName ?object ?objectId WHERE {
  ?repository git:hasReference ?head, ?direct .
  ?head a git:SymbolicReference ;
        git:referenceName "HEAD" ;
        git:symbolicTargetName ?targetName .
  ?direct a git:DirectReference ;
          git:referenceName ?targetName ;
          git:pointsToObject ?object .
  ?object git:objectId ?objectId .
}

Find unreachable repository objects

PREFIX git: <https://ontology.inferal.com/modules/git/>
SELECT ?repository ?object ?objectId WHERE {
  ?repository a git:Repository ; git:hasObject ?object .
  ?object git:objectId ?objectId .
  FILTER NOT EXISTS {
    ?repository git:hasReference/git:pointsToObject ?root .
    ?root (git:commitTree|git:hasParent/git:parentCommit|
           git:hasTreeEntry/git:entryObject|git:tagTarget)* ?object .
  }
}

Resolve effective payload stores

PREFIX git: <https://ontology.inferal.com/modules/git/>
SELECT ?object ?store ?accessIRI WHERE {
  ?repository git:hasObject ?object .
  OPTIONAL { ?repository git:defaultObjectStore ?defaultStore }
  OPTIONAL { ?object git:payloadStore ?explicitStore }
  BIND(COALESCE(?explicitStore, ?defaultStore) AS ?store)
  ?store git:accessIRI ?accessIRI .
}

Validation expectations

Validation is intentionally closed-world and belongs to SHACL, not to the open-world OWL vocabulary. The supplied shapes enforce at least the following contracts:

one SHA-1 or SHA-256 format per repository;
exactly one native object kind per repository object and no repository-owned gitlink identities;
algorithm-appropriate lowercase object-ID length, including external gitlink identities;
unique object IDs and reference names within a repository graph;
an explicit or inherited payload store for every repository object;
repository containment for ordinary topology and direct-reference targets;
unique contiguous tree-entry and commit-parent indices from zero;
exactly one containing tree per tree entry and one containing commit per parent occurrence;
unique exact name bytes among entries of one tree;
tree mode agreement with blob, tree, commit, or gitlink target kind;
exactly one tree per commit and exactly one target per annotated tag;
exactly one object target for direct refs and one name target for symbolic refs.

OWL functional-property declarations support reasoning consumers but do not replace SHACL cardinality checks. Missing values are not false under OWL's open-world semantics, while a conformance validator must report them as absent from the submitted data graph.

Interoperability and extension

Extensions may attach provenance, archival policy, media type, commit metadata, or service descriptions to Git resources without changing their core identity. New payload-store protocols SHOULD specialize or document resolver behavior rather than interpreting every HTTP or file IRI identically. Applications MAY derive human-readable filenames from entryNameBytes, but SHOULD retain the exact bytes alongside any decoded view.

This ontology makes no OWL equivalence claim with hosting-provider APIs or software-package vocabularies. Such projections are directional mappings and should state coverage and loss explicitly, especially when an API omits unreachable objects, symbolic references, or parent order.

Security and privacy considerations

Object-store IRIs may reveal repository locations or trigger access to local files and network services. Consumers MUST apply scheme allowlists, authorization policy, size limits, and network isolation appropriate to untrusted RDF. A materializer MUST NOT trust a payload merely because it was returned by a declared store; native Git hash verification is required before object or reference creation.

Git object identifiers and topology can themselves disclose repository history, branch names, deleted-but-unreachable objects, submodule commit identities, or the existence of confidential content. Publishing a hash-only graph is not equivalent to anonymization. Producers should apply the same disclosure policy they would apply to repository metadata.

Scope limits

This version models the persistent object and reference graphs described by Git's repository and pack-format documentation [[!GIT-REPOSITORY-LAYOUT]] [[!GIT-PACK-FORMAT]]. Worktrees, index state, reflogs, configuration, hooks, shallow boundaries, replacement mechanisms, and transport negotiation are outside this conformance layer.

Later profiles may add these operational layers. They should not weaken the core distinction between immutable objects, mutable references, and external payload custody, and should add conformance tests against real Git behavior before becoming normative.