Improving support for user-defined annotations

With XQuery 3.0 annotations were extended to support any EQName, and allow
optional values. These have been used by vendors to implement REST
capabilities (via the EXQuery RESTXQ specification) and unit test
capabilities (such as in BaseX's test module).

However, support for user-defined annotations is lacking. This means that
external projects implementing the RESTXQ module (such as the rqx library
for MarkLogic) need to rely on vendor extensions and vendor APIs to
implement that functionality to take advantage of annotations. A similar
case applies to unit test libraries like XRay which use annotations to
define which functions are unit tests.

The general approach for this (some of which have been raised as xpath-ng
proposals) can be broken down into 3 parts:

1. Annotation Item Types -- similar to a FunctionTest, making annotations a
concrete part of the XQuery type system.

2. Annotation Declarations -- similar to function declarations, that define
the form an annotation can take; that is, the annotation name along with
the supported parameter names and types.

3. Functions and Operators support -- allowing annotations to be queried,
along with the annotation argument values, and possibly other operations.

I'm wondering if it makes sense for annotation declarations to be function
declarations. This would avoid the need for having a separate parallel
system to functions (including in-scope definitions).

For example, you could create a simple test framework as follows:

    declare %annotation function test:case() {};
    declare %annotation function test:values($values as item() ...) {};

    declare function test:run-tests() {
        for $f in in-scope-functions()
        let $a as annotation()? :=
            annotation-for-function($f, test:case#0)
        let $with-values as annotation(xs:string ...)* :=
            annotation-for-function($f, test:values#*) (: any arity :)
        where exists($a)
        return if (exists($with-values))
            then
                for $value in $with-values
                return $f(annotation-arguments($value))
            else $f()
    };

and have it work on any XQuery 4.0 capable processor.

The other use case for this is for tooling, so things like xqDoc can
provide documentation for annotations and annotation parameters, as well as
accessing the annotation information in a vendor-agnostic manner to
generate the function signatures in the documentation. Editors/IDEs could
also provide features like validation, auto-complete, and parameter
signature tooltips for user-defined annotations.

Kind regards,
Reece