Dear all,
please find a first analysis of the eContract XML schema (a 2006 OASIS standard of our domain, https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=legalxml-econtracts ).
We have received requests as to integrate the useful stuff into AKN. This is a systematic analysis of the final schema. There is little comment, as I had little time to write it. We can discuss it in greater detail during the call. Anyhow, most of the proposals are pretty straightforward. The only potentially complicated is discussed in note (16).
To better understand the nesting please use a monospaced font for the rest of the message.
Ciao.
Fabio
--
Fabio
--
=================
eContract example
=================
============================
eContract document structure
============================
19. contract
68. title
59. subtitle
40. metadata
20. contract-front
11. background
12. block
23. date-block
22. date
45. parties
46. party
48. person-record
7. address
41. name
13. body
38. item (outside of a block)
68. title
59. subtitle
12. block
39. item (inside a block)
65. text
32. definition
64. terms
63. term
37. inclusion
61. table
10. back
12. block
23. date-block
22. date
47. party-signature
52. signatory
53. signatory-group
54. signatory-record
55. signature-line
69. witness
9. attachments
8. attachment
==========
Vocabulary
==========
eContract defines 64 elements (listed here as 7. thru 71.) and seven attributes. The grouping in AKN-related categories is mine. They do not group them in any meaningful way.
eContract example
=================
<?xml version="1.0" encoding="utf-8"?>
<contract xmlns="urn:oasis:names:tc:eContracts:1:0">
<title>
<text>Sample of the elements</text>
</title>
<subtitle>This file is to test</subtitle>
<contract-front>
<date-block>
<date><em>Long time ago</em></date>
</date-block>
<parties>
<party></party>
</parties>
</contract-front>
<body>
<item number="1">
<title><text>First level</text></title>
<item number="1.1"><title><text>Second level</text></title>
<item number="1.1.1">
<title><text>Third level</text></title>
<block><text>Content under third level with title.</text></block>
</item>
</item>
<item number="1.2">
<title><text>Second level</text></title>
<block><text>This is a two level list:</text>
<item number="(a)">
<block><text>First level list item.</text></block>
</item>
</block>
</item>
</item>
</item>
</body>
<back>
<party-signature>
<signatory-group>
<block> </block>
<signatory-record>
<signatory id="T0001" xml:lang="ja">
<signature-line id="I0001" xml:lang="en_US">
<text>Mr. Signatory Jr.</text>
<field>Field for a text.</field>
</signature-line>
</signatory>
<witness>
<signature-line id="I0002" xml:lang="fr">
<text>Ms. Witness Arcole</text>
<field>Field for a text.</field>
</signature-line>
</witness>
</signatory-record>
</signatory-group>
</party-signature>
</back>
<attachments>
<attachment> </attachment>
</attachments>
</contract>
* No mixed content anywhere. Element <text> introduces text-only fragments everywhere (exception: <subtitle>. Why?)
* Only one type of hierarchy with one element (<item>).
* Numbers are attributes, headings are elements. Why?
* Many structures acts both as containers of simpler leaves as well as elements in specific expected places in the document.
* Signatures are (pointlessly?) complicated.
* Conditional texts (see further) require some thoughts.
============================
eContract document structure
============================
19. contract
68. title
59. subtitle
40. metadata
20. contract-front
11. background
12. block
23. date-block
22. date
45. parties
46. party
48. person-record
7. address
41. name
13. body
38. item (outside of a block)
68. title
59. subtitle
12. block
39. item (inside a block)
65. text
32. definition
64. terms
63. term
37. inclusion
61. table
10. back
12. block
23. date-block
22. date
47. party-signature
52. signatory
53. signatory-group
54. signatory-record
55. signature-line
69. witness
9. attachments
8. attachment
==========
Vocabulary
==========
eContract defines 64 elements (listed here as 7. thru 71.) and seven attributes. The grouping in AKN-related categories is mine. They do not group them in any meaningful way.
Entries we can directly map onto akoma Ntoso are annotated with (-). The rest have a numbered reference [n] discussed in the following.
Inlines
=======
We can divide inlines in presentation, semantic, and structural (i.e., they are only allowed within specific structures). In addition images and x-include, which I will not discuss further.
Presentation inlines
--------------------
33. em (-)
49. phrase (-)
56. statutory-em (1)
57. strike (-)
58. sub (-)
60. sup (-)
(1) statutory-em is described as follows: "This is used to mark up content that must be emphasized as per a particular statute. Presumably, the application program will render the contract emphasizing the text as required by that statute. The TC recognized this need in [Min0216]." For statutory-em, my proposal is simply <i class="statutory">...</i>
Semantic inlines
----------------
42. note (2)
43. note-in-line (2)
41. name (3)
7. address (3)
50. reference (4)
14. citation (4)
36. field (5)
16. conditional (6)
(2) Element note is either <noteref> or <authorialNote>. Element note-in-line is simply <noteref/authorialNote placement="inline">
(3) Elements name and address are used to describe people inside element person-record. proposal: <person> and <location> respectively.
(4) Element reference is clearly <ref>. Element citation is described as "the name by which a referenced work is cited". No example is given. I do not know.
(5) element field: "A field is a generic element that can be used to mark up a unit of information in the contract that is either captured from the user, inserted from a database, generated by a processing application such as a cross reference tool, or extracted from the contract for other uses, such as to populate a contract-management database." Example given:
<definition>
<term>BNML Standard Schema</term>
<block>
<text>means the XML Schema called Pay <field source="ida" name="PaymentAmount"/>.</text>
</block>
</definition>
I woud use <placeholder refersTo="#PaymentAmount"> or possibly <fillIn refersTo="#PaymentAmount">.
(6) element conditional is an inline text that only appears if a condition is met. Use <span>. For the specification of the condition, see the discussion in note (16).
Structural inlines
------------------
22. date (7)
46. party (8)
64. terms (9)
63. term (9)
52. signatory (10)
53. signatory-group (10)
54. signatory-record (10)
55. signature-line (10)
(7) Use <date> for date
(8) We should differentiate between individuals and organizations, and use <person> and <organization> accordingly.
(9) we have term, we do not have terms which is simply a grouping algorithm for individual term. I would skip terms.
(10) Frankly I would not give a big deal of attention to signatures. We already have them, and have <fillIn> for signature-line.
Structures
==========
19. contract (11)
68. title (12)
59. subtitle (12)
40. metadata (-)
20. contract-front (-)
11. background (-)
13. body (-)
38. item (-)
12. block (-)
65. text (-)
10. back (-)
9. attachments (-)
8. attachment (-)
23. date-block (13)
45. parties (13)
48. person-record (13)
32. definition (13)
47. party-signature (13)
52. signatory (13)
37. inclusion (14)
69. witness (15)
(11) A contract contains a title and subtitle, metadata, a front, a body, a back and some attachments. We shall create a new document type
<akomaNtoso>
<contract>
...
</contract>
</akomaNtoso>
(12) We need to wrap title and subtitle inside a container (<coverPage>), and move the position of metadata before them. No big deal.
(13) These are specialized containers. My idea is to ignore them, they only serve to group together interesting inlines (date, party, signatures, terms, etc.). At most use a <container class="x">.
(14) element inclusion is "a generic container element for content that is distinct from the narrative, such as quotations, annotations, notes and examples. It is also used to provide a title and number on graphical objects and tables. Typically, the inclusion element contains content that is separate from the main contract provisions for automatic number of layout purposes." We have a variety of different ways to express these needs. An hypothesis would be to use <??? status="editorial">, where ??? could be equivalently an inline, a block, a container or an hcontainer depending on the context. Alternatively we could use element <scene> but it is not available everywhere.
(15) A witness is a special type of signatory, and therefore I would solve it with <signature class="witness">.
Metadata
========
24. dc:contributor (-)
25. dc:creator (-)
26. dc:date (-)
27. dc:description (-)
28. dc:publisher (-)
29. dc:rights (-)
30. dc:subject (-)
31. dc:title (-)
18. conditions (16)
17. condition (16)
(16) Element conditions is a metadata element that contains the list of condition element to activate on the document. Each condition specifies a condition identifier. Inside the contect, the conditional element will refer to one or the other of the condition identifiers, as follows:
<contract>
<conditions>
<condition name="US">United States</condition>
<condition name="AU">Australia</condition>
</conditions>
...
<block condition="US">
<text>A US-specific statement in the contract.</text>
</block>
<block condition="AU">
<text>An Australian-specific statement in the contract.</text>
</block>
<block>An unconditional block with
<conditional condition="US">American</conditional>
<conditional condition="AU">Australian</conditional>-specific wordings.
</block>
</contract>
This allows to create multiple different variants of the text depending on which condition is active. This is my main concern: is it a shorthand for different variants (FRBR Expressions) or is it a single _expression_ that contains text that can disappear? Could we just use @wId and @alternativeTo? Would the following be appropriate?
<akomaNtoso>
<contract contains="multipleVersions">
Inlines
=======
We can divide inlines in presentation, semantic, and structural (i.e., they are only allowed within specific structures). In addition images and x-include, which I will not discuss further.
Presentation inlines
--------------------
33. em (-)
49. phrase (-)
56. statutory-em (1)
57. strike (-)
58. sub (-)
60. sup (-)
(1) statutory-em is described as follows: "This is used to mark up content that must be emphasized as per a particular statute. Presumably, the application program will render the contract emphasizing the text as required by that statute. The TC recognized this need in [Min0216]." For statutory-em, my proposal is simply <i class="statutory">...</i>
Semantic inlines
----------------
42. note (2)
43. note-in-line (2)
41. name (3)
7. address (3)
50. reference (4)
14. citation (4)
36. field (5)
16. conditional (6)
(2) Element note is either <noteref> or <authorialNote>. Element note-in-line is simply <noteref/authorialNote placement="inline">
(3) Elements name and address are used to describe people inside element person-record. proposal: <person> and <location> respectively.
(4) Element reference is clearly <ref>. Element citation is described as "the name by which a referenced work is cited". No example is given. I do not know.
(5) element field: "A field is a generic element that can be used to mark up a unit of information in the contract that is either captured from the user, inserted from a database, generated by a processing application such as a cross reference tool, or extracted from the contract for other uses, such as to populate a contract-management database." Example given:
<definition>
<term>BNML Standard Schema</term>
<block>
<text>means the XML Schema called Pay <field source="ida" name="PaymentAmount"/>.</text>
</block>
</definition>
I woud use <placeholder refersTo="#PaymentAmount"> or possibly <fillIn refersTo="#PaymentAmount">.
(6) element conditional is an inline text that only appears if a condition is met. Use <span>. For the specification of the condition, see the discussion in note (16).
Structural inlines
------------------
22. date (7)
46. party (8)
64. terms (9)
63. term (9)
52. signatory (10)
53. signatory-group (10)
54. signatory-record (10)
55. signature-line (10)
(7) Use <date> for date
(8) We should differentiate between individuals and organizations, and use <person> and <organization> accordingly.
(9) we have term, we do not have terms which is simply a grouping algorithm for individual term. I would skip terms.
(10) Frankly I would not give a big deal of attention to signatures. We already have them, and have <fillIn> for signature-line.
Structures
==========
19. contract (11)
68. title (12)
59. subtitle (12)
40. metadata (-)
20. contract-front (-)
11. background (-)
13. body (-)
38. item (-)
12. block (-)
65. text (-)
10. back (-)
9. attachments (-)
8. attachment (-)
23. date-block (13)
45. parties (13)
48. person-record (13)
32. definition (13)
47. party-signature (13)
52. signatory (13)
37. inclusion (14)
69. witness (15)
(11) A contract contains a title and subtitle, metadata, a front, a body, a back and some attachments. We shall create a new document type
<akomaNtoso>
<contract>
...
</contract>
</akomaNtoso>
(12) We need to wrap title and subtitle inside a container (<coverPage>), and move the position of metadata before them. No big deal.
(13) These are specialized containers. My idea is to ignore them, they only serve to group together interesting inlines (date, party, signatures, terms, etc.). At most use a <container class="x">.
(14) element inclusion is "a generic container element for content that is distinct from the narrative, such as quotations, annotations, notes and examples. It is also used to provide a title and number on graphical objects and tables. Typically, the inclusion element contains content that is separate from the main contract provisions for automatic number of layout purposes." We have a variety of different ways to express these needs. An hypothesis would be to use <??? status="editorial">, where ??? could be equivalently an inline, a block, a container or an hcontainer depending on the context. Alternatively we could use element <scene> but it is not available everywhere.
(15) A witness is a special type of signatory, and therefore I would solve it with <signature class="witness">.
Metadata
========
24. dc:contributor (-)
25. dc:creator (-)
26. dc:date (-)
27. dc:description (-)
28. dc:publisher (-)
29. dc:rights (-)
30. dc:subject (-)
31. dc:title (-)
18. conditions (16)
17. condition (16)
(16) Element conditions is a metadata element that contains the list of condition element to activate on the document. Each condition specifies a condition identifier. Inside the contect, the conditional element will refer to one or the other of the condition identifiers, as follows:
<contract>
<conditions>
<condition name="US">United States</condition>
<condition name="AU">Australia</condition>
</conditions>
...
<block condition="US">
<text>A US-specific statement in the contract.</text>
</block>
<block condition="AU">
<text>An Australian-specific statement in the contract.</text>
</block>
<block>An unconditional block with
<conditional condition="US">American</conditional>
<conditional condition="AU">Australian</conditional>-specific wordings.
</block>
</contract>
This allows to create multiple different variants of the text depending on which condition is active. This is my main concern: is it a shorthand for different variants (FRBR Expressions) or is it a single _expression_ that contains text that can disappear? Could we just use @wId and @alternativeTo? Would the following be appropriate?
<akomaNtoso>
<contract contains="multipleVersions">
...
<p wId="p_15" eId="p_15US" alternativeTo="p_15AU">
A US-specific statement in the contract.
</p>
<p wId="p_15" eId="p_15AU" alternativeTo="p_15US">
An Australian-specific statement in the contract.
</p>
<p eId="p_16">An unconditional block with
<span wId="p_16__span_1" eId="p_16__span_1US"
alternativeTo="p_16__span_1AU">American</span>
<span wId="p_16__span_1" eId="p_16__span_1AU"
alternativeTo="p_16__span_1US">Australian</span>-specific wordings.
</p>
</p>
<p wId="p_15" eId="p_15AU" alternativeTo="p_15US">
An Australian-specific statement in the contract.
</p>
<p eId="p_16">An unconditional block with
<span wId="p_16__span_1" eId="p_16__span_1US"
alternativeTo="p_16__span_1AU">American</span>
<span wId="p_16__span_1" eId="p_16__span_1AU"
alternativeTo="p_16__span_1US">Australian</span>-specific wordings.
</p>
...
</contract>
</akomaNtoso>
Special Structures
==================
X-Include (17)
70. xi:fallback (17)
71. xi:include (17)
</contract>
</akomaNtoso>
Special Structures
==================
X-Include (17)
70. xi:fallback (17)
71. xi:include (17)
(17) We are not going to use X-Include.
Other
=====
Table
15. colspec (-)
34. entry (-)
51. row (-)
61. table (-)
62. tbody (-)
66. tgroup (-)
67. thead (-)
Images
21. data (-)
44. object (-)
35. fallback (-)
Attributes
==========
@id (-)
@xml:lang (-)
@class (-)
@number (-)
@condition (16)
@orient (18)
@stop-contents (19)
(17) "This attribute specifies whether the element contents should be rendered as portrait or landscape". I refuse to even consider this attribute.
(18) "This stops the generation of table-of-contents entries for the elements contained within this element." We have nothing of the sort. Do we need it? Do we care?
CiaoOther
=====
Table
15. colspec (-)
34. entry (-)
51. row (-)
61. table (-)
62. tbody (-)
66. tgroup (-)
67. thead (-)
Images
21. data (-)
44. object (-)
35. fallback (-)
Attributes
==========
@id (-)
@xml:lang (-)
@class (-)
@number (-)
@condition (16)
@orient (18)
@stop-contents (19)
(17) "This attribute specifies whether the element contents should be rendered as portrait or landscape". I refuse to even consider this attribute.
(18) "This stops the generation of table-of-contents entries for the elements contained within this element." We have nothing of the sort. Do we need it? Do we care?
Fabio
--
Fabio Vitali The sage and the fool
Dept. of Informatics go to their graves
Univ. of Bologna ITALY alike in this respect:
phone: +39 051 2094872 both believe the sage to be a fool.
e-mail: fabio@cs.unibo.it Where, then, may wisdom be found?
http://vitali.web.cs.unibo.it/ Qi, "Neither Yes nor No", The codeless code
--
Fabio Vitali The sage and the fool
Dept. of Informatics go to their graves
Univ. of Bologna ITALY alike in this respect:
phone: +39 051 2094872 both believe the sage to be a fool.
e-mail: fabio@cs.unibo.it Where, then, may wisdom be found?
http://vitali.web.cs.unibo.it/ Qi, "Neither Yes nor No", The codeless code