XForm language

[adammichaelwood]

We need to talk about the meaning and usage of several words and concepts related to XML and XForms.

• block
• instance
• model
• variable

(Probably a few other things.)

Between @mish24's work on pulling in the Form Design documents, and my work on the OpenRosa standards, this is becoming critical to clear-headed thinking and writing... and my current feelings are that the existing documentation and specs don't make these as clear as they should, and there are some inconsistencies in the way things are talked about.

I'm going to review the XForm specification and gather a few examples.

[adammichaelwood]

What is the name of the element immediately inside <instance>, which (seems to) define the form's structure?

In existing docs, the following structure is discussed and shown by example:

<instance>
          <data xmlns:jr="http://openrosa.org/xforms"
                id="example.org:myFormId"
                version="1" >

but that element isn't always labeled data -- for example, in the all-widgets form (as output by the online XLSForm utility):

<instance>
  <all-widgets id="all-widgets" version="2017061601">

In at least one doc, this element is called "an instance".

[adammichaelwood]

What does the word model mean?

• Does it mean different things in different contexts?
• Can we limit its meaning to one thing going forward?

Some of the documentation seems to refer to a blank form as a "model", but it isn't always clear if "model" in that context refers to the whole XML document, or just a portion of it.

Meanwhile, model is an element in a blank XForm.

[adammichaelwood]

What is the relationship between the blank XForm and the XForm that represents a complete form?

In reality (I think), a person answers a bunch of question in-app, and a new XML document is generated to include those answers. But some of the documentation seems to suggest a mental model in which the XForm is "filled in" and submitted.

I know some of this is just due to the mental model of filling-in paper forms. But the suggestion is that the completed form is a copy of the blank form, but with response data added to it. But then, when I look at actual blank forms and their completed instances, this doesn't seem to be precisely the case.

[lognaturel]

At a high level, I think that all things XForms and XML should now live in the developer docs with most of it at https://opendatakit.github.io/xforms-spec/. There are some rare cases in which users may want to edit XML but I don't think it happens commonly at all. That has some implications for @mish24's #217, I think the contents there will need to be heavily revised. It would be ok to first pull it in as-is and then find homes for the different pieces as long as it's made very clear that today people generally don't need to touch the XML. @mish24 and @adammichaelwood have already been discussing this in the comments there.

Consider submitting clarification pull requests to https://opendatakit.github.io/xforms-spec/

I'd have to see the context but I imagine "block" just refers to a container tag and its children.

I think the description of instance and model at https://opendatakit.github.io/xforms-spec/#instance should be augmented with some of the information in the abstract at https://www.w3.org/TR/xforms/

The child of the primary instance can have any name. I think this is well described at https://opendatakit.github.io/xforms-spec/#primary-instance

[adammichaelwood]

The child of the primary instance can have any name. I think this is well described at https://opendatakit.github.io/xforms-spec/#primary-instance

I gathered the tag can have any label. Do we refer to that abstract idea as anything other than "the child of the instance"?

[adammichaelwood]

I imagine "block" just refers to a container tag and its children.

It does. But the more precise word would be "element" or "document node"

[adammichaelwood]

it's made very clear that today people generally don't need to touch the XML.

This fact, by itself, covers a multitude of issues.

[adammichaelwood]

a solution to most of the general problem here has, I think, emerged.
Some specific conversation around the definition of "form" (#605) might go somewhere,
but I think this issue can go away...