Citation-related Reqs

["John McClure" <jmcclure@hypergrove.com>]

For discussion, here's my statement of some requirements for the Functional
Specification. These are now formally proposed for consideration by the TC.
Regards,
John


1. Citation Links
==============
Contracts contain citable material, normally, its structural elements such as
Clauses, Tables, List Items, and so on. Citations such as these appear either
internal to a contract, or external to the contract. In both circumstances, when
a hyperlink associated with the citation is activated, one's browser "jumps" to
that location -- this is literally the foundation of the Internet.

HTML <anchor> tags are the common mechanism for linking to elements within a
document, or within another document.  Less common are XML Link (XLL) attributes
that may be placed onto XML elements. In both cases, an "href" attribute
contains a Universal Resource Identifier (URI) that specifies either an
identifier on the target element, or a path-to the target element.

A. The HTML Anchor Element

The simplest coding possible for a citation is <a href='url#id'>Clause 2.1</a>
where the "id" specified in the href attribute is the same "id" value on the
element corresponding to Clause 2.1. For instance, if the clause is coded as
<Block id='NonCompetitionClause'> then a link to it would be <a
href='url#NonCompetitionClause'>Clause 2.1</a>.

At issue with this approach is that the anchor-coder must know a-priori the "id"
of the target. To know this, the anchor-coder must examine the internals of the
target file, find the target element, and then note its id, if one is present.
If the target XML file references an XSL stylesheet (or other transformative
mechanism) then the anchor-author must generate the target presentation (if such
is the intention of the stylesheet) using a tool other than a browser, and then
find the target element in the output, and then note its id, if one is present.

This approach appears fraught with difficulties stemming from file
accessibility, tools support, user technical skills level, permissiveness of
non-unique "id"s in an X/HTML environment, non-traditional validation
mechanisms, and processing overhead.

B. The XPath Solution

The next simplest coding possible is for a citation that references the
structural elements within the contract document, that is, one that identifies a
"path" of elements that should be followed to locate the target element. For
Clause 2.1, for instance, the href="url#xp(Block[2]/Block[1])" could represent
the clause, holding aside the containing structure(s) for the clause. For this
XPATH expression to operate correctly, elements named "Block" must appear in the
file being examined by the XPath mechanism. If the target XML file references an
XSL stylesheet (or other transformative mechanism) then the XPATH expression is
resolved against the output from the XSL transformation. If the transformation
yields an XHTML output, then the <Block> elements must appear in the XHTML
datastream.

If the target XML file references a CSS stylesheet (or other non-transformative
mechanism) then the XPath expression can be resolved against the native XML
file.

This approach seems promising. It is easy to create the href's URI from the
manner of the citation itself, without pre-examining the target file. A
document's "citability" cannot be controlled by the author. It is implicit;y
validatable by the standard DTD mechanism. Its drawback, however, is that XPath
is not yet implemented widely, perhaps a poor choice upon which to base a
standard that is meant to be used immediately.

C. The XPath Solution, Alternatives

Variations of XPath expressions are possible. Instead of enveloping the target
element, the strategy is to place a special attribute on the target element. The
XPath expression would then specify the attribute to be sought. The present
problem of XPath support, however, remains an issue despite the refinements of
XPath expressions. This would eliminate the use of, for example,
LegalXML-namespace qualified "names" attributes and rdf:ID attributes, as the
primary mechanism for identifying the structural elements within an XML
contract.

D. The HTML Approach, Revisited

An appropriate response is to establish, as a standard, an algorithm for the
"id" value that must be placed onto structural elements in the output stream to
any transformative process such as XSL, or directly onto XML elements subject to
a non-transformative process such as CSS.

The "id" for Clause 2.1 would be "Block2.1".

The advantages of this approach is that it can be used immediately. Its drawback
of course is the voluntary nature of the standard: an author may cause a legal
document's content un-citable, simply and inadvertently by a mis-coding of the
"id" value. Of signficant additional concern is the complexity of mapping
required between characters allowed within a caption number, and those commonly
found in captions of a legal document.

Conclusions #1
==============
For all practical purposes, LegalXML has only one chance to establish the
mechanism most appropriate to guaranteeing that its documents' content is
citable material. It would be greatly troubling -- incurring large costs -- to
the community should LegalXML establish one coding mechanism for citations, and
then to change to another in a few years. Given this reality, the functional
requirement for the eContract is stated:

	o The eContract Technical Specification shall support as a prime
	requirement, the ability to externally link to any structural contract
	element, without requiring foreknowledge of the value(s) of any
	element attribute(s).

	o The eContract Technical Specification shall exclusively support
	positional XPATH-type citations to its structural contract elements.
	Citations are required to resolve to XML elements that are present
	in the output stream of any transformative process, or in the input
	stream of any non-transformative process, as executed prior to the
	legal material's presentation to a party to a contract.


2. Namespaces and Citations
==========================
One practical implication of embedding LegalXML markup within an XHTML
datastream, regardless of whether that datastream is one transformed or not, is
that, for the stream to be valid, the LegalXML elements must be
namespace-qualified. The same namespace URI must be specified both within the
target file and within the linking application. For instance, assuming that the
LegalXML namespace is http://www.legalxml.org/v1, then markup in the source file
would be

<a xmlns:lgl='http://www.legalxml.org/v1'
	href='url#xp(lgl:LegalDocument//lgl:Block[2]/lgl:Block[1])'>Clause 2.1</a>

