RE: [dita] Constraints and Inheritance

[Erik Hennum <ehennum@us.ibm.com>]

Hi, Paul:

Just to make sure we're all on the same page, the job of the document type is assembly of design modules. The design modules that define elements don't have any constraints. The constraints are provided in distinct redefinition modules that can be assembled or omitted from document types. So, you can always use elements without constraints merely by choosing to assemble a document type that doesn't include or declare any constraints.

By including and declaring a constraint in a document type, you agree to honor the contract including implementing the constraint on the specializations of the base constrained elements within that document type. In exchange, you get interoperability with others who implement the same constraint.

With that understanding, here's an example for why we want declared constraints to apply to specializations.

SomeOrg wants every topic to have a shortdesc so it can provide a detailed abstract is always available for links. SomeOrg defines the constraint and require all designers to assemble the base constraint module in their document types. A validator that's sensitive ot the DITA architecture will report an error if a specialized topic type doesn't require shortdesc.

Continuing the example, OtherOrg has a requirement for tutorials and has created a tutorial topic type.

OtherOrg and SomeOrg decide to partner. SomeOrg explains their requirement for shortdesc. Swayed by their arguments and (more importantly) the business opportunity, OtherOrg agrees. SomeOrg provides the constraint to OtherOrg, which adds the constraint to their document types and then updates all of their topic instances including their tutorials to add the shortdesc elements.

OtherOrg ships their tutorial content to SomeOrg. SomeOrg, which doesn't use the tutorial topic type, generalizes from the constrained tutorial to the constrained topic type and merrily processes the content.

Alas, the partnership sours. Under the terms of the agreement, SomeOrg retains a copy of the content to edit as they wish with no distruption of their standard operating procedures. That's possible only because SomeOrg and OtherOrg shared the constraint that guaranteed valid generalization of the instances.

On the specific question...

[Paul] There is a thing called topic/section in the doctype "standard DITA". For the purposes of communication, let's call that object DITA/topic/section. Let's say I constrain it in my doctype. There is logically a new object in the universe called mydoctype/topic/section. Now the question is: does mydoctype/topic/example need to conform to the constraints from DITA/topic/section or those from mydoctype/topic/section? I claim that I usually want them to inherit from the unconstrained standard (which is what all of my downstream tools will be programmed to deal with) rather than the constrained local version (which is primarily applicable to my authoring tool).

I'm not sure about the particular scenario because topic/example doesn't specialize from topic/section. But, the goal should be pluggable modules along the following lines (the issue that Michael raised this morning):

1. As in DITA 1.0, the topic module defines the topic/topic element.

2. As in DITA 1.0, the unconstrained topic document type assembles the topic module.

3. As in DITA 1.0, the mytopic module defines the mytopic/mytopic specialization.

4. As in DITA 1.0, the unconstrained mytopic document type assembles the topic and mytopic modules.

5. The shortdesc-required declaration module defines the shortdesc-required constraint to target topic/topic. A separate topic shortdesc-required module implements the constraint on the topic element.

6. The constrained topic document type (an alternative to 2) assembles the topic, shortdesc-required declaration, and shortdesc-required implementation modules.

7. If desired, the mytopic shortdesc-required module implements the shortdesc-required constraint on the mytopic/mytopic element.

8. If desired, the constrained mytopic document type (an alternative to 4) assembles the topic, shortdesc-required declaration, topic shortdesc-required implementation, mytopic, and mytopic shortdesc-required implementation modules.

If that seems like a lot, please recall that several people are something similar today in order to bend the rules of the DITA architecture. This enhancement just brings that capabilities into the architecture. Anyway,

Instances of 8 can generalize to 6, 4, or 2.
Instances of 6 can generalize to 2.
Instances of 4 can generalize to 2.

Defining 6 doesn't create an absolute _requirement_ to define 7 and 8. I could instead create instances of 4. The instances of 4 can't be generalized to 6, but I can always generalize both to 2.

Does that clarify?

While there's no requirement, I suspect that most designers would be willing to put in the extra work to get the consistency and the ability to generalize.

The best practice would be write processes for unconstrained instances just in case you ever do have to interoperate with someone who doesn't implement your constraints.


Thanks for helping to drive the articulation of this architectural proposal,


Erik Hennum
ehennum@us.ibm.com