xml-dev - Re: Community help on W3C XML Schemas

["Thomas B. Passin" <tpassin@home.com>]

Rick JELLIFFE called for reviews of the text of W3C XML
Schemas:

>
> I would like to renew my call for people to make concrete
suggestions on
> improving the text of W3C XML Schemas.
>
> I am particularly interested in knowing the points at
which people who
> get lost or stymied or frustrated.  Are there terms that
are not defined
> sufficiently?  What would be a better way to organize it?
Are there
> explanations which seem to increase the difficulty of
understanding
> rather than adding clarity?
>

I've started on this.  I agree with Rick that the current
draft is a big improvement on earlier ones.  I've attached
some remarks and suggestions - I haven't had time to get
very far, but hope that they will be useful anyway.

Regards,

Tom Passin
Review of Parts of XML Schema Part 1
Thomas B. Passin (tpassin@home.com)
30 October 2000

2.2.1 Type Definition Components

The abstract model provides two kinds of type definition component: simple and complex.

[Definition:]  This specification uses the phrase type definition in cases 
where no distinction need be made between simple and complex types.
Type definitions form a hierarchy with a single root. First we 
describe characteristics of that hierarchy, then provide an introduction 
to simple and complex type definitions themselves.

========== comment =============================
Need to say what a "type" is before getting into this.  Especially, 
the difference between a type and an element needs to be drawn
clearly - that can be especially confusing because many people think 
of an element as a type, so that an actual instance in a document 
is labeled by its type (the start end tags).
==================================================

2.1 Overview of XML Schema

...which may have been implicit in the original document

========== comment =============================
What original document???
==================================================

2.2.1 Type Definition Components

...Schema component is the generic term for the building blocks that comprise the 
abstract data model of the schema...

========== comment =============================
What should they be called when talking about their appearance in
come more concrete occurrance?
==================================================
2.2 XML Schema Abstract Data Model

...There are 12 kinds of component in all, falling into three groups. The 
primary components are as follows. They may have names...

========== comment =============================
They may have names in what context?  Does this mean the ***type*** of 
component has a descriptive name, does it mean that a component may
have a name when it is used in a schema - when its instance is to be 
referred to by that name, or does it mean that instances in a document 
have names that are used in the document?
==================================================

...The target namespace serves to identify the namespace within which 
the association between the component and its name exists....

========== comment =============================
This reads well but is not entirely clear.  Does it mean something like this?

"For the purposes of validating a schema component, when the component
appears in an instance document, its name must belong to the target namespace 
(as specified by an appropriate prefix or default NS declaration)."

If this is not the intended meaning, then the statement must be clarified.
If it does, then it still should be made more clear.
==================================================

2.2.1 Type Definition Components

...[Definition:]  A type definition whose declarations or facets are 
in a one-to-one relation with those of another specified type definition, 
with each in turn restricting the possibilities of the one it corresponds 
to, is said to be a restriction. The specific restrictions might include 
narrowed ranges or reduced alternatives. Members of a type, A, whose 
definition is a restriction of the definition of another type, B, are 
always members of type B as well....

========== comment =============================
This appears to say that type A can restrict type B while at the same
time, B can restrict A.  Is this correct?  And if so, is this
really desired???  Circular restrictions seem to be very 
dangerous.  This passage need clarification.
==================================================

[Definition:]  A distinguished ur-type definition is present in each XML Schema, 
serving as the root of the type definition hierarchy for that schema. 
The ur-type definition, whose name is anyType, has the unique characteristic 
that it can function as a complex or a simple type definition, according 
to context. 

========== comment =============================
Suggest that this should say

"The ur-type is an abstract type that has no restrictions applied.
Thus, it serves as the parent or root type for all derived types in a schema.
It, and it alone, can function as a complex or a simple type definition, 
according to context."
==================================================

2.2.1.2 Simple Type Definition
A simple type definition is a set of constraints on strings and information 
about the values they encode, applicable to the normalized value of an 
attribute information item or of an element information item with no 
element children. Informally, it applies to attribute values and text-only 
content of elements.

========== comment =============================
This would be clear except for the lack of definition, mentioned
earlier, about the exact role of elements vis-a-vis types.  Here, it
seems that the type definition restricts element content, but we still
don't quite know if an element is considered to be an instance of
a type.

What exactly an element or type is has importance for query languages, as
well as for understanding the schema recs themselves,
so it's not really splitting hairs to want to be very clear about it.

People will come to their own conclusions about this, unless it is made very clear.
==================================================

...Simple types may also be defined whose members are lists of items 
themselves constrained by some other simple type definition, or whose 
membership is the union of the memberships of some other simple type definitions.

========== comment =============================
It's fairly clear how the allowed members of a type could be the set of the 
union  of another type.  The passage about lists is harder to understand.
Are the members, which I take to be the allowed contents of elements or
attributes, themselves lists, or are they specified by a list of allowed
values, which list is defined elsewhere?  

Literally the text says that the members are lists, but I
am questioning whether that is what is intended.  Certainly the
passage needs clarification.
==================================================


2.2.1.3 Complex Type Definition

A complex type definition is a set of attribute declarations and a 
content type, applicable to the [attributes] and [children] of an 
element information item respectively.


========== comment =============================
The section on simple types began by referring to "normalized values" of
information items.  Here the term "normalized" has not been used.
If this is not intentional, it shuld be added here.  If it is
not intended, consider briefly addressing why it is not applicable here 
but was in the earlier section.
==================================================

...The content type may require the [children] to contain neither 
element nor character information items, to be a string which belongs 
to a particular simple type or to contain a sequence of element information 
items which conforms to a particular model group, with or without character 
information items as well.

========== comment =============================
This sentence does not fit in a normative section, because we cannot
tell whether this list is intended to be an exhaustive enumeration
or whether it is illustrative (and non-normative)only.  The point 
should be clarified.
==================================================

2.2.2 Declaration Components

...Element declarations contribute to validation as part of model 
group validation, when their defaults and type components are checked 
against an element information item with a matching name and namespace,
and by triggering identity-constraint definition validation.

========== comment =============================
This seems fairly understandable except for "as part of model 
group validation", and except for "by triggering identity-constraint 
definition validation".

Does the "model group" phrase mean that the same element information item
could be validated against different type definitions?  Does 
this refer to some notion of scope?  THe phrase either needs to be removed
or clarified.

The phrase about triggering identify-constaints also needs clarifying. 
It contains too many concepts that have not been defined up to this point.
==================================================