autocomplete is a quite powerful but also fairly involved component. We've looked at how form authors use the autocomplete in Orbeon Forms, and found that in most cases they use it as an alternative to a combo box or radio buttons, for cases where the number of items to choose from is too large to be displayed in its entirety. The autocomplete then acts as a search interface to locate one specific item amongst many. In some cases, the number of items is so large, that it not only doesn't make sense to display all the items to users: it also wouldn't be reasonable to load them all in Orbeon Forms, on the server-side. In those cases, as users type in the field, you want the form to make a request to a service to load the items relevant to what users typed so far. To make that use case easier, last year we introduced the resource mode.
But the resource mode had one flaw. To see exactly what it is, let's first backtrack a bit. Items have two components: the label, which is shown in the UI, say "California", and the value, which is stored as part of the form data when users make a selection, say "CA". This is consistent with how things are done in XForms for all XForms selection controls. The trouble is that when users load a form where a value has already been selected, say "CA", we didn't know what to show in the autocomplete. Of course, you say, show "California"! But how can the autocomplete know that the label for "CA" is "California"? In resource mode, form authors give the autocomplete a service allowing the component to find items based on labels; but here we want to do the opposite: find a label based on the value. We could have asked form authors to provide another service, returning the label for a value. But this would have put more burden on form authors and could have caused performance problems on forms with several autocompletes, causing many service calls. So instead, we added a new labelref attribute, simply pointing to a node in the instance that will be used to store the label, so the component can store both the value and label of the selected item.
And for those of you using Form Builder, all of this is entirely transparent. You can forget what you just read about labelref, as Form Builder will take care of adding that attribute as well as a corresponding node in the instance.