[graap-wg] Alternative Approach to Templates and Constraints

[Karl Czajkowski]

Heiko and GRAAP:

I think I have narrowed down my discomfort with the current template
proposal... basically, I think we are on the right track with the
creation constraints but the prototype aspect is still too biased
towards a particular flavor of domain-specific term language that is
"flat" and has no variable-cardinality content.  Once you start
wanting to admit a domain language with optional fields or repeatable
fields WITHOUT TOTALLY CONSTRAINING ITS USE, this approach gets in the
way.


EVALUATION CRITERIA

We of course need to keep focused on delivering a specification, so I
am writing this email with the intent that people can review my
suggestions and decide if they make sense and are easy enough to write
into the specification without any non-trivial change to the schedule,
i.e. Heiko should feel that it isn't more complex or open-ended than
his proposal in terms of specification content, and that it also seems
beneficial, and others should agree as well. :-)

My concept of an "ideal" template is one that does the following in
a very concise manner (in rough order of importance):

  1. identify the domain-specific language(s) that are allowed
     in terms

  2. specify the prototype values for terms, e.g. fixed or default**
     values which are specific to one WS-Agreement service rather
     than schema-level fixed/default values

  3. specify other more general content restrictions, e.g. identify
     a place where the domain-language has open content and specify
     a smaller list of recognized extensions that are acceptable

  4. related to (1), specify the compositional rules/restrictions
     for terms in an offer, e.g. the whole "template composition"
     discussion.  this is basically a matter of asserting restrictions
     to the generic wsag:compositor syntax of the offer.

  5. assumes schema-level understanding of the content model in
     the absence of prototypes and restrictions, i.e. do not require
     the template to re-state the structural requirements of the
     domain language if the WS-Agreement service is not trying to
     restrict it further

In other words, the offer MUST (SHOULD?) conform to the WS-Agreement
envelope and domain-specific term schemas, and it also MUST (SHOULD?)
conform to the additional prototypes and restrictions of the template!

The current proposal doesn't allow concise mixing of the prototype and
restriction mechanisms.  You end up having to either generate a large
set of creation constraints that express the different parts of the
domain schema (redundantly) against a prototype, or you cannot use the
prototype feature and you provide one more compact creation
constraint.

My view is that the current prototype mechanism is not valuable enough
to keep, when a slight modification to the constraint model can cover
the case where it is concise (a simple fixed list of values).


ALTERNATE PROPOSAL

Make the entire template a set of constraint rules which have a new
"triggering" and "reference" model: they refer to the eventual offer
document by XPath instead of the (now non-existent) prototype
document.  Furthermore, they are softened by default to only apply IF
their XPath reference matches content in the prototype. (If they
select an empty "nodeset" from the offer, they are ignored by
default.) An extra attribute is permitted to override this soft
triggering model and REQUIRE that the nodeset references by the Xpath
(even if empty) match the constraint's content model.

   <Item>
      <Location required="boolean"?>XPath</Location>
      ...XSD content model...
   </Item>

Whatever content in the offer is addressed by /Item/Location must
conform to the content model in the rule. The Location is evaluated
with the wsag:offer element as the root. This content model can be any
of the following to cover our use cases:

   1. a literal value or subtree to cover the fixed/prototype case

   2. a simple restriction for the old enumeration use case

   3. a complex restriction/group for the new structural restriction

   4. an attribute group to cover the bases for reasonable XPath
      references?

There is an implicit rule in every template which could be made
explicit without harm:

   <Item>
      <Location required=true>/wsag:AgreementOffer</Location>
      <xsd:sequence>
         <xsd:element ref="wsag:AgreementOffer"/>
      </xsd:sequence>
   </Item>

Which by itself means that the offer must conform to the WS-Agreement
normative schema.

