KMIP TC members,
As I mentioned in the announcment of the publication of your CSD/CND drafts, we found several issues that we thought worth passing along for your next editorial rounds. Here is a list & feel free to follow up if you want more detail.
Broken links:
In addition to the references acting as placeholders for more details, we found several to specific resources that are broken. Here are the ones we noted…
* Broken throughout:
Committee Note Draft, 1 December 2011
* In KMIP Spec v1.2:
* In Suite B Profile:
* In KMIP Test Cases Version 1.2:
This reference uses the title of a Committee Note, identifies it as an OASIS Standard and uses a url that doesn't exist. Assuming the CN is what is meant, the correct citation is:
[KMIP-UG] Key Management Interoperability Protocol Usage Guide Version 1.1. 27 July 2012. OASIS Committee Note 01.
* In KMIP Usage Guide v1.2:
Formatting problems
- Paul fixed several vexing formatting problems in the Word doc for KMIP Specification v1.2 csd01. For example, tables in the appendicies ran off the page and in Section 3.22, the figure and caption become separated in the HTML format. Now that they are fixed in that file, you could help us by using a copy of
http://docs.oasis-open.org/kmip/spec/v1.2/csd01/kmip-spec-v1.2-csd01.doc for your next round of editing.
- In the long text message listings that include line numbers, we had problems with the HTML generation. The blank space that Word inserted to space out line numbers to match long strings of wrapping text in the second column was converted into <p class=KMIPXMLCELL> </p> elements in the HTML. However, the text didn't wrap in the second column with the result that you see a lot of white space in the HTML versions. We tried several approaches to fix this but didn't come up with anything that didn't risk introducing other errors to your document.
If anyone has an idea for fixing that, we'd be happy to give it a try. For now though, all we can do is let you know the reason for the extra white space.
- Several of the profile documents have duplicate references to RFC2119.
Computer Language files
Your computer language test cases pose an interesting case for OASIS Rules. To remind you, in section 2.18 of the TC Process, the following requirement is made:
"(7) Computer Language Definitions. All normative computer language definitions that are part of the Work Product, such as XML instances, schemas and Java(TM) code, including fragments of such, must be well formed and valid.
(7a) For Standards Track Work Products:
All normative computer language definitions must be provided in separate plain text files…
Each text file must be referenced from the Work Product; and
Where any definition in these separate files disagrees with the definition found in the specification, the definition in the separate file prevails."
We believe that there would be great benefit to your users to have these files available in separate plain text files to save them from having strip them out themselves (and risk mucking something up when they do) - so you may plan to do this anyway.
From the OASIS rules point of view however, it appears that even though the text says the 'values' are illustrative, the content itself is mandatory / normative. E.g.
"3.1 Mandatory Test Cases KMIP 1.0
This section documents the test cases that a client or server conformant to the Symmetric Key Foundry (FIPS140) Profile SHALL support under KMIP Specification 1.0."
So I ask that you take one of the following steps before going to public review:
a) provide copies in separate text files or
b) change the language of the introductions to make clear that these are non-normative/illustrative examples. For example, you might change the above to say:
"This section illustrates the test cases that a client or server conformant to the Symmetric Key Foundry (FIPS140) Profile needs to support under KMIP Specification 1.0. The test cases are documented in <xxx>"
Those are our observations. Please let us know if you have any questions on any of the above.
--
/chet
----------------
Chet Ensign
Director of Standards Development and TC Administration
OASIS: Advancing open standards for the information society
http://www.oasis-open.orgPrimary: +1 973-996-2298
Mobile: +1 201-341-1393