Subject: Comments on ietf-many-ical-xmldoc-00.txt

From: "Lisa Lippert (Dusseault) (Exchange)" <[email-masked]>
Date: Fri, 12 Mar 1999 18:42:38 -0800

I've read ietf-many-ical-xmldoc-00.txt carefully and it shows good progress.
I'm glad to see the use of namespaces to avoid collisions when different
vendors and 3rd parties inevitably extend calendar objects.  The DTD is
solid.

There are some minor and some medium flaws in the draft:

1.  The draft requires DTDs to represent attachments
This adds unecessary complexity:
 - Increases the size of the data object for a very common scenario
 - Doesn't help, it's unnecessary, the same information can be conveyed
within the XML body and it can still be validated.
 - Requires DTD parsers and generators on all clients (a problem for thin
clients)

See http://www.xml.com/xml/pub/98/07/binary/binary.html -- this is an
article on how to include binary data, such as pictures, in XML.

What the spec currently says:
	<!DOCTYPE iCalendar PUBLIC "-//IETF//DTD iCalendar RFC2445//EN"
http://www.ietf.org/internet-drafts/draft-many-ical-xmldoc-00.txt
	[
	<!ENTITY attach1 SYSTEM "http://host.com/pub/photos/holiday.jpg"
NDATA JPEG>
	<!NOTATION JPEG PUBLIC "ISO/IEC 10918:1993//NOTATION Digital
Compression and Coding of Continuous-tone Still Images (JPEG)//EN" >
	]>
	...
	<attach><extref uri="attach1" /></attach>

Instead, I propose an equivalent one-line solution, using:
  <attach fmttype="image/jpeg"
dt="uri">http://host.com/pub/photos/holiday.jpg</attach>

Similarly, dt="bin.base64" can be used to say that the contents of the
attachment tag are a base-64-encoded binary blob:
  <attach fmttype="application/octet-string"
dt="bin.base64">aslk9u28970934... </attach>

This is much easier to handle, because this does not require a DTD fragment
in any XML document that has an attachment.  It is also much closer to the
way iCalendar defines it, as far as I can tell.

In the XML standards committees, this method of doing data type markup is
pretty non-controversial.

2.  The draft requires internal DTDs (Document Type Definitions) to be
included with every object that has extensions
Similar to the above. The problems with this are: 
 - it adds hugely to the size of the data
 - it requires clients to have DTD parser and generator code, which they may
not have
 - it doesn't add information (it's not helpful to understand what the
extensions are for)
 - it doesn't allow a calendar object and another XML schema to be in the
same document
 - it doesn't allow namespaces to be defined for extended properties
 - since the DTD's for objects like vtodo are "closed", this would require
redefining "vtodo" just to add a custom property to it.  That's more
unnecessary work and bulk.

We can't require internal DTDs for every non-iCalendar property -- what if
the iCalendar XML data is used in the same document as some other standard
XML data?  How are namespaces for new properties defined in the internal
DTD?  Using a DTD for the standard is great, but it is overkill if used
internally in a document.  

I haven't seen any other specs that use internal DTD's as an extensibility
mechanism.  Most of the people in the XML community assume that
extensibility is done by defining a new DTD entirely outside the document.  

Counter-arguments:
a) internal DTDs are required in order to be able to validate the document
b) internal DTDs provide data-typing for custom properties

Counter-counter-arguments:
a) There are better ways to ensure that the document is validatable -- such
as using a namespace for custom properties that points to a site where the
schema/DTD is published. (Also, just because the document cannot be
validated doesn't mean it's not valid, well-formed, and even more important,
useful.  The point of XML was to relax some of the restrictions of SGML, to
make it more useful, not to be as strict in requiring validation.)  
b) Do we need data-typing on custom extensions?  How's that going to help --
can the client do anything with a custom property just by knowing the data
type?  If we do decide we need datatyping, it should not require an internal
DTD because of the problems above, and it should be done in a way that is
closer to what the XML community has already proposed for on-the-fly data
typing.  For that, I suggest an attribute on the property that contains the
data type.

