POJO v.1.1 Test Assertions Version 1.0

[Patrick Durusau <patrick@durusau.net>]

Greetings,

Some comments on behalf of the TAB.

Citation Format:

Reads:

When referencing this specification the following citation format should 
be used:
SCA-POJO-CI-TA-v1.0OASIS Committee Specification Draft 01, SCA POJO 
Component Implementation v1.1 Test Assertions Version 1.0, November 
2010, 
http://docs.oasis-open.org/opencsa/sca-j/sca-j-pojo-ci-1.1-test-assertions-1.0-csd01.pdf

*****

Actually not. That is to say what is given isn't a citation format but 
the citation for the standard.

Thus:

Citation of this specification:

Shortref: SCA-POJO-CI-TA-v1.0

Name: OASIS Committee Specification Draft 01, SCA POJO Component 
Implementation v1.1 Test Assertions Version 1.0, November 2010

Location:  
http://docs.oasis-open.org/opencsa/sca-j/sca-j-pojo-ci-1.1-test-assertions-1.0-csd01.pdf

****

BTW, did you know the entire name is a hyperlink in the PDF?

****

Not to quibble but the format for the test assertions are defined in 
[TA-Guide]. So, why does 1.1 Example Test Assertion repeat that definition?

BTW, 1.1 should either be cut or re-written.

Illustrative issues (not all of them):

Reads: Assertion ID: Is a unique ID for the test assertion.

Should read: Assertion ID: The unique ID of a test assertion.

***

Reads: Source: The identifier(s) of normative statement(s) in *the 
specification* ??? which one?

***

Reads: "Target: Identifies the target which is addressed by this 
assertion."

If I knew what that was intended to mean I might be able to help. 
Defining a term using a term is risky business.

BTW, "typically" statement should be in notes if allowed at all.

artefact -> artifact (yes, I know British spelling and all that.)

****

Reads: Prerequisites: Defines any prerequisites for this test assertion. 
The prerequisites may be defined in terms of one or more other test 
assertions that must be true.

Should read: Prerequisites: Defines prerequisites for a test assertion.

Prerequisites may be defined in terms of one or more other test 
assertions that must be true.

Question: Is this a normative "may?" If so, probably needs to be in a 
separate line and use a style for the line to make it easy to extract 
later on. That is a separate style for must, may, can, etc.

Question: Do you really want to limit prerequisites to true? What if my 
prerequisite is to fail a test? That is my test assertion results in 
false, which means some other prerequisite comes into play.

*****

Reads: Predicate: The meat of the assertion - something that should 
evaluate to true or false for the given target.

???

Sorry, "The meat of the assertion..." doesn't qualify as standards prose.

Try:

The test defined by an assertion.

All tests, when applied to a target, result in true or false conditions.

(I am not sure what is expected. A result, report, condition, etc. 
change as appropriate)

*****

Reads: Prescription Level: Mandatory (for MUST requirements) or 
Preferred (for SHOULD requirements) or Permitted (for MAY requirements).

Question: Why redefine MUST, SHOULD and MAY?

Suggest: Prescription Level: MUST, SHOULD, MAY

****

Reads: Tags: Zero or more labels that may be attached to this test 
assertion - these tags can be used to group sets of assertions.

Suggest: Tags: Tags: Zero or more labels that may be attached to a test 
assertion.

Note: Tags can be used to group sets of assertions.

(Well, except that I don't know how the standard defines grouping or for 
what purpose. Or do you mean some informal search type grouping?)

1.2 Terminology

as described in IETF RFC 2119 [RFC 2119] -> it is usually written:

as described in [RFC 2119].

1.3 Normative References:


[RFC 2119] S. Bradner. Key words for use in RFCs to Indicate Requirement 
Levels. IETF RFC 2119, March 1997.


The IETF says:

RFC2119 Bradner, S., "Key words for use in RFCs to Indicate Requirement 
Levels", BCP 14, RFC 2119, March 1997.

Yes, I know, the template has it as you do. The template is wrong. See 
the canonical list at: ftp://ftp.rfc-editor.org/in-notes/rfc-ref.txt

2 Test Assertions

General comments:

[JC120001] is not a sufficient reference to something outside this document.

In JC1-TA-2001, lose the "" marks around Tags (and all that follow).

In JC1-TA-2002 (and following), there is no "SCA POJO component 
implementation class" defined here or elsewhere.

In Service Component Architecture SCA-J Common Annotations and APIs 
Specification Version 1.1, the term "SCA POJO component implementation 
class" is never defined so far as I can tell. There is reference to a 
"Java implementation class" but even there, not to define it.

Just to skip ahead a bit, look at:

JC1-TA-4002

"The SCA Runtime converts the property value into an instance of the 
property's Java type as defined by the XML to Java mappings in the JAXB 
specification with XML schema validation enabled."

I can't find the JAXB specification reference in this document.

In the Service Component Architecture document there is a reference to 
JAX-B but it would be an assumption on my part that they are the same.


3 Service Component Architecture POJO Component Implementation 
Specification Version 1.1

It isn't clear where the references in the Conformance Statement are 
pointing.

The only likely normative reference is JAVACI but that has an Annex of 
conformance statements, which is clearly not allowed under the OASIS rules.


4 Conformance - No conformance statements for Test Assertions?

Or is that the purpose of unknown conformance clause mapping?

Hope everyone is having a great holiday season!

Patrick

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

Another Word For It (blog): http://tm.durusau.net
Homepage: http://www.durusau.net
Twitter: patrickDurusau