Subject: [Simple] Double specification: text and schema

From: Miguel Garcia <[email-masked]>
Date: Thu, 01 Jul 2004 14:10:29 +0300

Hi:

I want to point out an issue I have found when reviewing a few I-Ds that 
define XML schemas.

The problem is that many documents do double normative specification: on 
  one side, they introduce normative text when they describe the various 
elements that are part of the XML schema; on the other side, the XML 
schema is normative by itself.

An example:

draft-ietf-simple-filter-format-01.txt says in section 3.2

    The <filter> MUST have an 'id' attribute.  The value of the 'id'
    attribute MUST be unique within the <filter-set> element.  The
    <filter> MAY have an 'uri' attribute.  The value of the 'uri'
    attribute is the URI of the resource which the filter applies to.
    The <filter> MAY have an 'domain' attribute.  The value of the
    'domain' attribute is the domain of the resources that the filter
    applies to.  The "uri" attribute and the "domain" attribute MUST NOT
    appear together in a filter.

Then, the XML schema indicates that <filter> MUST have a required 'id' 
attribute:

        <xs:attribute name="id"  type="xs:string" use="required"/>

The schema also says that <filter> MAY have a 'uri' attribute (optional):

        <xs:attribute name="uri" type="xs:anyURI" use="optional"/>

And so on.

The problem: We have two normative statements (one in the text, another 
in the XML schema) indicating the same thing. This is not a big problem 
as long as both statements indicate the same thing. But what happens if 
the document evolves, and then we it is decided to make mandatory some 
attribute that previously was optional, and what happen if the change is 
reflected only in the textual form and not in the schema; or vice versa. 
Then we run into trouble.

Therefore, I would like to propose that, in the sake of interoperability 
of implementations, documents indicating XML schemas MUST specify the 
normative part as much as possible in the XML schema definition. Only 
those bits that cannot be specified in the schema MUST be specified in 
the text.

According to this suggestion, the above paragraph would be re-written as:

    The <filter> has an 'id' attribute.  The value of the 'id'
    attribute MUST be unique within the <filter-set> element.  The
    <filter> has an 'uri' attribute.  The value of the 'uri'
    attribute is the URI of the resource which the filter applies to.
    The <filter> has an 'domain' attribute.  The value of the
    'domain' attribute is the domain of the resources that the filter
    applies to.  The 'uri' attribute and the 'domain' attribute MUST NOT
    appear together in a filter.

Note that the text above still indicates a couple of normative sentences 
that cannot be expressed (to my knowledge) in the schema.

Comments? Can we agree this way of working from now on?

- Miguel

-- 
Miguel A. Garcia           tel:+358-50-4804586
Nokia Research Center      Helsinki, Finland

_______________________________________________
Simple mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/simple

---

From: "Joel M. Halpern" <[email-masked]>
Date: Thu, 01 Jul 2004 11:09:40 -0400

