OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: New design pattern for DITA XML Schema (General Constraint (12008) and newTask type (12011))


Just a fair warning...this is a long note.  

XML Schema development has been silent for a while on the TC front.  There has been ongoing work internally to develop an new design pattern that should facilitate the implementation of DITA features 12008 [1] and 12011 [2].  I want to make sure that TC is aware of the design that are needed to implement the features and how it will affect the XML Schemas.   Admittedly, I was trying to avoid these two features as long as possible because it required the most amount of work on the XML Schema side of the house.  Mainly because these two features force us to make use of the XML Schema inheritance architecture (restriction/extension) because getting an XML Schema to validate properly can sometimes be quite frustrating.

The new changes will make it easier for specializers to develop valid constraints based on XML Schema validation rules [3].  Without these changes to the base schemas it is nearly impossible to implement feature 12011in DITA 1.2 using the available mechanisms in XML Schema 1.0.  I can't guarantee that specializers will escape unscathed .  I can say that the likelihood of getting valid constraints has increased with the new design pattern.  The long term good news is that  XML Schema 1.1 will be introducing an element <xs:override> to help address the issue.

I know it may seem complicated and it overwhelming.  I will continue to make things simpler (either in design and/or the description).  Please take a look at the design especially if your are not that familiar wit XML Schemas.  

- Named groups have an additional sequence particle wrapping the main content model.
- Replacing an element via a constraint is a two step process.  It involves using the redefine mechanism in two different files.  This is a by-product of the current mechanisms that are available in XML Schema 1.0.
- More granular representation of content models.
       - This will, at least, double the number of architectural groups in the schemas.

If we didn't have to deal with XML Schema's inheritance mechanism or if we were to simply create a new content model for the constrained task, the content model representation would look very similar to that of the DTD representation found below.

XML Schema                                                                                                                 XML Schema - Constraint
<xs:group name="taskbody.content">                                                                 <xs:group name="taskbody.content">
    <xs:sequence>                                                                                                                         <xs:sequence>
       <xs:choice minOccurs="0" maxOccurs="unbounded">                                           <xs:group ref="prereq" minOccurs="0"/>
           <xs:group ref="prereq"/>                                                                                                <xs:group ref="context" minOccurs="0"/>
           <xs:group ref="context"/>                                                                                               <xs:choice minOccurs="0" maxOccurs="1">
           <xs:group ref="section" />                                                                                                 <xs:group ref="steps" />
       </xs:choice>                                                                                                                               <xs:group ref="steps-unordered" />
           <xs:group ref="steps" />                                                                                                  </xs:choice>
           <xs:group ref="steps-unordered" />                                                                          <xs:group ref="result"  minOccurs="0"/>
           <xs:group ref="process" />                                                                                           <xs:group ref="postreq"  minOccurs="0"/>
       </xs:choice>                                                                                                                          <xs:group ref="example"  minOccurs="0"/>
            <xs:group ref="result" minOccurs="0"                                                                   </xs:sequence>
           <xs:group ref="postreq" minOccurs="0" maxOccurs="unbounded"/>  </xs:group>
           <xs:group ref="example" minOccurs="0" maxOccurs="unbounded"/>

DTD                                                                     DTD - Constraint
<!ENTITY % taskbody.content                   <!ENTITY % taskbody.content
         "(((%prereq;) |                                                   "((%prereq;)?,
            (%context;) |                                                    (%context;)?,
            (%section;))*,                                                   (%steps; |
           ((%steps; |                                                        %steps-unordered;)?,
             %steps-unordered; |                                             (%result;)?,
             %process;))?,                                                   (%example;)?,
           (%result;)?,                                                      (%postreq;)?)"
           (%example;)*,                                         >

With DITA 1.0 and DITA 1.1 the XML Schemas  we have used the extension mechanism to add support for domains. These group overrides (extension) are defined in the shell schemas.  We have avoided using the XML Schema restriction mechanism in the past because of the number of rules, 25 of them, that the XML Schema must adhere to in order to create a valid schema.  

In order to make it easier for folks to implement their own constraints via XML Schemas I will need to make changes so that the pieces that could be constrained much smaller.  The hope is that with smaller named groups within content models it make using use of XML Schema restriction mechanism easier to do and use.

For DITA 1.2, the new design uses smaller group definitions to make it hopefully easier for specializers to constrain the content using XML Schema inheritance mechanism.  The addition of a <xs:sequence> will make it easier to satisfy one of the restriction rules for model groups.  Adding the minOccurs="0" for element that are optional will help make sure that the elements will be available during the comparison phase in the restriction algorithms.

