Generic structural locator?

[AndrewSales]

xvrl/schema/xvrl.rnc

Lines 92 to 100 in 19438c4

	attribute xpath {
	xsd:string { pattern = "/?([^/]+/)*[^/]+" }?
	}
	|
	(
	# these are different syntaxes to address JSON documents:
	attribute xpath-map-array { xsd:string }
	| attribute json-pointer { xsd:string }
	| attribute JsonPath { xsd:string }

It really is a question -- I can see the merit of a set of explicit attribute names, but this could well expand/change in the case of JSON. Also, might some circumstances require them not to be mutually exclusive (e.g. locators reported in more than one JSON location syntax)?

Is the below a bridge too far?

<location line='5' column'3'>
  <structural type='xpath'>/foo/bar</structural>
</location>

[gimsieke]

We already went from attribute to element, we can also go to element with elements.

Alternatively we can refrain from trying to be too smart about which attributes might be mutually exclusive and just allow the whole lot of non-namespaced attributes, plus arbitrary attributes in namespaces. (Then people who come up with a new JSON path notation need to create an XML namespace for their notation, which they certainly will decline to do, out of spite and vile hatred towards XML.)

[dmj]

As I see it we will have zero or more information items with different kinds location information. Thus I would prefer something like:

locations = element locations { location* }
location = element location {
    attribute vocabulary  { xs:Name }
  & text
}

E.g.

<locations>
  <location vocabulary = "xpath">/foo/bar/baz</location>
  <location vocabulary = "text">5,3</location>
</locations>

(I think my idea is to keep distinct information items in distinct elements.)

[tgraham-antenna]

If I was validating the formatting represented by the Area Tree XML output of AH Formatter, then I may want to record some or all of:

• Page number (physical or logical)
• Region
• Column
• X-Y position
• Size

Up until the comment by @dmj (and because I don't experience spite and vile hatred towards either XML or Namespaces in XML), I would have assumed that specialised location information such as that would require attributes in a separate namespace.

If XVRL went in the direction that @dmj suggests, then I'd be looking to put at least one more level of identifier on location in addition to the vocabulary. The pieces are really one vocabulary, but I wouldn't want to have to concatenate them all into some structured text representation just to make them fit into the value of one element.

[dmj]

Right, this makes sense. Thus: The @‍vocabulary attribute specifies the content model of the location element. A consuming application should be able to tell by looking at this attributes value whether it can do something with the locator or not.

[tgraham-antenna]

Sorry, that's too cryptic for me. Can you provide an example?

[dmj]

Sure. The XML (just the locations)

<locations>
  <location type="xpath" xpath="/foo/bar/baz"/>
  <location type="provenance" document="file:///C:/myfile.docx!word/document.xml" xpath="/w:document/w:body/w:p[12]"/>
  <location type="areatree" page="1" region="…" column="…"/>
</locations>

In the Schema

locations = element locations {
   location+
}

location = element location {
   location.model
}

location.model = empty

location.model |=
   attribute type { "xpath" }
 & attribute xpath { text }
 & empty

location.model |=
   attribute type { "provenance" }
 & attribute document { text }
 & attribute xpath { text }
 & empty

location.model |=
   attribute type { "areatree" }
 & attribute page { string }
 & attribute region { string }
 & attribute column { string }
 & empty

[AndrewSales]

Isn't the problem here then that we are trying to delimit an (more or less) unlimited set of location criteria?
That would seem to bring us back to what are essentially key-value pairs, expressed as vocab:value or as @tgraham-antenna said, namespaced-attribute:value.

I interpret his comment

I wouldn't want to have to concatenate them all into some structured text representation just to make them fit into the value of one element

to mean

<location vocabulary='pageNumber'>xxx</location>
or
<location ahf:pageNumber='xxx'/>

is preferable to

<location type="areatree" page="1" region="…" column="…"/>

so that each reported location is atomic.

[gimsieke]

Either that, or

<location vocabulary="fo:area-tree">
  <arbitrary-content-here/>
</location>

I’d prefer Andrew’s proposal: Individual location elements. If you have a @vocabulary attribute on location, you probably don’t want to attach your custom location attributes on the same level as @vocabulary. But having a sub-element for the sole purpose of attaching other attributes to it seems a bit verbose.

On the other hand, if all your attributes have distinct names anyway, you can stick them all to a single location element:

<location fo:page-number="4" fo:page-name="ii" fo:region="foo" 
  fo:column="1" fo:x="720" fo:y="1440" … xpath="/fo:block[1]/…"/>

Is the size information something that may be expressed as name/value pairs (attributes), or do we need to allow more elaborate structures for it? If so, location may well have namespaced child elements in addition to attributes.

I concur with Andrew that we cannot anticipate all possible location vocabularies. Therefore it makes sense to allow any namespaced attribute (or any number of namespaced attributes) on location. People who want to have possible attributes/values restricted by a schema can always include the basic XVRL RNC and overwrite the location pattern (or create an epischema!).

The question remains whether there are special attributes, such as @line, @column, or @xpath, that are considered so common that they don’t need a namespace and are part of the base XVRL grammar.

[tgraham-antenna]

This prompted my concern:

  <location vocabulary = "text">5,3</location>

What I don't want that to lead to is:

<location type="areatree">1, 1, , 150.4, 12.04</location>

It now occurs to me that '5,3' may have been a European '5.3'. If so, expect a new issue about defining the number format.

---

I do/did think that it's useful to identify the vocabulary that defines what the location value means.

Namespaced attributes can sort-of do that for you, if you're willing to find all the unique namespace URIs of the attributes and try to make sense of each URI. QNames in content (e.g., vocabulary="fo:area-tree" could do that, too, though you'd have to find the namespace that goes with the namespace prefix.

Requiring something at the other end of the namespace URI that defines the meaning of the location would add a whole lot of machinery to XVRL processing. (XML Catalogs, anybody?)

---

There really is a need for supporting arbitrary location types.

@gimsieke's example uses fo:areatree as if there is one format, but, for starters, Antenna House has its Area Tree XML, RenderX has its own, and FOP has two. AH Formatter reports lengths, sizes, etc., in whatever unit was used in the source document, at least one of the FOP formats reports things in 'millipoints', and xmlroff reports/reported things in 1/1024 pt.

---

@xpath might work as an unnamespaced attribute, but I could contemplate reporting the XPath of a location in the Area Tree XML and the XPath of the corresponding location in the source document. How would two XPaths be reported?

[gimsieke]

@gimsieke's example uses fo:areatree as if there is one format, but, for starters, Antenna House has its Area Tree XML, RenderX has its own, and FOP has two. AH Formatter reports lengths, sizes, etc., in whatever unit was used in the source document, at least one of the FOP formats reports things in 'millipoints', and xmlroff reports/reported things in 1/1024 pt.

Maybe one should be able to annotate, in the metadata, not only the name and version of the validator application but also name and version of the application that created the validated data to which the location info pertains.

@xpath might work as an unnamespaced attribute, but I could contemplate reporting the XPath of a location in the Area Tree XML and the XPath of the corresponding location in the source document. How would two XPaths be reported?

Maybe change provenance in a way that it can hold location information, too:

<metadata>
  <creator name="Apache FOP" version="2.3"/>
  <validator name="…" version="…"/>
</metadata>
<report>
  <location xpath="/areaTree/pageSequence[1]/pageViewport[1]/page[1]/regionViewport[3]/regionBody[1]/mainReference[1]/span[1]/flow[1]/block[3]/block[1]/block[1]/block[1]/block[1]/block[1]/block[1]/lineArea[1]/text[1]/word[1]" 
    line="1" column="41978"/>
  <provenance>
    <location href="file:///C:/Users/gerrit/Desktop/Untitled1.xml" 
      xpath="/Q{http://docbook.org/ns/docbook}article/Q{http://docbook.org/ns/docbook}sect1[1]/Q{http://docbook.org/ns/docbook}title[1]" 
      line="18" column="16"/>
  </provenance>
  …

[gimsieke]

I’d prefer to keep location attributes as an adequate name/value mechanism that supports namespaces natively (in contrast to namespaced @type attribute values, see Tony’s “QNames in content” comment above).
All attributes (@xpath, jsonpath, @jsonpointer, octet-position) may be used for location simultaneously. Previously @xpath and the JSON selectors were mutually exclusive. But I wanted to allow XPath selectors such as .(2)('mykey') in order to navigate to the second item of a JSON array that is a map with a key mykey.
Mutual exclusions may be defined as Schematron rules.