A minimal open-ended template might just want to identify the domain
language and a simple compositor structure without making additional
restrictions:

   <Item>
      <Location required=true>
         /wsag:AgreementOffer/wsag:Terms/wsag:All/*
      </Location>
      <xsd:sequence>
         <xsd:element ref="wsag:ServiceDescriptionTerm"/>
      </xsd:sequence>
   </Item>
   <Item>
      <Location>//wsag:ServiceDescriptionTerm/*</Location>
      <xsd:sequence>
         <xsd:element ref="tns:docroot"/>
      </xsd:sequence>
   </Item>

The first rule says that the offer must have the very simple form of
an All compositor with one child element ServiceDescriptionTerm... the
number of children could be opened up with cardinality attributes in
the sequence definition of the rule.  Alternatively, someone could
write a rule with Location /wsag:AgreementOffer and then provide more
inline typing to give a restriction of it?

The second rule says that the (any) service description term must have
the tns:docroot domain-specific element in it.  A benefit of this
approach for complex domain languages is that the variable structure
of the domain language is preserved with all its flexibility UNLESS
the template lists constraints against the structure.

Someone more familiar with XPath and/or XSD may be able to show a more
compact way to write both of these conditions into one rule.

To do the fixed value fieldA from Heiko's email:

   <Item>
      <Location>//tns:docroot/fieldA/text()</Location>
      <wsag:literal>fixed value</wsag:literal>
   </Item>

i.e. we define one "literal" content model to handle the prototype
cases concisely.  (Is there an XSD feature that works as well? The
most concise I can think of is a one-element enumeration
restriction...)

These rules can be overlapping at different depths in the tree, so
that the "top-level" rules fix the superstructure with brief
ref=elementname descriptions of structure, implying that the general
purpose elementname schema is acceptable, while later rules further
restrict the use of that schema by referencing substructures in the
descendents of elementname.

Thus, I hope I have demonstrated that this approach is just as
expressive in terms of conveying information about offer requirements
to the human.  I do not think we have use-cases in mind yet where we
can evaluate the automatic consumption of templates by schema-aware
software. :-( I think this is more general and consistent w/ the
nodeset/infoset model of XPath selection, e.g. rules select parts of
the offer and define schematic requirements on those selected parts.


EXAMPLE

Here is the concrete example w/ the same implied offer content as
Heiko's email example, e.g. I've left out the same contextual bits as
were left out in his!

<template>
   <Item>
      <Location required=true>//wsag:ServiceDescriptionTerm/*</Location>
      <xsd:sequence>
         <xsd:element ref="tns:docroot"/>
      </xsd:sequence>
   </Item>

   <Item>
      <Location>//tns:docroot/fieldA/text()</Location>
      <wsag:literal>fixed value</wsag:literal>
   </Item>

   <Item>
      <Location>//tns:docroot/fieldB/text()</Location>
      <xsd:restriction base="xsd:string">
         <xsd:enumeration value="foo"/>
         <xsd:enumeration value="bar"/>
      </xsd:restriction>
   </Item>

   <Item>
      <Location>//tns:docroot/fieldC</Location>
      <xsd:sequence>
         <xsd:element ref="tns:fieldC" maxOccurs="128"/>
      </xsd:sequence>
   </Item>

   <Item>
      <Location>//tns:docroot/[fn:namespace-uri()!=http://tns/path]</Location>
      <xsd:sequence>
         <xsd:element ref="wsgram:FileStageIn" minOccurs=0 maxOccurs=unbounded/>
      </xsd:sequence>
   </Item>
</template>

Note that the only reason I have to assert a constraint for fieldC is
because I am restricting its cardinality. Otherwise, I could leave it
off and the consumer of the template would assume the schema
definition for tns:docroot is the only constraint, e.g. fieldC would
be unbounded or whatever cardinality is given in the schema.


karl


** I want to raise the idea that a default value semantics (B) that
differs from the domain-specific schema is a confusing topic.
Shouldn't a term document have the same meaning everywhere? (Shouldn't
the domain schema remain normative for interpreting the absence of
content?)  If we want to advertise a "default", maybe it should really
be a weaker form of constraint which has the meaning "we recommend
this value if you don't have any other preference", but it is still
the initiators responsibility to fill in some value?



-- 
Karl Czajkowski
karlcz at univa.com