[UI] Proposal for shui:searchQuery

[danielbeeke]

Feature Proposal: shui:searchQuery Extension

1. Abstract & Context

In SHACL UI, a property's value nodes are typically enumerated via sh:in, optionally computed dynamically with a sh:select expression (including federated SERVICE queries), as allowed by Dynamic SHACL in SHACL 1.2.

Such baseline queries resolve a full candidate set and cannot be parameterized with a user's live search input, nor take advantage of vendor-specific full-text search (FTS) extensions.

This proposal introduces shui:searchQuery, an optional property directly on a property shape, that lets shape authors provide a dedicated SPARQL SELECT query for resolving candidate value nodes from live, user-provided search input (e.g. in an AutoCompleteEditor). It can be used standalone, or alongside sh:in/sh:select as a live-search override with a defined fallback path.

---

2. Vocabulary Definition

Term	Detail
Property Name	shui:searchQuery
Domain	sh:PropertyShape — appears directly on the property shape, not nested inside sh:in
Range	xsd:string (containing a SPARQL SELECT query string)
Cardinality	At most one value per property shape
Conformance	Optional / MAY be supported by SHACL UI renderers

---

3. Specification Rules

1. Rendering & Execution Behavior:
   When an end user enters or changes search input for a property rendered with a widget that consumes candidate value nodes, a renderer that supports this extension MAY evaluate the query given by shui:searchQuery to retrieve the candidate values offered to the user.

2. Reserved Execution Variables:
   The query MUST expect the following variables to be pre-bound by the renderer before evaluation:

   • $searchTerm: an xsd:string literal containing the current search input entered by the user.
   • $uiLanguage: a language-tagged literal identifying the user's current UI language, as determined by Language Resolution.

3. Query Structure & Constraints:

   • Output Mapping: the query MUST project exactly one result variable, representing matching IRIs or literals.
   • Paging: the query MUST NOT include a LIMIT or OFFSET solution modifier — pagination and limits remain under the exclusive control of the renderer.

4. Interaction with sh:in:
   A property shape's permissible value nodes can still be computed via sh:in/sh:select (including SERVICE) per Dynamic SHACL. When a property shape combines sh:in with shui:searchQuery, a renderer that supports shui:searchQuery evaluates it in place of the sh:in-derived query while the user is searching. A renderer that does not support shui:searchQuery, but does support Dynamic SHACL, MAY fall back to the baseline sh:in/sh:select query instead. shui:searchQuery may also be used on its own, without any sh:in.

5. Editor Selection:
   The presence of shui:searchQuery on a property shape signals that a live search widget is appropriate, even without an explicit shui:editor statement — it now contributes +20 to the AutoCompleteEditor's selection score.

6. Validation Scope:
   shui:searchQuery is never evaluated as part of ordinary SHACL validation and MUST NOT be treated as a constraint by a validation engine. A new subsection defines an optional mechanism for implementations that additionally want to validate value nodes returned by shui:searchQuery:

   • Shape authors SHOULD write shui:searchQuery so its results are a subset of (or equal to) the value nodes permitted by the property shape's other constraints (sh:class, sh:node, sh:in, etc.).
   • Implementations MAY validate each returned value node in isolation against the surrounding property shape.
   • For SERVICE-backed sh:in expressions, this requires a validation engine supporting federated (Dynamic SHACL) validation, and the isolated check SHOULD use only the sh:in constraint — not the shape's other constraints — since a value node retrieved via SERVICE typically has no local triples and would otherwise trigger spurious violations.

---

4. Example Usage

Standalone (no sh:in needed):

ex:TaskShape
    a sh:NodeShape ;
    sh:targetClass ex:Task ;
    sh:property [
        sh:name "Assignee" ;
        sh:path ex:assignee ;
        sh:class ex:Person ;
        shui:searchQuery """
            PREFIX ex: <http://example.com/>
            PREFIX text: <http://jena.apache.org/text#>
            SELECT ?value WHERE {
                ?value text:query ($searchTerm $uiLanguage) .
                ?value a ex:Person .
            }
        """ ;
    ] .

Combined with sh:in for federated fallback:

ex:BookShape
    a sh:NodeShape ;
    sh:targetClass ex:Book ;
    sh:property [
        sh:name "Author" ;
        sh:path dct:creator ;
        sh:in [
            sh:select """
                PREFIX ex: <http://example.com/>
                SELECT ?value WHERE {
                    SERVICE <http://example.com/sparql> {
                        ?value a ex:Person .
                    }
                }
            """ ;
        ] ;
        shui:searchQuery """
            PREFIX ex: <http://example.com/>
            PREFIX text: <http://jena.apache.org/text#>
            SELECT ?value WHERE {
                SERVICE <http://example.com/sparql> {
                    ?value text:query ($searchTerm $uiLanguage) .
                    ?value a ex:Person .
                }
            }
        """ ;
    ] .

If the renderer doesn't support shui:searchQuery but does support Dynamic SHACL, it falls back to the baseline sh:in/sh:select query, returning all ex:Person instances.

5. Implementation Notes & Scope Boundary

• Decoupled from Property Roles: this spec does not mandate how property roles (e.g. shui:LabelRole, shui:DepictionRole) are resolved or injected into the search query. Renderers MAY combine filtering and label retrieval into one query or perform them separately.
• Deterministic Execution: isolating shui:searchQuery as a standalone SPARQL contract parameterized by $searchTerm and $uiLanguage keeps execution predictable without relying on string manipulation or automatic query restructuring by renderers.
• Not a validation hook by default: shui:searchQuery results are not checked against the shape unless an implementation opts in to the new optional validation mechanism described above.

Closes #846

• See this document rendered online here

[robert-david]

I have some questions about this proposal. My understanding is that you want to query something different (different nodes) compared to what the 'standard' sh:select query does. In the example it is not clear how the two queries interact.

1. What is the reason this cannot be expressed by the sh:select?
2. Is the semantics of having two queries such that both result sets are merged?
3. The sh:in, as presented in the example above, is not a valid SelectExpression. I think we need to change this in the shacl12-sparql spec, right?

[danielbeeke]

What is the reason this cannot be expressed by the sh:select?

• sh:select is a query to get all valid value nodes. It is for validation. We need to a have a short list that only gives what the end user is searching for.
• We could stretch s:select its usage and pre-bind a variable $searchTerm. This would put a burden on shape writers to make a very precise sh:select query so that UIs work. Requiring them to put something like if (bound($searchTerm) ? etc...). Seems complicated and error prone.

Is the semantics of having two queries such that both result sets are merged? No, when shui:searchQuery is available, it is only used to populate the list of options in an autocomplete. shui:searchQuery is never used in validation. Maybe we should add that the shape writer SHOULD make sure that the list of results in the shui:searchQuery is a sub set of the query in sh:in.

The sh:in, as presented in the example above, is not a valid SelectExpression. I think we need to change this in the shacl12-sparql spec, right? It is a valid SelectExpression, I carefully read the spec, I might have missed something. I do not read the normative part as blocking having more predicates with values. We are just extending the SelectExpression.

[danielbeeke]

I made changes to the PR and the issue description after a call with Robert David,

Summary of what changed vs. the original proposal:

• shui:searchQuery moved off the sh:in/sh:select blank node onto the property shape itself (so it no longer requires sh:in at all)
• Reserved variables switched from ?searchTerm/?uiLanguage to $searchTerm/$uiLanguage
• Its presence now feeds into AutoCompleteEditor editor-selection scoring
• A new optional "Validation of Search Query Results" section was added covering how (and when) implementations may validate returned values against the shape, including guidance for federated/SERVICE-backed cases.