I would agree that this can be a problem.
I would like to phrase the solution differently.  (I am not sure whether I 
am disagreeing with Miguel's proposal or not.)

While I like reading the schema, I really want the text to be clear and 
sufficiently precise.  Hence, I would prefer not to weaken the use of MUST, 
etc. in the text.

Rather, I would suggest that we simply state in a paragraph in the 
introduction, after the citation for the terms MUST, SHOULD, ... that in 
the case of conflict between the text and the  XML schema, any requirements 
or prohibitions defined in the schema take precedence over conflicting text.

Yours,
Joel M. Halpern

At 02:10 PM 7/1/2004 +0300, Miguel Garcia wrote:
>The problem: We have two normative statements (one in the text, another in 
>the XML schema) indicating the same thing. This is not a big problem as 
>long as both statements indicate the same thing. But what happens if the 
>document evolves, and then we it is decided to make mandatory some 
>those bits that cannot be specified in the schema MUST be specified in the 
>text.

---

From: Miguel Garcia <[email-masked]>
Date: Fri, 02 Jul 2004 10:20:08 +0300

Hi Joel:

I don't agree with you. We can't avoid the XML schema. I believe you 
agree with me.

Since the XML schema already needs to indicate whether an element or 
attribute is mandatory or not, there is no point in repeating the same 
information in the text. What for?

If you are implementing the draft, you need to implement the XML schema. 
If you just look at the text, then we will have interoperability problems.

If you are just a curious reader, then you most likely don't look at the 
XML schema, but you don't care whether an element MUST be present or MAY 
be present (and if you care, look at the XML schema). You most likely 
care about the existence of an element.

Therefore, I don't support having a disclaimer like: "we try to have 
100% quality in this document, but if we didn't achieve 100% quality, 
the XML shema takes precedence".

- Miguel

Joel M. Halpern wrote:

> I would like to phrase the solution differently.  (I am not sure whether 
> I am disagreeing with Miguel's proposal or not.)
> 
> sufficiently precise.  Hence, I would prefer not to weaken the use of 
> MUST, etc. in the text.
> 
> the case of conflict between the text and the  XML schema, any 
> requirements or prohibitions defined in the schema take precedence over 
> conflicting text.
> 
> Yours,
> Joel M. Halpern
> 
>> The problem: We have two normative statements (one in the text, 
>> another in the XML schema) indicating the same thing. This is not a 
>> big problem as long as both statements indicate the same thing. But 
>> what happens if the document evolves, and then we it is decided to 
>> make mandatory some attribute that previously was optional, and what 
>> happen if the change is reflected only in the textual form and not in 
>> the schema; or vice versa. Then we run into trouble.
>>
>> Therefore, I would like to propose that, in the sake of 
>> interoperability of implementations, documents indicating XML schemas 
>> MUST specify the normative part as much as possible in the XML schema 
>> definition. Only those bits that cannot be specified in the schema 
>> MUST be specified in the text.
> 
>

---

From: Jonathan Rosenberg <[email-masked]>
Date: Fri, 02 Jul 2004 06:23:04 -0400

> information in the text. What for?

I think that it can be useful for purposes of clarification. I would 
advise using non-normative terminology in the text. So, for example:

"The <foo> element includes a single mandatory attribute, "bar", and 
always has two children, <sip> and <ping>..."

I think it also makes sense to have an explicit statement about the 
normative nature of the schema, and that any explanatory text is not 
normative. I routinely put such statements in "overview of operations" 
sections, which are not written with RFC2119-strentgh terms.

-Jonathan R.

-- 
Jonathan D. Rosenberg, Ph.D.                600 Lanidex Plaza
Chief Technology Officer                    Parsippany, NJ 07054-2711
dynamicsoft
[email-masked]                     FAX:   (973) 952-5050
http://www.jdrosen.net                      PHONE: (973) 952-5000
http://www.dynamicsoft.com

---

From: Miguel Garcia <[email-masked]>
Date: Fri, 02 Jul 2004 13:44:20 +0300

> sections, which are not written with RFC2119-strentgh terms.

As long as we don't use normative statements in the text, it is fine to 
me. I would go one step further to avoid the words "mandatory" and 
"optional" in the text, but I would accept Jonathan's proposal.

I also like the idea to stress that the XML schema is normative (in case 
someone didn't realize yet).

- Miguel

---

From: "Joel M. Halpern" <[email-masked]>
Date: Fri, 02 Jul 2004 08:55:05 -0400

From my view of history and pragmatics:
1) This is not a new problem.  Many standards bodies have had this problem 
for a long time.  The consistent answer has not been that whatever is 
formally specified should not be described in normative language in text.
2) For human being reading the text it is very helpful to comprehension if 
the text says exactly what is required and permitted.  Sure, when it comes 
to final implementation the formal specification is the absolute rule.  But 
human beings can find it hard to understand exactly what is meant by the 
formal spec.
3) If one leaves out the requirements for uniqueness, number of 
occurrences, and other properties from the english text, then one has an 
english portion that is likely misleading and frequently wrong.

The practice of recognizing duplicative specification, and indicating which 
portion over-rides is long established and works.  Why would we suddenly do 
something different.
As far as I can tell, even the W3C follows this rule, with english text 
explaining the meaning, cardinalities, uniqueness, and other requirements 
for documents which are also specified by XML Schema.

Yours,
Joel M. Halpern

At 10:20 AM 7/2/2004 +0300, Miguel Garcia wrote:
>Hi Joel:
>
>I don't agree with you. We can't avoid the XML schema. I believe you agree 
>with me.
>
>be present (and if you care, look at the XML schema). You most likely care 
>about the existence of an element.
>
>Therefore, I don't support having a disclaimer like: "we try to have 100% 
>quality in this document, but if we didn't achieve 100% quality, the XML 
>shema takes precedence".
>
>- Miguel
>
>Joel M. Halpern wrote:
>

---

From: "Joel M. Halpern" <[email-masked]>
Date: Fri, 02 Jul 2004 09:00:00 -0400

Part of what I am trying to avoid is telling authors that they must be 
extra careful never to use MUST words about things described in the 
schema.  In a typical text description there will be explanatory text, 
there will be explanation of requirements that are also in the schema, and 
there will be explanation of requirements that are not in the 
schema.  (Occasionally one gets lucky and the last category is empty.)
As an author, I really don't want to have to try to change style from 
sentence to sentence in a section depending upon whether or not the 
particular behavior I am describing also occurs in the schema.
Also, as I reader I would like to see a complete description in the text.

Yours,
Joel M. Halpern

---

From: Miguel Garcia <[email-masked]>
Date: Fri, 02 Jul 2004 16:16:11 +0300

Well, here is the disagreement. I just want to tell authors: "don't use 
normative text when there is normative definition expressed in the schema".

Believe me, and record my words for a future time: if we start doing 
double specification of normative requirements in RFCs, we will face 
interoperability problems.

If you are not able to put a bit of effort when writing your documents, 
we all will pay in the future.

- Miguel

Joel M. Halpern wrote:

> there will be explanation of requirements that are also in the schema, 
> and there will be explanation of requirements that are not in the 
>>> attribute is mandatory or not, there is no point in repeating the 
>>> same information in the text. What for?
>>
>>