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

[Eric Sirois <esirois@ca.ibm.com>]

Hello,

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.   



Highlights
- 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.



Design
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"/>
    </xs:sequence>
</xs:group>

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;)*,
                     
                  >
           (%postreq;)*)"
                     
                 
>

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,
Eric

Task.mod
<xs:group name="taskbody.content">
    <xs:sequence>
       <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:sequence>
  </xs:group>

  <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:choice>
    </xs:sequence>
  </xs:group>

  <xs:group name="taskGroup3">
    <xs:sequence>
        <xs:group
ref="result" minOccurs="0"/>
        <xs:group ref="postreq" minOccurs="0"
 maxOccurs="unbounded"/>
        <xs:group ref="section" minOccurs="0"
 maxOccurs="unbounded"/>
    </xs:sequence>
  </xs:group>
  
  <xs:group name="taskGroup2">
    <xs:sequence>
       <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"/>
     </xs:choice>
    </xs:sequence>
  </xs:group>

   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:sequence>
             <xs:sequence>
                 <xs:group ref="prereq"
minOccurs="0"/>
                  <xs:group
ref="context"minOccurs="0"/>
              </xs:sequence>
           </xs:sequence>
    </xs:group>
    
    <xs:group name="taskGroup3">
      <xs:sequence>
        <xs:sequence>
          <xs:group ref="result"
minOccurs="0"/>
          <xs:group ref="postreq"
minOccurs="0"/>
          <xs:group
ref="example" minOccurs="0"/>
        </xs:sequence>
      </xs:sequence>
    </xs:group>

</xs:redefine>        

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.

• Constrains the generic <ph> element to be replaced by its <filepath>, <userinput>, and <systemoutput> specializations so the <ph> element is no longer visible.
• Constrains the generic <keyword> element to be replaced by its <cmdname> and <varname> specializations so the <keyword> element is no longer available.

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 "">

or 

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

or 

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

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
Email: esirois@ca.ibm.com
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.

test.zip