This document is a review of OWL Web Ontology Language Semantics and Abstract Syntax (Working Draft 31 March 2003) against the QA Framework: Specification guidelines. If you need to discuss about this review, please, do it on the www-qa mailing-list (www-qa@w3.org).
This checklist includes all checkpoints from the QA Framework: Specification Guidelines [QAF-SPEC] presented in a tabular format. The checkpoints are presented by order of their priorities, which makes it an appropriate Implementation Conformance Statement for the guidelines.
These comments do not relate to the QA Spec Guidelines specifically, but have been made when evaluating and reading the OWL Semantics Specification. You can ignore them if you choose to do it.
Often your specification will gain by establishing a clearer language. Your text if often too crowded and it makes difficult to articulate the concepts, like in this example, where I have rewritten one of your paragraph, just by changing the markup:
Your version
Definition: An OWL vocabulary V consists of seven sets of URI references, VC, VD, VI, VDP, VIP, VAP, and VO. In any vocabulary VC and VD are disjoint and VDP, VIP, VAP, and VOP are pairwise disjoint. VC, the class names of a vocabulary, contains owl:Thing and owl:Nothing. VD, the datatype names of a vocabulary, contains the URI references for the built-in OWL datatypes and rdfs:Literal. VAP, the annotation property names of a vocabulary, contains owl:versionInfo, rdfs:label, rdfs:comment, rdfs:seeAlso, and rdfs:isDefinedBy. VIP, the individual-valued property names of a vocabulary, VDP, the data-valued property names of a vocabulary, and VI, the individual names of a vocabulary, VO, the ontology names of a vocabulary, do not have any required members.
My version of the same paragraph
- OWL vocabulary V
Definition: An OWL vocabulary V consists of seven sets of URI references, VC, VD, VI, VDP, VIP, VAP, and VO.
In any vocabulary VC and VD are disjoint and VDP, VIP, VAP, and VOP are pairwise disjoint.
- VC
- the class names of a vocabulary, contains owl:Thing and owl:Nothing
- VD
- the datatype names of a vocabulary, contains the URI references for the built-in built-in OWL datatypes and rdfs:Literal.
- VAP
- the annotation property names of a vocabulary, contains owl:versionInfo, rdfs:label, rdfs:comment, rdfs:seeAlso, and rdfs:isDefinedBy.
- VIP
- the individual-valued property names of a vocabulary
- VDP
- the data-valued property names of a vocabulary
- VI
- the individual names of a vocabulary
- VO
- the ontology names of a vocabulary, do not have any required members.
To be A-conformant with the guidelines, the following Priority 1 checkpoints must be fulfilled:
Nbr | Checkpoint | Yes | No | N/A |
---|---|---|---|---|
Guideline 1. Define Scope. |
||||
1.1 |
Include the scope of the specification. |
NO: The introduction doesn't say what are the application fields of the language. What are the possible usages of it. | ||
Guideline 2. Identify what needs to conform and how. |
||||
2.1 |
Identify all classes of product. |
YES: in the last chapter of your introduction, you define who and what will use this specification. You may work a bit more on it to detail a bit more and make a list with the different classes of products, you have identified: 1) parsers and syntactic tools 2) reasoners and semantic tools. No others classes of products? | ||
2.2 |
For each class of product, define the conformance requirements. |
NO: You didn't define the conformance requirements for each class of products and you do not have at all a conformance section. | ||
Guideline 3. Specify conformance policy. |
||||
3.4 |
If special conformance terms are used, include a definition in the specification. |
NO: Define a conformance section. | ||
3.5 |
Justify any usage of a dimension of variability by reference to usage scenarios and requirements |
NO: Define a conformance section. | ||
Guideline 4. Address the use of profiles to divide the technology. |
||||
4.1 |
Indicate whether or not the use of profiles is mandatory for conformance. |
N/A | ||
Guideline 5. Address the use of modules to divide the technology. |
||||
5.1 |
If modules are chosen, indicate any mandatory conditions or constraints on their usage. |
N/A | ||
Guideline 7. Identify the relation between deprecated features and conformance. |
||||
7.1 |
Identify each deprecated feature. |
N/A | ||
7.2 |
For each class of product, specify the degree of support required for each deprecated feature and the conformance consequences of the deprecation. |
N/A | ||
Guideline 8. Define discretionary items. |
||||
8.1 |
State the circumstances for when discretionary items are allowed |
N/A | ||
8.2 |
For implementation dependencies, address the allowable differences between implementations |
N/A | ||
Guideline 9. Allow extensions or NOT! |
||||
9.1 |
Indicate if the specification is extensible. |
NO: You should define if the extension are allowed or not. | ||
9.2 |
If extensions are allowed, define their scope and constraints. |
N/A: just because we don't know if the specification is extensible or not. | ||
9.3 |
Prevent extensions from contradicting the specification. |
N/A: just because we don't know if the specification is extensible or not. | ||
Guideline 10. Provide a conformance clause. |
||||
10.1 |
Include a conformance section. |
NO: You didn't provide any conformance clause. You have to give one explaining how the different classes of products should conform to your specification. | ||
Guideline 11. Specify how to make conformance claims. |
||||
11.1 |
Identify and define all conformance designations. |
N/A: Only because you don't have any conformance sections. | ||
11.4 |
Impose no restrictions about who can make a claim or where claims can be published. |
N/A: No conformance section. | ||
Guideline 13. Clearly identify conformance requirements. |
||||
13.1 |
Use conformance key words. |
NO: How one defines that he has done the right thing? How one knows what he must implement or not? | ||
13.2 |
Distinguish normative and informative text. |
NO: You do not define the section of your documents which are normative BUT you defined the informative ones. Please add after each section, not only the table of contents a sentence to indicate that this part is normative, or that part is informative. | ||
13.3 |
Use consistent terminology. |
YES: It seems correct, even if your text often lacks of clarity in the presentation, which doesn't help for reading and understanding it. |
To be AA-conformant with the guidelines, the following Priority 2 checkpoints must be fulfilled (in addition to the above Priority 1 checkpoints):
Nbr | Checkpoint | Yes | No | N/A |
---|---|---|---|---|
Guideline 1. Define Scope. |
||||
1.4 |
Provide examples. |
NO: The section example in your document is more about usage scenario. See below. | ||
Guideline 3. Specify conformance policy. |
||||
3.1 |
Specify any universal requirements for minimum functionality. |
NO: you don't define the minimal requirement even if you could because it seems you have levels. | ||
Guideline 4. Address the use of profiles to divide the technology. |
||||
4.2 |
If profiles are chosen, define any minimal requirements. |
N/A | ||
4.3 |
If profiles are chosen, define their relationships and interaction with other dimensions of variability. |
N/A | ||
4.4 |
If profiles are chosen, address rules for profiles. |
N/A | ||
Guideline 5. Address the use of modules to divide the technology. |
||||
5.2 |
If modules are chosen, define their relationships and interaction with other dimensions of variability. |
N/A | ||
Guideline 6. Address the use of functional levels to divide the technology. |
||||
6.1 |
If levels are used, define their relationships and interaction with other dimensions of variability. |
YES: You are using levels: OWL Lite -> OWL DL -> OWL Full (btw you don't say what DL means) | ||
Guideline 8. Define discretionary items. |
||||
8.3 |
Indicate any constraints on the number of choices/options that can be implemented for discretionary choices |
N/A | ||
8.4 |
Promote consistent handling of discretionary choices. |
N/A | ||
Guideline 10. Provide a conformance clause. |
||||
10.2 |
Make normative reference to specifications on which the current specification depends |
YES | ||
Guideline 13. Clearly identify conformance requirements. |
||||
13.4 |
Provide a fast way to find conformance information |
NO | ||
Guideline 14. Provide test assertions. |
||||
14.1 |
Provide test assertions |
NO: You have a test suite, but you don't provide in this document a way to know what is testable. | ||
14.2 |
Provide a mapping between the specification and the test assertions list |
NO: You don't have this list. |
To be AAA-conformant with the guidelines, the following Priority 3 checkpoints must be fulfilled (in addition to the above Priority 1 and Priority 2 checkpoints):
Nbr | Checkpoint | Yes | No | N/A |
---|---|---|---|---|
Guideline 1. Define Scope. |
||||
1.3 |
Provide Usage Scenarios. |
YES: but confusing because it has been noted examples. | ||
Guideline 2. Identify what needs to conform and how. |
||||
2.3 |
Identify which of the categories of object are specified in the document as a whole. |
NO | ||
Guideline 7. Identify the relation between deprecated features and conformance. |
||||
7.4 |
Include an explanation for the deprecation. |
N/A | ||
7.5 |
Include examples to illustrate how to avoid using deprecated features. |
N/A | ||
Guideline 9. Allow extensions or NOT! |
||||
9.4 |
Define a uniform mechanism to create an extension. |
N/A | ||
9.5 |
Require that extensions be published. |
N/A | ||
9.6 |
Require that implementations provide interoperable alternatives to extensions |
N/A | ||
Guideline 11. Specify how to make conformance claims. |
||||
11.2 |
Provide specific wording of the claim. |
N/A: make a conformance section. | ||
11.3 |
Provide a conformance disclaimer. |
N/A: provide a conformance clause | ||
Guideline 12. Publish an Implementation Conformance Statement proforma. |
||||
12.1 |
Provide an Implementation Conformance Statement proforma. |
N/A: because impossible to verify now. | ||
12.2 |
Require the ICS be completed as part of the conformance claim. |
N/A: because impossible to apply now. |