3.  The draft requires the uses of namespaces in nonstandard ways
I like the use of namespaces, but the draft uses it in ways that seem
contradictory to the Namespaces Recommendation of the W3C.

There seems to be some confusion in the spec about what the "default
namespace" is for an XML document, and what the "qualified namespace" is.
They can be one and the same thing.  Also, we can't mandate the prefix "ics"
-- all we can mandate is the namespace identifier, which should be something
simple like "iCalendar" (define that as a URI), and the entity which creates
the XML can choose the prefix "ics" or "Q" or "foo".  

If we use a namespace identifier which is a valid URL, we can use
http://www.ietf.org/internet-drafts/draft-many-ical-xmldoc-00.txt, but I'd
rather not-- would this have to change with every revision??   It can be
something like "http://www.imc.org/xml-ical-schema" that doesn't change.  Or
to keep it simple, it can be simply "iCalendar:"  The qualified namespace
does not have to point to an existing page for it to be valid, but it can.

Note that we can't mandate that the namespace declaration must appear on the
iCalendar element -- it can be used earlier, e.g.
  <foo:mydocument xmlns:Q="iCalendar" xmlns:foo="http://foo.com">
    <Q:iCalendar version="2.0">
      ...etc...
    </Q:iCalendar>
  </foo:mydocument>

The two things a client can do with our namespace are:
 - Define it as the default namespace for the XML document, so that anywhere
an element appears without a prefix, it is understood to be in the default
namespace.
	e.g. 
	<iCalendar xmlns="iCalendar">
	  <iCal version="2.0">
	    <F:foo xmlns:F="foo"/>
	    <B:bar xmlns:B="bar"/>
	etc...

 - Define it as a namespace in the XML document, so that anywhere an
iCalendar element appears, it must have the prefix in order to be scoped.
Some other namespace might be the default (as "bar" in this example  Note
that both examples are equivalent, they just pick different default
namespaces).  
	e.g.
	<I:iCalendar xmlns:I="iCalendar">
	  <I:iCal version="2.0">
	     <F:foo xmlns:F="foo"/>
	      <bar xmlns="bar"/>
	  etc...

4.  It continues the use of X- property names
The problem with X- property names is that collisions may occur.

XML namespaces are intended to replace X- and other mechanisms that do not
prevent collisions.  Instead, I propose that new custom property names
should be used with proprietary namespaces.  So if I define a new
busy-status code to give more detail, I could do this in a way that is
guaranteed, by our ownership of the *.microsoft.com namespace in DNS, to be
unique to us:

  <i:fb xmlns:i="iCalendar">
    <i:start>19990219T0900</i:start>
    <i:end>19990219T1000</i:end>
    <m:busy-status
xmlns:m="http://schemas.microsoft.com/icalendar-extensions">Busy-OOF</busy-s
tatus>
  </i:fb>

This makes it very easy to add custom elements, which I'm sure there will be
a lot of.  Defining a proprietary namespace identifier is as easy as writing
it down.  Existing custom elements (ones in existing iCal documents) can be
included in our "iCalendar" namespace.

5.  the <br> element in "description" is illegal within XML PCDATA
There's no way to define the <br> element within PCDATA.  The XML would be
illegal.  Instead, I propose we define description and comment as CDATA,
which can legally contain HTML within some escape codes.

Other comments

- The mapping of property parameters to attributes is good:  in the last
iCal-in-XML draft published by Reddy and myself, we mapped more of the iCal
property parameters to elements rather than attributes.  We chose this
because elements can be dynamically data typed and attributes cannot.
However, this draft does have the benefit of being closer to iCal so that's
cool.

- Defining a new MIME type:  I'm not sure this is the best way to do this
long-term (will every XML document type need its own MIME-type?  What about
mixed XML schemas in the same document?)  but I'm still mulling it over.
It's a known issue in the W3C, and we can encourage them to deal with the
issue in a timely fashion.  For now let's go ahead with this section
untouched and just mark it as an open issue.

- Defining a file type:  I've been told this is a no-no in the IETF, but
that's just hearsay...  

