Subject: [Geopriv] Miscellaneous XML Tips

From: "Thomson, Martin" <[email-masked]>
Date: Wed, 3 May 2006 23:47:15 -0500

Hi All,

I thought that I would share a few thoughts I had on how we use XML in specifications.  I'm still learning...

-- Extensibility

I have been thinking about the XML and extensibility problems we have had recently and while this is way too late for common-policy, maybe this can be used for future work.

The primary method used in GML for extension is substitution groups.  This is a feature of XML Schema that has been used to great effect in the GML specification and I believe that we may have been able to benefit from it for common policy.  This might have helped even more with PIDF and its many extensions.

The basic idea is to avoid using the <xs:any...> construct and instead use an element that acts as the abstract head of a substitution group.  So instead of defining the actions/transformations sections like so:

 <!-- //rule/actions or //rule/transformations -->
 <xs:complexType name="extensibleType">
   <xs:complexContent>
     <xs:restriction base="xs:anyType">
       <xs:sequence>
         <xs:any namespace="##other" processContents="lax"
                 minOccurs="0" maxOccurs="unbounded"/>
         </xs:sequence>
      </xs:restriction>
   </xs:complexContent>
 </xs:complexType>

You would instead define the contents of each to be a very definite type:

  <xs:complexType name="actionsType">
    <xs:sequence>
      <xs:element ref="_action" minOccurs="0" maxOccurs="unbounded"/>
    </xs:sequence>
  </xs:complexType>

And the new type is defined quite simply:

  <xs:element name="_action" type="xs:anyType" abstract="true"/>

This forces people who want to use this extension to define their elements as members of this substitution group (for presence rules for instance):

  <xs:element name="sub-handling" type="pr:sub-handlingType"
              substitutionGroup="cp:_action"/>

These sorts of restrictions are largely invisible to the user of the specification, but now there is a little more certainty - each extension parameter is now clearly labeled with where it may be used.  That might prevent misuse - there is a higher barrier to people using element where they weren't originally intended to be used.

It also means that you can, from the base specification, impose some constraints on the content that others provide by judicious use of the final attribute on the _action element, or the type that is applied to it.  If you don't care what the element looks like as long as it has a certain attribute, add that attribute to the abstract base type.

I'm not suggesting that we change anything, but maybe this might be useful for future work.

-- xsi:schemaLocation and validation tips

As Jari has pointed out a few times, we also need to be careful with xsi:schemaLocation declarations in our examples.  Those declarations are useful for validation and development, but they should not appear in the final specification.  I actually put all my examples in a single XML box that has all the schemaLocation declarations.  Then each example is put inside that box, just like for my geo-shape examples:

  <box xmlns="box"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="box box.xsd
    urn:ietf:params:xml:ns:geopriv:held held.xsd
    urn:ietf:params:xml:ns:pidf:geopriv10:geoShape gs.xsd
    http://www.opengis.net/gml geometryPrimitives.xsd">
    
    <!-- examples here -->

  </box>

The box schema is simple:

  <xs:schema targetNamespace="box"   
     xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xs:element name="box">
      <xs:complexType>
        <xs:sequence>
          <xs:any namespace="##other" processContents="strict"
            minOccurs="0" maxOccurs="unbounded"/>
        </xs:sequence>
      </xs:complexType>
    </xs:element>
  </xs:schema>

Then you only have to validate the one file as well:
  http://validate.openlaboratory.net/
  http://www.w3.org/2001/03/webdata/xsv

Be aware that there might be bugs in the validator, so check with as many sources as you can.

Cheers,
Martin 

------------------------------------------------------------------------------------------------
This message is for the designated recipient only and may
contain privileged, proprietary, or otherwise private information.  
If you have received it in error, please notify the sender
immediately and delete the original.  Any unauthorized use of
this email is prohibited.
------------------------------------------------------------------------------------------------
[mf2]

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

---

From: Jari Urpalainen <[email-masked]>
Date: Fri, 05 May 2006 09:50:10 +0300

On Wed, 2006-05-03 at 23:47 -0500, ext Thomson, Martin wrote:
> substitution groups

The primary reason for not using substitution groups and just to stick
with <xs:any> is because you can't write forwards and backwards
compatible schemas without those wildcards. For presence it is imo
reasonable, but not necessarily always. With common policy the rules
could have been stricter, imo. Substitution groups give nice, exact
extension points to w3c schemas, but actually Relax NG outperforms w3c
schemas here, as with it you can easily redefine the rules (and even
without the dreaded UPA constraint).
br,
Jari

---

From: Hannes Tschofenig <[email-masked]>
Date: Fri, 05 May 2006 09:12:39 +0200

Hi Martin,
Hi Jari,

As a follow-up,

In the past we used substitution groups within Common Policy but then we 
replaced it with the <xs:any...> construct to align it with the rest of 
the SIP/SIPPING/SIMPLE work. This was done as part of an investigation 
in an XML schema design team. The usage of Relax NG was also mentioned 
to overcome some of the extensibility issues. However, it would have had 
impact on already published specifications. Hence, we decided to go for 
the <xs:any...> construct particularly since we don't care too much 
about validation anyway.

Ciao
Hannes