I included a sample XML schema that demonstrates replacing <keyword> with <myKeyword> in the file test.zip.

The following sample below are the groups that will be defined in taskMod.xsd as part of feature 12011.

 Please take a look. If you have any comments, need clarification or just plain don't understand please respond.  There is no feature for this design change and I do need to update the schema specialization section in the architectural spec.  If flesh out some some of the details sooner than later, hopefully, we can help improve the uptake of DITA XML Schemas.

Kind regards,

<xs:group name="taskbody.content">
      <xs:group ref="taskGroup1"/>   <!-- The content model is broken down into smaller chunks.  The final version will have a better -->
     <xs:group ref="taskGroup2"/>   <!-- naming pattern instead of taskGroup#.   -->
     <xs:group ref="taskGroup3"/>


 <xs:group name="taskGroup1">
   <xs:sequence>                                  <!-- The piece to notice here is the addition of a <xs:sequence> wrapper on every content model definition -->
     <xs:choice minOccurs="0" maxOccurs="unbounded">  
       <xs:group ref="context" minOccurs="0"/>   <!-- We need to add the minOccurs values on the element definition otherwise the XERCES algorithm gets rid -->                      
       <xs:group ref="prereq"  minOccurs="0"/>   <!-- of pointless particles.  These need to be there in case if as part of the constraint you want to make them manditory  -->
       <xs:group ref="section" minOccurs="0"/>

 <xs:group name="taskGroup3">

        <xs:group ref="result" minOccurs="0"/>
       <xs:group ref="postreq" minOccurs="0"  maxOccurs="unbounded"/>
       <xs:group ref="section" minOccurs="0"  maxOccurs="unbounded"/>
 <xs:group name="taskGroup2">
      <xs:choice minOccurs="0" maxOccurs="1">
      <xs:group ref="steps" minOccurs="0"/>
      <xs:group ref="steps-unordered" minOccurs="0"/>
      <xs:group ref="process" minOccurs="0"/>

   Here is the what the redefined content models would look like as redefined in strictTaskbodyConstarintMod.xsd
   <xs:redefine schemaLocation="taskMod.xsd">

   <xs:group name="taskGroup1">
                <xs:group ref="prereq" minOccurs="0"/>
                 <xs:group ref="context"minOccurs="0"/>
   <xs:group name="taskGroup3">
         <xs:group ref="result" minOccurs="0"/>
         <xs:group ref="postreq" minOccurs="0"/>

          <xs:group ref="example" minOccurs="0"/>


Feature 12008  needs clarification
While implementing feature I noticed that we mention replacing an element so that it's no longer visible/available (same thing - we need to pick one of the two terms).  For reference I included the appropriate bullets from the feature proposal.

What has not been specified in the statement is whether or not it's permissible for a constraints can be emptiable.  By emptiable I mean allow the entity or named group override to be empty.  For instance,

<!ENTITY % keyword "">


<xs:group name="keyword">
<!-- empty container -->


<xs:group name="keyword">
        <xs:choice minOccurs="0">   <!-- optional container -->
       <xs;element ref="keyword" />

Although possible and allowable via DTD. I believe that TC should not allow the entities and model groups to be emptiable and include a statement as such in the Architectural specification.   Allowing containers to be empty can pose some validation issues if the original container is part or can become part of a sequence of required elements.  For the XSDs, you will not be able to validate the schema is the content is emptiable.  

NOTE: If containers can be emptiable, knowing that it might cause validation issues, then I will need to modify the design pattern accordingly.  If you want to have the ability to remove an element from a DTD/XSD, then my suggestion would be to remove it from the content model rather than emptying the container.

[1] - http://www.oasis-open.org/committees/download.php/25090/IssueConstraints12008.html
[2] - http://www.oasis-open.org/committees/download.php/26791/IssueNumber12011v1.2rev3.html
[3] - http://www.w3.org/TR/xmlschema-1/#coss-particle

Eric A. Sirois
Staff Software Developer
DB2 Universal Database - Information Development
DITA Migration and Tools Development
IBM Canada Ltd. - Toronto Software Lab
Phone:(905) 413-2841

Blue Pages (Internal)

"Transparency and accessibility requirements dictate that public information and government
transactions avoid depending on technologies that imply or impose a specific product or
platform on businesses or citizens" - EU on XML-based office document formats.


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]