Lisa

---

From: "Frank Dawson" <[email-masked]>
Date: Tue, 16 Mar 1999 16:21:20 -0500

>vendors and 3rd parties inevitably extend calendar objects.  The DTD is

Thank you for your support of this document. The strength of the DTD is
further acknowledged by the fact that others have already selected it for
use in XML applications. Apparently, the IBM Websphere product includes the
DTD in it's library of DTDs. This group has also assisted our work efforts
by passing it through their QE repertoire of parsers to ensure flexibility
in the DTD design for its practical use by both lightweight, as well as
robust XML applications. We would like to thank Thomas Rowe's team for this
volunteer effort. In addition, the Swedish Calendar Initiative (SKI) is
making use of the DTD. Gregory FitzPatrick's team has found this DTD design
to be very useful too. These early endorsements have provided great feedback
on many of the design principles used in the DTD.

>There are some minor and some medium flaws in the draft:

Based on the above endorsements of the draft and other feedback we have
received, your characterization of the DTD as having "design flaws" maybe a
bit subjective and reflect your personal view. In fact, the design choices
made by the three authors of the draft reflect the strong common goals that
many "markup designers" have made while designing structured text
applications; and that we in particular have made for the iCalendar XML DTD
document. Let me explain.

Our primary goal was to produce an optional, but isomeric, XML
representation for iCalendar's "standard format" defined by RFC 2445. As
such, we agreed with Paul Hoffman's request that the DTD work neither add
nor subtract from the form and function laid out in RFC 2445. This DTD will
be useful as either an information RFC or experimental RFC for near-term
experimentation with XML representation of iCalendar.

Our second goal was to design a DTD that would ensure that applications of
this DTD would interoperate with other iCalendar implementations. We had a
mandate from customers and vendors in the current calendaring and scheduling
market to provide a DTD design that assures that applications making use of
this optional XML representation for iCalendar can interoperate with
iCalendar implementations using the "standard format" defined by RFC 2445.
Hence, we purposefully restricted use of some XML features in the design of
the DTD in order to discourage vendors from creating applications that might
only interoperate with themselves. For example, rather than defining
external entity content as simple PCDATA, we force documents to declare all
external entities in an element attribute of type ENTITY that must be
further declared in a ENTITY and NOTATION declaration in an internal DTD.
Another example, is that we require all extensions to be made to the DTD
through declaration in an internal DTD, rather than allowing inclusion of
elements and attributes from other namespaces. See more comments on these
two points below.

Our third goal was to xxxx...
Third, where it comes to external references, such as support for the
standard iCalendar ATTACH property, we felt that it was imperative that a
transferred document use the most explicit mechanism allowed in XML to
specify where this external entity resided and what tools were needed to
process it. Mapping external entities through an ENTITY typed element
attribute is also a long accepted practice in DTD design.

> - Requires DTD parsers and generators on all clients (a problem for thin

Actually, the DTD specifies that ATTACH property values can EITHER be BASE64
encoded and placed inline in the document or the ATTACH property value can
be an external entity, whose location is specified using the standard XML
approach of an external entity reference. An external entity reference is
specified in an attribute of the ATTACH element, which is explicitly
identified by a URI and format type in an ENTITY and NOTATION declaration in
the internal DTD.

This is specified by exactly two lines in an internal DTD. This is a trivial
amount of XML text. After all XML is hardly a terse representation syntax
;-)

Your approach is problematic. Simply specifying external entities in an
element with a PCDATA content model exposes all of us (vendors and users) to
possible misuse. The large benefit of strong typing of external entities,
afforded by the approach in the current DTD, out-weighed the minimal extra
two lines needed to represent the ENTITY and NOTATION declarations.

Currently, we are assuming that iCalendar XML documents are parsed by XML
parsers, but this is no more a requirement on implementations than with your
design approach.

Your use of the name "dt=" for element attributes is a potential name
collision with future W3C data declaration work. We prefer use of an element
attribute name that is similar to that already in use in the "standard
format" iCalendar and that will minimize this conflict (i.e., "value=").

