@prefix sps:     <https://schema.sempods.org/> .
@prefix rdf:     <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs:    <http://www.w3.org/2000/01/rdf-schema#> .
@prefix owl:     <http://www.w3.org/2002/07/owl#> .
@prefix xsd:     <http://www.w3.org/2001/XMLSchema#> .
@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix vann:    <http://purl.org/vocab/vann/> .
@prefix schema:  <https://schema.org/> .

#
# The sempods vocabulary.
#
# It holds only terms that are specific to sempods and have no established equivalent
# elsewhere. Everything a standard vocabulary already says is taken from that vocabulary
# instead — see the note on schema:text and schema:position below, which are deliberately
# reused rather than duplicated here.
#
# Stability guarantees, the deprecation policy and how a term gets added:
# https://github.com/sempods/sempods-spec/blob/main/vocabulary/README.md
#

<https://schema.sempods.org/>
  a                              owl:Ontology ;
  dcterms:title                  "The sempods vocabulary"@en ;
  dcterms:description            """Terms specific to sempods: today, the metadata a `find`
    response carries about each hit. Deliberately small — the model is expressed in RDF,
    SPARQL, SHACL and schema.org, not in a vocabulary of its own."""@en ;
  vann:preferredNamespacePrefix  "sps" ;
  vann:preferredNamespaceUri     "https://schema.sempods.org/" ;
  dcterms:hasVersion             "0.1.0" ;
  dcterms:issued                 "2026-08-12"^^xsd:date ;
  dcterms:license                <https://creativecommons.org/licenses/by/4.0/> ;
  dcterms:publisher              <https://sempods.org/> ;
  rdfs:seeAlso                   <https://sempods.org/> .


##
## find — the semantic entry to the graph
##
## `find` answers with a context-sandboxed subgraph: the matching resources, each expanded with
## its authoritative type and label. That answer is FLAT — no ordering, no score, and no marker
## separating a hit from its expansion (SPS-FIND-018).
##
## The terms below describe a per-hit metadata node for a response that would carry one. They are
## RESERVED, not present: no implementation emits them, and SPS-FIND-022 confines them to a
## representation a client explicitly asks for — which this version of the specification does not
## define. They are published so that the first implementation wanting per-hit metadata adopts
## these names rather than minting its own, and a second one different names again.
##
## Where such a node is emitted, it is transient: it belongs to the response, not to the store, and
## carries no named graph (SPS-FIND-024).
##

sps:FindResult
  a               rdfs:Class, owl:Class ;
  rdfs:isDefinedBy <https://schema.sempods.org/> ;
  rdfs:label      "Find result"@en ;
  rdfs:comment    """Metadata about one hit in a `find` response: which engine produced it,
    where it ranked, and the excerpt that matched. RESERVED — no implementation emits this today,
    and the default `find` answer carries no such node. Where one is emitted, an instance is
    produced per response and is not part of the stored graph: a client may use it for ordering and
    display, and must not expect to retrieve it again.

    Authoritative facts about the hit itself (rdf:type, labels, timestamps) are never asserted
    here. They come from the store during expansion, because the store is what knows them."""@en .


sps:findResult
  a                rdf:Property, owl:ObjectProperty ;
  rdfs:isDefinedBy <https://schema.sempods.org/> ;
  rdfs:label       "find result"@en ;
  rdfs:comment     """Links a resource that matched a `find` query to the metadata node
    describing that match.

    No domain is stated on purpose: any resource can be a hit, and constraining the domain
    would say something about the resource that the search has no standing to say."""@en ;
  rdfs:range       sps:FindResult .


sps:engine
  a                rdf:Property, owl:DatatypeProperty ;
  rdfs:isDefinedBy <https://schema.sempods.org/> ;
  rdfs:label       "engine"@en ;
  rdfs:comment     """The name of the search engine that produced this result — provenance,
    for a `find` implementation that merges several engines behind one contract. An opaque
    short token, for example "sparql-text" or "ai-search"; the set is open, because which
    engines run is a deployment decision."""@en ;
  rdfs:domain      sps:FindResult ;
  rdfs:range       xsd:string .


##
## Reused, not redefined
##
## An `sps:FindResult` node also carries, where the engine supplies them:
##
##   schema:text      the excerpt that matched — the snippet
##   schema:position  the hit's rank within this response, 1-based
##
## Both are schema.org terms used with their ordinary meaning. They are named here for the
## reader's benefit and deliberately not given a domain or range in this file: constraining a
## foreign term inside one's own vocabulary is exactly the redefinition NAMESPACE.md asks third
## parties not to do, and the rule holds for this project too.
##