OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

legalxml-econtracts message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Development steps for TC specification - revised

Dear TC members,

At our last meeting, I was asked to provide an updated list of steps we need
to take to continue our development. This is to include the original list in
my email of 22 September, the issues raised by Rolly Chambers on 18 October
and any other issues that have arisen. I have made a few minor changes to
the previous issues for the purpose of clarification.

Shortly, I will be re-issuing the schema with some minor technical
corrections to deal with validation problems encountered by Rolly. This
should not affect consideration of the listed issues.

Elkera is preparing XSLTs to transform BNML markup into HTML / XHTML. A CSS
will be included. These will be released as open source around the end of
November. I will make them available as soon as they are sufficiently

1. Schema architecture
We need to decide the high level issues about the TC's proposed schema. Some
key issues are set out in the following points.

1.1 Is it a development platform or smorgasbord?
1.1.1 Background
The issue is whether to create a basic, development platform or a
smorgasbord schema that tries to cover all possibilities.
The BNML Schema provides a basic model that can be easily adapted by
particular users to their needs while retaining the core content models. The
idea is to not overload the schema with things that a lot of users may not
need but to provide all the basics so that applications developed around the
schema can be easily adapted to deal with changes. This is also the approach
taken by DITA, although it uses a different specialization model to that in
Schema such as DocBook take the smorgasbord approach, but do allow