>dt="bin.base64">aslk9u28970934... </attach>

This suggestion runs against our goal of a strong 1:1 mapping with the
iCalendar "standard format". The iCalendar standard already defines a set of
strong data types for properties. We have a "value=BINARY" data type to
indicate that the value is Base64 encoded text. The current iCalendar XML
document incorporates this fidelity with RFC 2445.

> - it adds hugely to the size of the data

We addressed this above. Two lines is hardly "huge", given the verbosity of
XML to begin with.

> - it requires clients to have DTD parser and generator code, which they
may

Hhmm. I don't think either approach necessitates an implementation to have a
parser. I would CERTAINLY hope that we are leveraging the benefits of XML
(ubiquitous parsers, DOM processing, etc.) rather than just creating
yet-another-iCalendar-encoding in the syntax-dejour.

> - it doesn't add information (it's not helpful to understand what the

We think you may be mistaken on this point. Requiring extension to be
defined as extensions to the DTD will allow a recipient of the XML document
to understand where the extended element can be used in the structure of an
iCalendar document. Allowing inclusion of elements from other namespaces, in
order to define extensions, works against our goal of providing
interoperablity. There is no existing namespace registration authority, the
same extension could be identified by different namespace declarations, the
namespace reference might not resolve into something useful for
understanding were the extension is allowed.

> - it doesn't allow a calendar object and another XML schema to be in the

Half true. Let's be clear here, this is the definition of an iCalendar XML
document...not a foo document. Certainly you can go off and create a "foo"
XML DTD that permits the inclusion of elements from the "iCalendar"
namespace. However, we DO NOT want to allow an iCalendar XML document to
have anything but iCalendar semantics.

> - it doesn't allow namespaces to be defined for extended properties

As we mentioned above, this is not considered to be the "interoperable" way
to specify iCalendar extensions.

>unnecessary work and bulk.

This is not true. There are even examples in the iCalendar XML document for
adding an extension property to a calendar component, such as VTODO. The
method for specifying the extension is neither "bulky" nor unnecessary.

>extensibility is done by defining a new DTD entirely outside the document.

Would be happy to point you to references of other DTDs that add
functionality in a document instance via the internal DTD. This is very much
accepted practice in the document markup community.

>The point of XML was to relax some of the restrictions of SGML, to
>make it more useful, not to be as strict in requiring validation.

The strength of using XML over the current "standard format" defined by RFC
2445 is weakened by not leveraging the strong structure capabilities of the
XML DTD.

>the XML can choose the prefix "ics" or "Q" or "foo".

Yep. Thanks. We will fix this.

>something like "http://www.imc.org/xml-ical-schema" that doesn't change.

Yep, an RFC document reference would be more stable. We are temporarily
tracking the draft of the iCalendar XML document, but will change it to the
eventual RFC document, when published as an RFC ;-)

>should be used with proprietary namespaces.

Remember we have a goal of mapping 1:1 between the "standard format" of RFC
2445 and the XML representation. If you don't force experimental extensions
to be named with the same "X-" naming, you won't be able to map back to
"standard format". We have thought about this for some time and this appears
to be a good method to assure interoperability. Proprietary names spaces are
problematic for mapping back into the "standard format".

>which can legally contain HTML within some escape codes.

Hhmm. Will check this out. But, I believe we had an example that was thrown
through test parsers that had a DESCRIPTION element value with this and it
didn't flag it. But will check again. Typing the DESCRIPTION and similarly
valued elements as CDATA is an interesting idea. Will review this further.

>However, this draft does have the benefit of being closer to iCal so that's

We agree it is better the way currently specified. Thanks.

>long-term (will every XML document type need its own MIME-type?

Actually, using the existing "text/xml" or "application/xml" is problematic
with a 1:1 mapping to the "standard format" and also for possible use of
this DTD in iTIP. We need to have control over the content-type to assure
that we have the proper content-type attributes.

>- Defining a file type:  I've been told this is a no-no in the IETF, but

We have heard this too ;-) However, you should be aware that the iCalendar
specification does define file types for iCalendar.

- - Frank