TAB Reviewer for PPS-Core-Elements-1.0, PPS-Transaction-Message-1.0,PPS-Profile-Specifications-1.0

[Patrick Durusau <patrick@durusau.net>]

Greetings!

One of the more interesting duties I have as an OASIS TAB (Technical 
Advisory Board) member is being assigned to return comments on work in 
OASIS that is up for public review. It gets me out of my markup backyard 
and to look at work I would not normally see. (What follows are my 
opinions and not those of the TAB.)

Unfortunately that sometimes means I have to point out problems that I 
think OASIS should have mechanisms to help TCs catch earlier in the 
standards process.* This is one of those times.

All three documents cite RFC 2119 (http://www.ietf.org/rfc/rfc2119.txt).

There the word SHOULD is defined as:

> 3. SHOULD   This word, or the adjective "RECOMMENDED", mean that there
>     may exist valid reasons in particular circumstances to ignore a
>     particular item, but the full implications must be understood and
>     carefully weighed before choosing a different course.
>    

If we take the second and third sentences of 2.1 Structure of primitive 
elements

> The type of this element SHOULD be represented with the following XML 
> schema and SHOULD fulfill the following constraints.
and
> id attribute SHOULD represent an identifier of this element.

It is fairly clear that SHOULD is the wrong term to use.

What is literally being said for the "id" attribute is that it "should" 
represent "an identifier of this element," but it could also represent 
the identifier for some other element or some other value altogether, so 
long as "...the full implications [are] understood and carefully 
weighted before choosing another course."

All three documents have extensive and incorrect use of the term "SHOULD."

Personally I don't bother with normative language for attributes and 
simply state them. The <blort> element attributes are: <listHere>.

That means that you can define conformance as conforming to element 
<blort> as defined and its children or whatever.

The use of "SHOULD" returns to bite you in the conformance clauses.

9 Conformance (of PPS-Core-Elements-1.0) reads:

> A document or part of document confirms OASIS PPS Core Elements if all 
> elements in the artifact are consistent with the normative text of 
> this specification, and the document can be processed properly with 
> the XML schema that can be downloaded from the following URI.

Yes, but we have already seen any text could be consistent with the 
normative text. A standard full of shoulds really isn't a standard at all.

For all three documents I would suggest that you review: 
http://docs.oasis-open.org/templates/TCHandbook/ConformanceGuidelines.html.

It is also problematic when you say "consistent with the normative 
text." Not sure what that means.

Not my area so I don't know what parts of the standards I shall conform 
to, etc.

BTW, should your ID attributes be xsd:string?

The word "description" is mis-spelled in the schema fragments in 4.2, 
4.3, 4.6, as "descirption." (In PPS-Profile-Specifications-1.0)

Question: Have the examples been checked against the schema with 
validation software? Just asking. I didn't try to parse them out by hand.

****

Some style comments that aren't critical but suggestive:

The schema is required to be available as a separate electronic document 
so I would lose the embedded schema. Particularly since you repeat the 
same information immediately after each fragment in prose.

I would then split up all the attributes and define each one once 
instead of for each element. Plus put the attributes in numbered 
subsections so they can be easily referenced. See ODF part 1 for an 
example of this style. (Yes, I am the editor. ;-) ) Like I said, style 
comments which are ultimately personal choice. See what works for you 
and your community.

I did not proof the documents with a spell checker but I would suggest 
doing so, particularly since I did find a spelling error in the schema 
for PPS-Profile-Specification-1.0. More of a schema typo than anything 
else but would not hurt to check the rest of the documents.

Hope everyone is looking forward to a great weekend!

Patrick

* That is not a universally held opinion at OASIS but it is mine.

-- 
Patrick Durusau
patrick@durusau.net
Chair, V1 - US TAG to JTC 1/SC 34
Convener, JTC 1/SC 34/WG 3 (Topic Maps)
Editor, OpenDocument Format TC (OASIS), Project Editor ISO/IEC 26300
Co-Editor, ISO/IEC 13250-1, 13250-5 (Topic Maps)