[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Citation-related Reqs
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.
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]