This is an archived snapshot of W3C's public bugzilla bug tracker, decommissioned in April 2019. Please see the home page for more details.
I was probably not concentrating very well while annotation assertions were being discussed; I think I assumed that all would become clear when I read the final spec. In fact, for someone who wasn't listening to the debates at the time, the spec is as clear as mud. Let's start with the definition: [Definition: If an annotation is present in a FunctionTest, it is called an annotation assertion.] Well, for a start, this is a very odd sort of definition. It's a bit like saying that if an apple is present in a restaurant it is called a dessert. This leaves me confused as to whether all apples are desserts or whether all desserts are apples. It might be better to define the concept syntactically: [189] FunctionTest ::= AnnotationAssertion* (AnyFunctionTest | TypedFunctionTest) [189a] AnnotationAssertion ::= Annotation Here it's no longer true that an AnnotationAssertion IS an annotation, it just takes the same syntactic form as an annotation. The next thing we read is "Annotation assertions further restrict the set of functions that are matched by a FunctionTest." So, I want to know how. I know that %speed:fast is an annotation, so I might conclude that it is also an annotation assertion, and with some imagination I might conclude that a FunctionTest carrying this assertion will only match functions with this annotation. But the spec doesn't actually say that. Perhaps (my imagination is now going wild, there is nothing in the spec to say otherwise) the annotation assertion %speed:fast will also match a function annotated as %speed:superfast. If that's a possibility, I think the spec should say so. There certainly needs to be something to describe the relationship between annotation assertions and annotations. Read on, Macduff. "Implementations MAY define further annotation assertions, whose behaviour is implementation-defined." What does "further" mean? Does it mean assertions that don't take the syntactic form of an annotation? I suspect not. I suspect it means annotation assertions that are not defined in this spec. The set of annotation assertions defined in this spec appears to be empty, is that right? So "further" is a bit of a euphemism. ("Behaviour", incidentally, needs to be spelt the American way). Moving on: "Implementations MAY provide a way for users to create their own annotation assertions.". So my assumption that you create an annotation assertion merely by using an annotation within a FunctionTest is clearly wrong. That's what the definition implied, but it seems that not every apple found within a restaurant is ipso facto a dessert. This is confirmed by the first Note: "There are no annotation assertions that correspond to the %public and %private annotations." So I'm coming to the conclusion that the only assertions that can be used as annotation assertions are those that are explicitly licensed to be used in that way by some mechanism outside this specification. Which presumably means there is some error condition that needs to be added to the spec to disallow others. (Or perhaps it isn't an error, perhaps they are just ignored? In which case we need to be clear about whether an annotation assertion that's ignored is or is not an annotation assertion). We're getting close to the end "Other specifications in the XQuery family also use annotation assertions.". Perhaps, I'm feeling, the "also" is redundant? Perhaps what has happened is that XQuery itself doesn't use them at all, but they are available for use by other specifications? If so, that's what we should say.
Proposed rewrite: A FunctionTest is used to match a function by its type signature and predicates specified in *function assertions. [191] FunctionTest ::= FunctionAssertion* (AnyFunctionTest | TypedFunctionTest) [*] FunctionAssertion ::= Annotation [Definition: A function assertion is a predicate that restricts the set of functions matched by a FunctionTest. It uses the same syntax as an annotation.] &language; does not currently define any function assertions, but future versions may. Other specifications in the XQuery family may also use function assertions in the future. Implementations are free to define their own function assertions, whose behavior is completely implementation-defined. Implementations may also provide a way for users to create their own function assertions. Note: Although function assertions use the same syntax as annotations, they are not directly related to annotations. If an implementation defines the annotation *blue* and uses it in function declarations, there is no guarantee that it will also define a function assertion *blue*, or that a function assertion named *blue* matches a function declared with the annotation *blue*. Of course, an implementation that does so may be more intuitive to users. Implementations must not define function assertions in the following reserved namespaces; it is an error for users to create annotation assertions in the following reserved namespaces [err:XQST0045]: http://www.w3.org/XML/1998/namespace http://www.w3.org/2001/XMLSchema http://www.w3.org/2001/XMLSchema-instance http://www.w3.org/2005/xpath-functions http://www.w3.org/2005/xpath-functions/math http://www.w3.org/2011/xquery-options Here are some examples of function tests: * function(*) matches any functionDM30. * %assertion function(*) matches any functionDM30 if the implementation-defined function assertion %assertion is satisfied. * function(int, int) as int matches any function with the function signature function(int, int) as int * %assertion function(int, int) as int matches any function with the function signature function(int, int) as int if the implementation-defined function assertion %assertion is satisfied.
If a function assertion is not recognized by an implementation, it is ignored, and has no effect on the semantics of the function test.
(In reply to comment #2) > If a function assertion is not recognized by an implementation, it is ignored, > and has no effect on the semantics of the function test. NOTE: An implementation is free to raise warnings for function assertions that it does not recognize.
An implementation may raise implementation-defined errors or warnings for function assertions, e.g. if the parameters are not correct for a given assertion.
The Working Group has adopted the resolution recorded in comments #1, #2, #3, and #4. Jonathan is encouraged to ensure that the text is clear that function assertions are always predicates that restrict.