[Geopriv] Comments: draft-rosenberg-simple-common-policy-caps-02

I've cross-posted this because there are folks in GEOPRIV who are interested.

Comments for: An Extensible Markup Language (XML) Representation for
Expressing Presence Policy Capabilities
(draft-rosenberg-simple-common-policy-caps-02.txt)

-- General

(Summary: The draft describes a means of conveying information about the level
of support for common-policy features. This information is carried within
the body of a policy document and is represented by XML elements. Each
feature is represented by an element, and the presence of this element
indicates support for that feature.)

This draft is essential if common-policy is to have any longevity. As
stated, the basic set of features provided by common-policy are limited - the
idea being that it is extended by other specifications or vendor extensions.
If this sort of mixed content is allowed, it is very useful to have some
means of communicating capabilities.

-- Mode of operation

(Summary: A client may query the capabilities of a server by requesting a
document before publishing any content.)

As far as this usage is concerned, I don't anticipate any problems. Each
protocol needs to have a means of requesting this document.

I would be a little stricter with regards to specifying how a client retrieve
the document though. Suggest that you RECOMMEND that servers don't remove
capabilities - a published capabilities document is like a promise. Also,
for XCAP, I assume that the standard HTTP methods can be used to set expiry
times and check for changes (ETag, If-Modified-Since, etc...). That should
suffice for most clients.

-- XML document structure

(Summary: The document structure closely mirrors the common-policy structure
- the presence of an element indicates support for that element.)

I have a problem with the way that the capabilities document is structured.
I'll present my critique, then I will propose a few alternatives.

Encoding data using element names is ... ugly. Element names in an XML
document are descriptive of the structure of the document, not the data that
the document conveys. For example, if I want to indicate that I support the
cp:identity element, "cp:identity" is data, not structure.

The best analogy that I can think of would be to protocol headers, and I
don't think that it's too much of a stretch. Imagine if the Allow header in
SIP and HTTP where instead implemented as a series of headers: Allow-INVITE,
Allow-ACK, Allow-OPTIONS, Allow-PUBLISH, ...

I understand that in some cases, the line between structure and data can
become blurred, but this draft takes it too far. I also appreciate that
there may already be a precedent for this practice; I have exactly the same
problem with those drafts, I hope that their authors read this, understand
and make some changes.

To understand the problem, you have to understand how it arrives. My theory
is that an author needs to indicate a set of possible values for a parameter.
I can define a simple type in schema as an example:

  <xs:simpleType name="cookingType">
    <xs:restriction base="xs:token">
      <xs:enumeration value="fried"/>
      <xs:enumeration value="boiled"/>
      <xs:enumeration value="poached"/>
      <xs:enumeration value="scrambled"/>
    </xs:restriction>
  </xs:simpleType>

However, the above list probably isn't exhaustive; someone will inevitably
find another way to cook an egg and will then want to use that value instead.
So I _could_ just loosen the structure a little bit, but the enumeration
elements aren't useful any more:

  <xs:simpleType name="cookingType">
    <xs:restriction base="xs:token">
      <xs:pattern value="\w+"/>
    </xs:restriction>
  </xs:simpleType>

But then, it isn't explicit that "fried" isn't a valid value. I leave those
words in the specification text, but it doesn't leave me with the same
satisfying feeling that I have put the constraint into schema. Hence the
following structure evolves, which seems to satisfy:

  <xs:complexType name="cookingType">
    <xs:choice>
      <xs:element name="fried" type="my:emptyType"/>
      <xs:element name="boiled" type="my:emptyType"/>
      <xs:element name="poached" type="my:emptyType"/>
      <xs:element name="scrambled" type="my:emptyType"/>
      <xs:any namespace="##other"/>
    </xs:choice>
  </xs:complexType>

This looks like it solves the problem, and it more-or-less does, but this
means that the document now has structural information that has to be
interpreted as data. It is longer clear what a document means - empty
elements indicate an empty container - what in this instance is indicated by
an empty <fried/> element? Aside that, a client that interprets this
document becomes more complex, documents become a little larger.

I believe that in these cases it is better to leave the explicit content out
of the schema and make recommendations using the text.

