RE: [legalxml-econtracts] Citation-related Reqs

[Peter Meyer <pmeyer@elkera.com.au>]

Hi John,

I have been over your citation related requirements posting. It seems to me
that the issues you raise are all interesting and that there is much work to
be done on this area. I think we will need to focus on just how users will
create links in their documents and how we will avoid dependencies on
particular processing technologies. Personally, I think that most of your
stated conclusions are more design preferences rather than functional
requirements but that will need further discussion.

My immediate concern was to establish whether you are proposing anything
that would cut across the basic clause model development.

As far as I can see, there are only two points that might impact:

Conclusions #2, second and 3rd bullet points
The second point says that DTD content models should be declared as ANY. The
third says that everything is OK with XML Schema definitions.
Its an issue to determine how schema languages are to be supported. This may
be a relevant input into that decision.
For the moment, I believe we should complete the clause model proposal
without dealing with these particular requirements. It does not affect
development of the basic concept that is proposed in the Harrop/Meyer
proposal.

Conclusions #3
This seems to require us to use elements from the XHTML namespace. At least
at the structural markup level, I believe this is fundamentally inconsistent
with the clause model requirements. There is no direct equivalence between
proposed clause model elements and many of the XHTML elements you mention.
XHTML does not provide the needed structure for the wide range of intended
uses. That is why we are developing a new clause model.

Am I correct in assuming that there is no reason to not proceed to finalise
the Harrop/Meyer proposal?

Regards
Peter






>
>
> 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.
>
> To unsubscribe from this mailing list (and be removed from the
> roster of the OASIS TC), go to
http://www.oasis-open.org/apps/org/workgroup/legalxml-econtracts/members/lea
ve_workgroup.php.