Improve reference field - custom representation

[rlouapre]

• Custom representation should be model based so XQuerrail API can still be used.
• The current custom reference function does not provide that.

[rlouapre]

One option would be to pass a model name as second param in @reference.
XQuerrail would invoke recursive-build using this model and annotate the document with usual ref attributes.

@garyvidal what do you think?

[skeptikos]

Wouldn’t it be the third part of the descriptor, e.g.

reference="model:{referenced-model-name}:{reference-model-name|model-function}"

This is a good idea that would achieve backwards compatibility because the function ‘reference’ would be invoked for current model-less reference behavior, and still allow for custom model-reference functions, but make it very easy to implement code-less custom references that copy additional field from the referenced objects.

[skeptikos]

One potential gotcha is that the reference proxy object holds an identifier as a text() child. But an object with attribute()s and a text() child can't simply be JSONified because the text() is an unnamed property.

[rlouapre]

Yes it is the third part.

@ref-id should always be used as identifier to the referenced object

[skeptikos]

Looking at the in-progress branch, sorry to be nitpicky but in base-model.xqy the overloading of multiple meanings for $instance-reference is a bit confusing:

• in model:reference the variable refers to the target of the reference
• in model:build-model-reference an argument of the same name holds either the scalar value of the keyLabel field, OR an instance of the reference object itself

Besides keeping the variable names consistent with what is represented, it would be cleaner if model:build-model-reference were given a single concern and named accordingly, something like decorate-reference-object. Then rather than the dual use of the 4th argument, it should always require some reference proxy object to decorate. It would then be the caller that would synthesize the input object, either a model-defined object or for reverse compatibility a default reference element containing a single text node with the keyLabel value.

[skeptikos]

Thinking about this a bit more, I wonder why this extended reference needs to go in the core framework at all. One already can specify a custom model reference function, and as far as I can see these are the only factors preventing this feature from being implemented that way, without core mods:

• The model name for the reference object needs to be communicated into the model reference function
• It would in fact be best for a systematized way to annotate the reference proxy object with the required attributes

The model-name issue is an artifact of the fact that there is no established way to communicate any additional parameters into the model reference function within the 3-argument ($reference, $model, $param) call that model:get-model-references makes. So I think addressing that in the framework first, along with the annotation support, would be the approach with the biggest win.

Well, not so hard: The $reference argument is the domain:element defining the field holding the reference, so that would be a way to communicate additional static information into the function:

• One could add custom attributes to the domain:element. But that would mess with the domain schema (is there a way to extend in some namespace?)

• Alternately, model:get-model-references does a fn:tokenize on $reference/@reference, but it only accesses up to the third element in the sequence. So a third colon could designate additional sub-arguments which are only accessed by the model function. Thus a format like this could work:

  reference="model:{referenced-model-name}:model-reference:{reference-model-name}"

What do you think of this approach?