Jari Urpalainen wrote:
>> I have been thinking about the XML and extensibility problems we
>> have had recently and while this is way too late for common-policy,
>> maybe this can be used for future work.
>> 
>> The primary method used in GML for extension is substitution
>> groups.  This is a feature of XML Schema that has been used to
>> great effect in the GML specification and I believe that we may
>> have been able to benefit from it for common policy.  This might
>> have helped even more with PIDF and its many extensions.
>> 
>> The basic idea is to avoid using the <xs:any...> construct and
>> instead use an element that acts as the abstract head of a
>> substitution group.  So instead of defining the
>> actions/transformations sections like so:
>> 
>> <!-- //rule/actions or //rule/transformations --> <xs:complexType
>> name="extensibleType"> <xs:complexContent> <xs:restriction
>> base="xs:anyType"> <xs:sequence> <xs:any namespace="##other"
>> processContents="lax" minOccurs="0" maxOccurs="unbounded"/> 
>> </xs:sequence> </xs:restriction> </xs:complexContent> 
>> </xs:complexType>
>> 
>> <xs:complexType name="actionsType"> <xs:sequence> <xs:element
>> ref="_action" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> 
>> </xs:complexType>
>> 
>> This forces people who want to use this extension to define their
>> elements as members of this substitution group (for presence rules
>> for instance):
>> 
>> substitutionGroup="cp:_action"/> substitution groups These sorts of
>> restrictions are largely invisible to the user of the
>> specification, but now there is a little more certainty - each
>> extension parameter is now clearly labeled with where it may be
>> used.  That might prevent misuse - there is a higher barrier to
>> people using element where they weren't originally intended to be
>> used.
>> 
>> It also means that you can, from the base specification, impose
>> some constraints on the content that others provide by judicious
>> use of the final attribute on the _action element, or the type that
>> is applied to it.  If you don't care what the element looks like as
>> long as it has a certain attribute, add that attribute to the
>> abstract base type.
>> 
> The primary reason for not using substitution groups and just to
> stick with <xs:any> is because you can't write forwards and backwards
> extension points to w3c schemas, but actually Relax NG outperforms
> w3c schemas here, as with it you can easily redefine the rules (and
> even without the dreaded UPA constraint). br, Jari
> 
> _______________________________________________ Geopriv mailing list 
> [email-masked] https://www1.ietf.org/mailman/listinfo/geopriv
> 
>

---

From: "Rohan Mahy" <[email-masked]>
Date: Mon, 8 May 2006 13:36:15 -0700

Hi Folks,

I'd like to echo Jari's comment that Relax NG is far better for
describing extensible schemas.  The W3C are using Relax NG for most of
their new schema work for this reason.  At some point, we should
consider ditching our XML Schema definitions so we can write clear,
extensible schemas that are readable by mere mortals.

thanks,
-rohan

---

From: Cullen Jennings <[email-masked]>
Date: Tue, 9 May 2006 09:50:34 -0700

You guys should go raise this on the xml directorate mailing list. If  
they proclaimed that Relax NG was "allowed", I imagine lots of people  
would start using it.

---

From: Andrew Newton <[email-masked]>
Date: Tue, 09 May 2006 13:39:14 -0400

> they proclaimed that Relax NG was "allowed", I imagine lots of people 

I'm on the XML Directorate.  The XML Directorate has never made any 
statements about Relax NG not being allowed.  In fact, the XML 
Directorate cannot even mandate against such a thing.

See the following message on the XML Directorate list regarding this issue:
http://www1.ietf.org/mail-archive/web/xml-dir/current/msg00110.html

I don't know how this idea got started, but Relax NG is not forbidden.

-andy

---

From: Cullen Jennings <[email-masked]>
Date: Tue, 9 May 2006 11:35:00 -0700

Well, I agree the xml directorate has never said anything was  
forbidden. But have they said anything was recommended, or even "not  
a bad idea". This may have changed but I remember asking along time  
ago and getting a pretty wishy washy answer on it all. I know they  
could not enforce things but the folks using XML would probably  
happily follow any advice or suggestions the XML directorate had.  
(Perhaps I am naive here but one could try :-)

On May 9, 2006, at 10:39 AM, Andrew Newton wrote:

> Cullen Jennings wrote:
>> You guys should go raise this on the xml directorate mailing list.  
>> If they proclaimed that Relax NG was "allowed", I imagine lots of  
>> people would start using it.
>

---

From: Hannes Tschofenig <[email-masked]>
Date: Wed, 10 May 2006 08:53:34 +0200

When we worked on the XML schema design team last year the problem with 
Relax NG in context of the Common Policy and related drafts was that we 
had to align our work with already published RFCs. There was no desire 
to change these documents only because of this issue (since it turns out 
to be a non-issue at the end). If there is a subject with less 
dependency then I suspect the situation will be a bit different.

Ciao
Hannes

Cullen Jennings wrote:
> forbidden. But have they said anything was recommended, or even "not  a 
> bad idea". This may have changed but I remember asking along time  ago 
> and getting a pretty wishy washy answer on it all. I know they  could 
> not enforce things but the folks using XML would probably  happily 
> follow any advice or suggestions the XML directorate had.  (Perhaps I am 
> naive here but one could try :-)
> 
>