1.1.2 PM recommendation
It is impracticable, particularly at this time to develop a universal schema
that will fully satisfy all needs. There is no identified need for such a
schema. The primary function of this schema at this stage will be in back
end systems (precedent systems and automated publishing on web sites. There
is no need for widespread exchange of eContracts documents between
enterprises since there is no infrastructure for recipients to deal with it.
As the need arises, particular interest groups who want to exchange data can
define standards for the purpose.
I recommend that we keep it as simple as possible and define a base model
that can be easily extended by particular users, along the lines of the BNML
approach. I don't think it is necessary for us to use the DITA approach to
specialization for contracts.

1.2 Do we include document types other than "contract"?
1.2.1 Background
You will notice in the eBay user agreement, I have added the privacy policy
as a "document" that is attached in the adjunct element. This adds
considerable flexibility to the schema but may or may not be necessary for
particular users, depending on the approach they take.
In theory, if particular users want to add "document" or other document
types, they can easily do so by borrowing from BNML or developing their own.

1.2.2 PM recommendation
Adding the "document" document type or something similar makes the schema
very flexible and makes it easier for others to see how the schema can be
extended in other legal areas. The TC has an interest in the adoption of its
model by other legal and business users. Unless this occurs, the schema's
market penetration will be extremely limited.
On balance, I recommend that we include the "document" document type to
provide this flexibility.

1.3 Which schema syntaxes do we use and which is normative?
1.3.1 Background
We have a choice between Relax NG, XSD (XML Schema) or DTDs. We canvassed
the issues in 2003-2004. Due to the different capabilities of each, we may
need to select one syntax as the normative schema. This decision will likely
depend on the architecture of the schema. If we want to provide features
that are not supported by, say, DTDs, then we will need to use either Relax
NG or XSD schema and make it the normative version.
This does not prevent us from making the schema available in all 3 syntaxes
for the convenience of users. This is the approach taken in BNML, although a
full DTD has not been created at this time.
The BNML schema uses Relax NG compact syntax for several reasons:
* BNML re-defines the item element in the //block context. This cannot be
done in DTDs;
* Relax NG is extremely flexible and excellent for customization;
* There are tools to automatically generate XSD schema from Relax NG
* The Relax NG compact syntax is reasonably close to DTDs and is very human
readable. XSD schema are XML documents and very difficult to read without a
schema editing application.  

1.3.2 PM recommendation
I believe we must provide a schema because some applications do not support
DTDs (MS Word). 
The choice may depend on whether the TC retains the re-defined item in
//block in its schema. If it does, I recommend we use Relax NG compact
syntax as the normative schema syntax. Even without this, I believe it is
the most appropriate syntax.

1.4 Schema name and XML name space
1.4.1 Background
The TC does not have to use "BNML" and may not wish to do so. The TC can
decide on its own name space and schema name.

1.4.2 PM recommendation
Develop a new name for the eContracts schema.

1.5 Relationship between the schema and other schema that provide semantic
vocabularies, such as UBL.
1.5.1 Background
Rolly Chambers raised two issues:
(a) Can the BNML schema be used within these other schema?
(b) Can these other schema be included within BNML?

1.5.2 PM comment
I doubt very much that it will be useful to incorporate BNML into another
schema such as UBL, even if it can be done via name spaces. As I understand
it, UBL is not a document schema.
I see no reason why UBL or parts of it cannot be incorporated into BNML
contract. I am not familiar with UBL in any detail so I don't know all the
issues. It seems to make sense to use something like UBL if it provides a
ready made, useful vocabulary.
I believe we should leave it as an option for those who need it but not
burden anyone who does not.

1.6 File organisation of the BNML Schema
1.6.1 Background
Rolly has pointed out that the use of multiple files in the Relax NG version
of the schema makes it difficult to understand.
It is difficult initially to see how the schema works, although the file
structure is set out in some detail in the Readme file that accompanies the
schema documents.

The arrangement is part of the schema's design to make it easy for users to
modify the schema. The core elements that are essential to BNML are in one
file "bnml-core.rnc". Under Elkera's licensing model, these elements cannot
be changed if the schema is to be called "BNML". Of course, the TC can take
a different approach with its implementation.
The file "bnml-structure.rnc" includes major container elements such as body
and back that may be shared in several different document types. There is a
separate file for metadata and for xinclude to permit these to be optionally
used or omitted. There is a separate file for each document type (contract,
document etc) for document type specific elements. Finally, there is the
file is the file "bnml-s-eContracts.rnc" umbrella file that defines the
eContracts schema. This file is the only one that a user will normally need
to modify to extend the schema.
It is very common in DTD or schema architectures to do this to maximise the
flexibility of the schema. The BNML set up is much simpler than for other
major DTDs.

1.6.2 PM recommendation
I recommend that we retain this basic structure. If everything is in one
file, customisation is much more difficult to manage.
We can easily improve the explanation in the ReadMe file, if necessary.

Only schema developers ought to be quite capable of working it out. They are
the only ones who need to refer to the schema files. Ordinary users should
never have to work with schema files. They should be able to gain necessary
information from the separate schema documentation.

2. Detailed schema design and development
2.1 Review BNML element names

Do we want to change any of the element names for BNML elements adopted in
the schema?

2.2 Structures for contract front and parties markup

Do we need a more flexible or structured model for handling contract front
matter and parties?

2.3 Party signature markup

(a) Do we need the semantic party-signature markup?
(b) If so, is the model sufficiently flexible?

2.4 Inline lists

Do we need to markup in-line lists?

2.5 Re-use of item as a list item element (//block/item)

(a) Rolly Chambers suggested that re-use of the item element may be
confusing to some.
(b) Do we need to add a list container and separate list item to provide for
separate numbering control on multiple lists in a single paragraph or block?

2.6 Reference schedules at front of contracts

Do we need to allow adjunct to occur at the front of the document for
reference schedules?

2.7 Values for inclusion class attribute
Do we want to define specific values for the inclusion class attribute?

2.8 Automatic numbering control attributes

Do we want to define specific values for these attributes on item, inclusion
and adjunct?

2.9 Additional elements

Do we need any other elements? Rolly has suggested we may need phrase level
and keyword elements in addition to those already provided. Perhaps the
mention element could be renamed to phrase.

2.10 Choice of loose, standard or tight content models for elements using
//item and //block

Rolly has asked which model is the standard and whether we should use the
loose model at all.

The intention in BNML is that the loose model is the exchange standard but
that users would normally use the standard or tight models when creating
markup. The loose model is detrimental in contents creation and page
chunking on web sites. However, the loose model is useful to incorporate
quoted material in //inclusion. In this context it should be harmless.

2.11 ID & IDREF for linking
Rolly asked whether we should be using ID & IDREF.

The schema permits //reference to point to objects in other files, say where
a contract is to be assembled from shared /item elements. In that case, the
ID IDREF mechanism will not work unless the shared /item elements are fully
copied into the document.

2.12 Metadata

Do we need to provide for any additional metadata structures or just leave
this to individual users? BNML currently provides basic Dublin Core metadata
on //contract and //item.
We can add further DC elements or we can use another metadata model or just
leave it entirely up to each user.

2.13 Presentation markup

Do we need to remove elements and attributes considered to be presentation
information. These may include the em element and the align attributes on
block and text. Rolly also suggested that attributes to control the
application of automatic numbering may be in this category.

2.14 Variables markup
Rolly has pointed out that additional markup may be needed for variables. In
BNML, the autovalue element is intended to be for substitution variables. We
can consider precisely what functionality we want and whether the existing
markup is adequate. 

3. Schema and specification documentation
Once we have decided all the above issues, we can prepare the actual
specification. This will need to include a comprehensive explanation of all
elements and attributes defined by the schema.

Undoubtedly, there are other issues but this list should get us started.


Elkera Pty Limited (ACN 092 447 428)
Email: pmeyer@elkera.com
Ph: +61 2 8440 6900 * Fax: +61 2 8440 6988

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]