and the markup in the presentation material would be

<html xmlns:lgl='http://www.legalxml.org/v1' xmlns='xhtml uri'>
<body>
       <lgl:LegalDocument>
	<h1>my title</h1>
	<lgl:Block>
	       <p><b>Clause 1.</b> Clause 1 text</p>
	</lgl:Block>
	<lgl:Block>
	       <p><b>Clause 2.</b> Clause 2 text</p>
	       <lgl:Block>
	               <p><b>Clause 2.1</b> Clause 2.1 text</p>
	       </lgl:Block>
	</lgl:Block>
</body>
</html>

Conclusion #2
============
This approach meet our objective to identify (and validate) the structure of a
contract, without sacrificing the public's ability to choose the XML dialect
used for presentation of their contracts. If there are other items in the
contract that LegalXML desires to identify in the presentation stream, then
equivalent elements must be fashioned to encapsulate that content within the
contract document, for instance, <LegalDocumentTitle>. Given this logic, the
following conclusions emerge:

	o The eContract Technical Specification shall define a URI to identify
	an XML namespace consisting of eContracts elements, so as to
	support mixed-namespace datastreams encoded in accordance with
	the W3C XML Namespace Technical Recommendation.

	o The eContract Technical Specification shall define all XML elements
	in a DTD with a content model of ANY, so as to avoid dictating the XML
	dialect in which contract content is to be presented to contract parties
	and to avoid "repeating" the DTD of any dialect possibly used by a
	document author creating presentation material.

	In XML Schema definitions, the eContract Technical Specification shall
	define the proper containment model for its elements, but nonetheless
	shall allow elements from external namespaces within the content of
	any and all LegalXML elements.


3. Citing Paragraphs, Tables, and Lists
==================================
Reports detailing LegalXML's ability to re-use other established namespaces have
focused on those namespaces' lack of structured elements that can adequately
represent the structure of a contract or the structure of clauses within the
contract.

However, container elements -- such as <lgl:Block> -- do provide the document
structure that those dialects are missing. Furthermore, the provision to support
namespaces gives LegalXML the opportunity to specify elements that would be
honored in citations to common presentation elements such as paragraphs, tables,
and lists.

For instance, a reasonable citation is to the 5th table in Clause 2.1 is:

<a xmlns:lgl='http://www.legalxml.org/v1' xmlns:html='xhtml uri'

href='url#xp(lgl:LegalDocument//lgl:Block[2]/lgl:Block[1]//html:table[5])'
>Clause 2.1, Table 5</a>

No concern has been expressed about the feasibility of re-using XHTML
paragraphs, tables, lists, images, lines, or any of its myriad
presentation-specific elements, such as <b>, to represent the content of
structural contract elements.

Authors creating non-XHTML presentation material are accordingly required to
encapsulate their non-XHTML markup within both LegalXML namespace elements and
within XHTML namespace elements. For instance, an SVG datastream representing a
legal document would be required to contain both XHTML and LegalXML container
elements for their SVG markup.

Conclusion #3
=============
Because proposals for paragraphs, lists, tables and other items simply (are
expected to) mirror the function of directly equivalent XHTML elements, there is
no reason not to designate those XHTML elements as valid for citation purposes.
Thus:

	o The eContract Technical Specification shall reuse elements from
	the XHTML namespace for paragraphs, tables, lists, lines, images,
	and other elements as deemed appropriate, to represent the text
	content of structural contract elements. Citation to content within
	a legal document shall be supported by the use of these XHTML
	elements.

	o The eContract Technical Specification shall not establish text or
	image content 	elements that correspond to elements found in the
	XHTML namespace.


4. Contract Metadata
===================
There are several kinds of metadata, two of which are (1) that concerned with
specific content represented in the document, such as the "value" of a contract;
and (2) that concerned with document indexing, for instance, the 14 elements
constituting the Dublin Core namespace.

For metadata, the W3C is establishing a set of links that are placed by authors
into the <head> element of (XHTML) datastreams whose "type" attribute indicates
the kind of metadata. This is eminently reasonable, and, using a citation
mechanism such as described here, is quite adequate for making statements
"about" a contract, "about" a structural element within a contract, and or
"about" a presentation element within a contract. There is no need to establish
a separate mechanism for pointing to metadata about the contract from within the
contract.

Conclusion #4
============

	o The eContract Technical Specification shall not manufacture its
	own mechanism for relating a contract to its metadata. The
	Specification shall not require metadata to be placed within a
	presentation datastream and shall support standard W3C
	mechanisms for this function.

	o The eContract Technical Specification shall establish its own XML
	protocols for metadata about a contract, its parts, or its content.
	These protocols must conform to the metadata protocol established
	by the W3C, namely, the Resource Description Framework, within
	which Dublin Core elements may be specified.

	Through these protocols only shall the Specification address and
	satisfy any and all functional requirements concerned with drafting,
	negotiation, execution, management, or litigation or mediation
	activities occurring with respect to the contract.


Final Conclusion
===============

	o The eContract Technical Specification shall provide explicit
	guidance to the wider community for the creation of presentation
	material that preserves the citability of structural and content
	elements within legal documents. In particular, citations to physical
	layout items such as document sections, pages, footnotes, and
	specific lines of text, shall be addressed.