Another example that is less clear:

  <xs:complexType name="someType">
    <xs:sequence>
      <xs:element ref="unimportant"/>
      <xs:element name="booleanData" type="my:emptyType" minOccurs="0"/>
      <xs:element ref="irrelevant"/>
    </xs:sequence>
  </xs:complexType>

Presence indicates a value of "true". But once again, we have structure and
content mixing. The proper thing to do would be to change the type:

  <xs:element name="booleanData" type="xs:boolean"/>

..or if the ability to omit the datum is important, it can be an attribute
with a default value:

  <xs:attribute name="booleanData" type="xs:boolean" default="false"/>

I usually reserve attributes for metadata, modifiers and qualifiers, any
choice will depend on the specific goals you have in mind.


So back to the issue at hand, I would be remiss of me to point out problems
without offering suggestions, so I am going to propose an alternative. You
will actually see that this approach actually goes another step and makes the
proliferation of companion documents (like
draft-guenther-geopriv-policy-caps-03) unnecessary - you only need to
understand a document specified in this namespace to understand the
capabilities of the server. This has the benefit of making the capabilities
document significantly less complex than the actual instance document,
particularly from the perspective of specification.

I have split this into two levels of support. This is somewhat reminiscent
of common-policy in that there are analogues of <one/> and <many/>. If the
distinction between condition, action and transformation needs to be
retained, I have added an element that can be used to establish a context.

These things tend to be easiest to explain by example so here is my example
document:

  <policy-capabilities xmlns="urn:ietf:params:xml:ns:policy-capabilities"
                       xmlns:cp="urn:ietf:params:xml:ns:common-policy"
                       xmlns:vpp="http://www.example.com/policy-caps-ex">
    <support-namespace ns="urn:ietf:params:xml:ns:common-policy"/>

    <context select="cp:conditions">
      <support-namespace ns="urn:ietf:params:xml:ns:geopriv-policy"
                         schemaLocation="geopriv-policy.xsd">
        <except>civic-loc-condition</except>
        <except>//@crsName[string(.)!="urn:ogc:def:crs:EPSG:6.6:4326"]</except>
      </support-namespace>
      <support>vpp:happy</support>
    </context>

    <context select="cp:actions">
      <support>vpp:log</support>
    </context>

    <context select="cp:transformations">
      <support-namespace ns="urn:ietf:params:xml:ns:geopriv-policy"
                         schemaLocation="geopriv-policy.xsd">
        <except>civic-loc-transformation</except>
      </support-namespace>
      <support children="false">vpp:min-security</support>
    </context>

  </policy-capabilities>

The above is largely the same as that given in the document, but it also
includes indicates that geopriv-policy is supported for conditions and
transformations, except the civic components.

If you understand Schematron (http://www.schematron.com/overview.html), this
document uses statements not dissimilar to Schematron constraints. A context
is established and within that context the supported elements are identified.
By default the context is each <rule> element in the ruleset.

Once a context has been established, there are two sorts of statements that
can be used:

  A <support> statement indicates support for a particular XPath node. For
  instance the above document states that it supports the vpp:happy element.
  By default, all children of the node are included
  (i.e. "//*[ancestor-or-self::*/...]" is implied), unless explicitly
  excluded by using the attribute children="false" . Note <support> actually
  selects a node-set, which may include multiple elements.

  A <support-namespace> statements indicates support for all elements from a
  given namespace. An optional schemaLocation attribute establishes a common
  understanding of what that namespace implies (a little disambiguation helps
  sometimes). Nodes that are not supported from that document are indicated
  using the <except> element.

One aspect of this document is that it could be used to construct an input
filter for the server. I can turn the above document into code that would
test for compliance to the capabilities relatively easily.

I'm sure that a complete XPath implementation might seem to be a little too
much for this particular task, so I'd recommend a similar subset to that
used for XCAP, which should be quite adequate. The given example for crsName
is probably something that could be cut without too many problems.


One final comment - I don't see the need for the .pcp extension for this
document, particularly since you aren't actually using it for XCAP.


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
Geopriv@ietf.org
https://www1.ietf.org/mailman/listinfo/geopriv
Received on Mon, 31 Oct 2005 22:26:17 -0600