Schema Typed Parameters and Return Values in Library Modules

[Michael Kay]

I think if I were writing a library for a vocabulary where schema 
validation is the norm (like FpML, say), and assuming that the schema is 
suitable for use in XQuery (most element names either global or having a 
named complex type) then I would declare the functions with types that 
assume the data is pre-validated.

I wouldn't expect client code to be invoking validate{} explicitly - I 
would expect that most of the time, the function is called to operate 
directly on input data, which is validated at source outside the query. 
(But that might not be how Zorba works, I don't know.)

The main reason is that it's a good idea in an interface definition to 
be as precise as possible about what you expect to cross the interface. 
It helps users reading the code to know the expectations, and it helps 
the compiler too. In my experience it tends to mean that errors in your 
code are detected and reported much closer to the point at which the 
error actually occurred, whether they are detected statically or 
dynamically.

Michael Kay
Saxonica

On 19/07/2010 20:43, David Graf wrote:
> Hello Everybody
>
> At FLWOR/Zorba group, we are having a discussion about the usage of 
> schema typed parameters and return values in the API of library 
> modules. As you might know, the Zorba XQuery engine supports XML 
> schema. Therefore, people like me are thinking about typing parameters 
> and return values of functions of Zorba's library modules with schema 
> types (with 
> http://www.w3.org/TR/xquery/#prod-xquery-SchemaElementTest). But if 
> parameters of functions are types with schema types, a user of the 
> function needs to validate the data before passing it (with 
> http://www.w3.org/TR/xquery/#doc-xquery-ValidateExpr). And to 
> validate, the right schema needs to be imported. Therefore, some 
> people in our group think that the validation should be done inside 
> the modules but the module programmers. And the users should be 
> informed with error messages if something cannot be validated.
>
> Here is a short example:
>
> Variante 1 (param validation by user):
> Module:
> /declare function foo:bar($param as schema-type(aa:bb)) {/
> /  (: xquery code :)/
> /};/
>
> User Query:
> /import schema namespace aa = "http://www.aa.com <http://www.aa.com/>";/
> /
> /
> /let $param := validate { <aa:bb>...</aa:bb> }/
> /return foo:bar($param)/
>
>
> Variante 2 (param validation by module):
> Module:
> /declare function foo:bar($param as elemente(aa:bb)) {/
> /  try {/
> /    let $validated := validate { $param }/
> /    return/
> /      (: xquery code :)/
> /  }/
> /  catch (err:something) {/
> /    fn:error(..., "user, your data is wrong!!")/
> /  }/
> /};/
>
> User Query:
> /declare namespace david = "http://www.david.com 
> <http://www.david.com/>";/
> /
> /
> /foo:bar(<aa:bb>...</aa:bb>)/
> /
> /
>
> Personally, I think the validation of an item should be done by the 
> creator of the item. Therefore, the parameters and the return values 
> should be schema typed. Means, the user validates the parameters, the 
> module programmer validates the return values. In my opinion, this 
> brings a lot of benefits. E.g. the user of a module gets an error 
> message in his own code if he creates a wrong item. Just type safety 
> like in programming languages like Java. The only tiny problem is (in 
> my opinion): almost all XQuery users are not familiar with the 
> validation construct.
>
> The other opinion is: The life for the module user should be made as 
> easy as possible. Therefore, the validation of the parameters should 
> be made by the module programmer. Of course, it easies the usage of a 
> module a little bit. But already the bug fixing gets more complicated 
> because the location of the bug is in the module instead in the code 
> of the user. Therefore, programmers of modules need to give module 
> users very specific error messages of a parameters is not correct. In 
> my opinion, this makes the life of programmers of modules unnecessary 
> complicated.
>
> What do you think about this topic? What should be the best practice?
>
> Regards,
> David
>
>
> _______________________________________________
> http://x-query.com/mailman/listinfo/talk
> http://x-query.com/mailman/listinfo/talk

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://x-query.com/pipermail/talk/attachments/20100719/f3fd7782/attachment.htm