RE: Comments on the Common Schema Structures note

> I'd like to forward to the group the following feedback on the
> common schema structure note I received from our JAXB team.

thanks, Roberto, and to 'JAXB' for the detailed review.

Overall, I think a lot of the comments come from the perspective of
one of the most dominant binding tools. I'd characterise they adopt
the position that there are a number of binding implementations in
existence, and that the note should document what works well between
them?

If so, then I think that's a dangerous approach as one of the
motivations behind this note is the lack of interoperability across
databinding tools.

If we include the 16+ implementations BT tested its infrastructure
services with, the lowest common denominator is limited to
not much beyond <complexType/sequence> and <element type="xs:string">.

Therefore the note is intended to inspire some implementations
to improve their act to the 'state of the art', raising the
interoperability floor, all be it very slightly.

> Overall, the general direction is quite XML Schema centric.

The note could focus on XML structures with how they
may be described in Schema, Relax, etc as an appendix, however
this is the W3C WSDL WG and XML Schema is in our Charter
and the current basis for interoperability with most tools, so
I'm personally more comfortable with the current approach, but
am open to other suggestions ..

> When there is impedence mismatch between binding XML Schema to a
> programming language,  the proposed solution/directions ignore the
> mismatch. It would be preferable to provide a recommendation on
> how to work around the issue in the short term.

As discussed with Mark Hapner, there is less risk of becoming
programming language specific if we think in terms of Schema
'patterns' which may map onto data structures, rather than
how to efficiently serialise structures from one or two domains:

http://lists.w3.org/Archives/Public/www-ws/2005Aug/0000.html

[snip]

> It is ironic that this note has a goal for an improved user
> experience when using data mapping/binding tools and does not issue
> a recommendation to not name schema types with names that are commonly
> reserved words in programming languages.  Minimally, a *recommendation*
> advising against the use of reserve words that occur across  multiple
> target programming languages would be helpful if the schema has a
> desire to be data binding/mapping friendly.  Otherwise, additional
> effort is needed to resolve this issue.

I did think about this approach, but it's our experience that there is
always yet another reserved word as the list of 'target programming
languages' increase. The word 'object' maps fine to C but not into C#
and whilst a symbol 'CUSTOMER-PROFILE-TYPE' works well in COBOL, it's
likely to be taken as an expression in many C based languages. So I
think it's much better to warn implementers of tools that they should
expect any valid XML _name_ to be used for elements, types and 
attributes and for them to map and escape problematic symbols in a 
way appropriate to their specific environment.

However I've added a sentence: "Conversely, publishers of schemas may
reduce the mapping required by avoiding element, attribute and type
names likely to clash with reserved words in many programming languages."

> Other naming issues include elements and type definitions being able
> to have same name due to 6 distinct symbol scopes in XML Schema.
> Workaround would be for schema designer to not use same names for
> elements and type definitions. From JAXB 1.0 to JAXB 2.0, this issue
> has been reduced significantly since only elements with anonymous
> complex type definitions are mapped to a class by default.

thx, I've added a sentence: "Authors of tools which map or bind data
structures to XML should be aware that the same name may be used in a
number of different places within a single schema, as a global element
name and as the name of a complexType, for example"

I'm wonder if there is a good reference guide to the "6 distinct
symbol scopes", or if it is worth referencing the SCD document:
http://www.w3.org/TR/xmlschema-ref/

>  From Section  2.2.1 Extensible Enumerated Type.
>
> An enumeration may made open to extension, possible in a later
> version of the schema, by creating a union with its base type.
>
> <xs:simpleType name='KnownCurrency'>
>    <xs:restriction base='xs:string'>
>      <xs:enumeration value='GBP'/>
>      <xs:enumeration value='USD'/>
>      <xs:enumeration value='CAD'/>
>    </xs:restriction>
> </xs:simpleType>
>
> <xs:simpleType name='Currency'>
>    <xs:union memberTypes='tns:Currency xs:string'/>
> </xs:simpleType>
>
> Comments:
> I believe there is a typo above. The memberTypes "tns:Currency"
> should be "tns:KnownCurrency".

thx, fixed.

> Extensible enumerated types recommendation does not bind/map well to
> enumerated types defined in existing programming languages. An enum
> type is typically a closed, finite set of values that can be 
> efficiently
> processed by switch/case statement. Future versions of the enum type 
> can
> add new enum constants, but this is not typically achieved via the use
> of unions in programming languages.

I agree that this isn't currently well supported by many tools, however
this is a case in hand where I'm communicating to binding tool authors
that this is a very common and useful schema pattern worth supporting ,
in particular for versioning and extensibility. I've added a note to draw
attention to this issue.


> 2.3 Collection
>
> The individual items held in a collection may appear either as XML
> element or attribute values.
>
> Comment: Section describes characteristics of various kinds of model
> group of elements. Missing statement that attributes are unordered.

I've added some text to that effect ..

> Also missing statement that collection is best mapped to all attributes
> or all elements. I don't  imagine that a collection should be split
> across element and attribute values in a single complex type 
> definition.

Some tools, such as .NET, make it easy to identify each individual 
property as an element or an attribute, a feature I've used often 
as attributes offer improved support for extensibility and random
order, however it's still necessary to use an element to represent 
more complex data types.

> 2.4 Vectors
>
> Missing  xs:list of a simple type definition.
>
> Example:
>
> <xs:simpleType name="xs:USStateList">
>      <xs:list itemType="xs:string"/>
> </xs:simpleType>
>

i've added that pattern - thx!

> 2.5  Maps
>
> For a tool to be able to recognise that a repeated item a map, it
> needs to be able to identify which of the repeated elements or
> attributes represents the unique key.
>
> Comment:
> Incomplete sentence above.  Believe something like the following was
> intended.
>
> For a tool to be able to recognize that a repeated item /can be
> bound to/ a map,  the tool needs to be able to identify which
> / child element or attribute of the repeated item/ represents the
> unique key.

fixed :")

> Another obvious mapping to map would be using the element names as
> the key of a map over xs:all model group.

i added a sentence at the start of the map section "Maps differ from
Vectors in that their contents are unordered. Therefore the sequence
and all model groups may be used interchangeably following patterns
and examples."

Paul

updated version in CVS:
file:///Users/pauldowney/Documents/w3c/2002/ws/desc/schema-patterns/
xml-schema-patterns.html

Received on Friday, 12 August 2005 16:41:51 UTC