| DRAFT - Federal XML NDR Comments Matrix | ||||||
| Starting Line # | Relevant Page, Section, or Rule # | Proposed Change | Priority (High, Normal) | Date Submitted | Submitter Name | Accepted change (Y/N) |
| - | XMLNDR EPA XML Design Rules and Conventions from 2003 | I was under the impression that some EPA XML guidance would be added to this site. Since that has yet to happen, I’ve added the 2 EPA documents I had from 2003. If there are more recent versions of EPA guidance, I’d appreciate if they would be added to the Government Standards folder. I’ve also heard of Air Force standards. Does anyone have access to them? | Normal | 2-Jul-2005 | Sall | LMI: We don't believe that this comment requires any change to the NDRG document. |
| - | (See IC Position Paper section 4.1 Define the Adoption Process) | 19-Jul-2005 | ICMWG | LMI: This comment is being addressed outside of the scope of the document. | ||
| - | (See IC Position Paper section 5.1 Propose Guidelines Rather Than Enforce Rules) | 19-Jul-2005 | ICMWG | LMI: The current document draft reflects the decision of the WG that, largely, it represents guidance but that there are some rules that MUST be impemented for inter-agency data exchange. | ||
| All | All | General guidance vs. rules based (change all applicable 'MUST' rules to 'SHOULD') | High | 15-Jun-2005 | Ambur | LMI:
The document has been updated to reflect this comment. (see section
1.4) The document provides |
| All | Overall | Audit entire XDG to ensure that all XSD element and attribute references appear in lowercase since XML is case sensitive. Examples of the problem are sub-section headings 5.1.3.2 to 5.1.3.4. | Normal | 2-Jul-2005 | Sall | LMI: Agreed. The document has been updated to reflect this comment. Greg will confirm that this is completed throughout the doc. |
| All | Overall | The
XDG uses variations of these terms: XML Schema, Schema (u/c), schema (l/c),
XML schema (l/c), and DTD. The variations are not used consistently, nor are
they well-defined. Recommend that the terms be defined on page 1 or perhaps
at the beginning of Section 1.3 (rather than at the end) since this
distinction is at least as important as your notation conventions. schema – model, which doesn’t imply XML at all XML schema – any modeling language written in XML syntax (W3C XML Schema, DTDs, RELAX-NG, etc.); recommend only using this form when you mean generically any XML-based schema language XML Schema – a particular language developed by the W3C used to describe a class of instances that conform to a particular model; also used to mean a given schema written using the W3C XML Schema language. Schema – recommend never using u/c without “XML” in front. Should also mention that the abbreviation “WXS” (for “W3C XML Schema”) is also used (besides “XSD”). |
Normal | 2-Jul-2005 | Sall | LMI: Agreed. The document
has been updated to reflect this comment. (section 1.4) |
| All | XMLNDR Global - inconsistent font conventions | While this may seem minor
in the scope of things, it is so frequent a problem in the XDG that I find it
very distracting. Inconsistency of fonts is something to make readers
conclude that the editors haven’t paid sufficient attention to detail, much
like typos. The use of Courier (fixed width) font should be reserved strictly for code, primarily element and type names and XML excerpts. Please do not use it for emphasis or other terminology. Your conventions state that you are using italics for special terms defined in Appendix A, when not used for title or emphasis. That sounds good; please perform a consistency check. See section 1.3 for your conventions and section 5.1.* for obvious inconsistencies. There are others problems in other sections as well. |
Normal | 2-Jul-2005 | Sall | LMI: Agreed. The document will be updated before final draft review to reflect this comment. |
| 116 | p.1-2 | On page 1-6, footnote 1
points to http://www.xml.gov/working_group.htm. (which no longer exists). It should point to: http://xml.gov/discussion.asp |
Normal | 2-Jul-2005 | Sall | LMI: This footnote is not in the latest draft document. |
| 161 | p.1-8, STR1 | This rule uses "must" - is this too strong? That is, since this is not formal policy, can this document state that agencies *must* adhere to a prescribed hierarchy of standards? I believe such policy (the hierarchy) must be issued by OMB. | Normal | 16-Jun-2005 | Chiusano | LMI: The document has been updated to reflect this comment given that it contains rules and guidelines. Also, different standards will likely propose competing approaches to myriad design issues. If the term MUST is to be used, extensive analysis may be required to identify how, specificaly, these standards are to be used. |
| 161 | STR1 | (See IC Position Paper section 5.12 Voluntary Consensus Standards) | 19-Jul-2005 | ICMWG | LMI: The document has been updated to reflect this comment- with the exception of the change to 'De facto'. Sites such as 'http://en.wikipedia.org/wiki/De_facto' and 'http://www.isoc.org/internet/standards/papers/amr-on-standards.shtml' seem to indicate that there is relevant precedant in the field of law that suggests that the term 'De jure' is appropriate. | |
| 165 | p.1-9, STR1 | Recommend additional explanation for the hierarchy at top of p.1-9. For example, what is a "de jure" VCS? What are "cross-sector" and "sector-specific" VCSs? Examples of each level would also help | Normal | 16-Jun-2005 | Chiusano | LMI: The document has been updated to reflect this comment. We believe the list of VCS examples should be sufficient. |
| 165 | STR1 | I suspect the wording for
STR1 should be: De facto VCS Horizontal VCS Vertical VCS Government-wide standards Agency –specific standards I agree that examples are needed. |
Normal | 1-Jul-2005 | Sall | LMI: The document has been updated to reflect this comment- with the exception of the change to 'De facto'. Sites such as 'http://en.wikipedia.org/wiki/De_facto' and 'http://www.isoc.org/internet/standards/papers/amr-on-standards.shtml' seem to indicate that there is relevant precedant in the field of law that suggests that the term 'De jure' is appropriate. |
| 171 | p.1-9, STR2 and STR3 | Recommend striking these rules, as they are out of scope of naming & design rules. They address policy and operational aspects | Normal | 16-Jun-2005 | Chiusano | LMI: We believe that it is appropriate to leave these 'rules' in the document since they pormote awareness within the XML development community regarding how XML Schema content should be discovered and submitted for candidate reuse. |
| 182 | p.1-9, section 1.4.1 | Recommend striking this entire section, because (a) I don't believe that we should be favoring one standards consortium over another, (b) if there are competing standards within/across consortiums, agencies should have the freedom to select whichever are best for their needs, and (c) STR1's reference to PL 104-113 and OBM A119 should suffice for this aspect. | Normal | 16-Jun-2005 | Chiusano | LMI: We'd like to discuss this with the commenter. |
| 197 | p.1-9, STA1 | I believe that this rule really means to say "all schemas must be based on W3C Schema" (as opposed to RELAX NG, for example). To say that "all schema design rules must..." does not make sense, unless we intend that agencies will be writing their own schema design rules (in which case they would not need this document). | Normal | 16-Jun-2005 | Chiusano | LMI: The reference to design rules has been removed. Joe writes: ''in which case they would not need this document'. Is this true ? Isn't this document meant to serve as a guideline with which agencies may choose to create their own NDRs ? |
| 203 | p.1-10, STA2 | Not sure what we mean by "and messages". Do we mean to say that any messages exchanged between agencies must be based on...(see rule for rest)? Also, to say "all schema must be based on..." is redundant, as that was stated in STA1. | Normal | 16-Jun-2005 | Chiusano | LMI: The document has been updated to remove the 'and messages' reference. It's purpose is unclear and extraneous. |
| 203 | [STA2] | All schema and messages SHOULD be based on the W3C suite of technical specifications holding recommendation status. Applications SHOULD NOT implement W3C technical reports at other stages of the development process, or other draft products of Voluntary Consensus Standards bodies. In particular, applications SHOULD NOT implement or rely on W3C notes or other draft documents from other organizations. | Normal | 23-Jun-2005 | Vincent | LMI: Please clarify this comment. |
| 203 | [STA2] | [I would strike the rest of this section.] | Normal | 23-Jun-2005 | Vincent | LMI: We believe this content does not distract from the purpose and scope of the document. |
| 203 | STA2 | “All schema and messages”
being based on W3C suite seems to prohibit the use of many other VCS
standards (e.g., those from OASIS). For example, if taken literally, it would
disallow using UBL or CCTS (even though *they* are based on W3C specs). “recommendation status” is certainly highly desirable, but the text in Sec. 1.4.1 is far too restrictive to be adopted government-wide. If an agency has a need to use XQuery, for example, which has been one or more Working Drafts for over 5 years, they will use it. IMO, the real point to be made is that if there are 2 competing specs and one is more mature than the other and/or by a more widely accepted source, than that should influence the choice. But even then, some critical feature of the less mature spec could override the maturity argument. |
Normal | 2-Jul-2005 | Sall | LMI: We believe that any
XML specification development MUST be done in accordance with the W3C rules
of that language. We assume that a literal interpretation will not be
understood here. Also, CCTS is not based on any XML standard. Any
specifications that extends the W3C XML Schema Recommendation may be used but
they MUST adhere to W3C XML Schema. The term 'based on' has been replaced with 'conformant to'. Also, we believe that this document MUST not promote use of specifications that are not yet recommended by their respective datdnards organization. If agencies choose to adopt these technologies, they may certainly do so at their own risk, but we believe this document should discourage that practice. To what line does section 1.4.1 refer ? |
| 203 | STA2 | (See IC Position Paper section 5.13 Permit Specifications that are Not Quite Recommendations) | 19-Jul-2005 | ICMWG | ||
| 208 | p.1-10, STA2 | text under rule: Recommend striking all of this text (under "Production Applications"), for reasons stated earlier (should not favor a single standards consortium, already covered the general concepts in STR1, etc.). | Normal | 16-Jun-2005 | Chiusano | LMI: We believe this content does not distract from the purpose and scope of the document. |
| 231 | All software and software components (XML parsers, generators, validators, enabled applications, servers, databases, operating systems), and other software acquired or used by Agencies SHALL be fully compliant with all W3C XML technical specifications holding final recommendation status and with final specifications produced by accredited standards bodies. (This should be deleted. In fact, no two parsers operate the same way. There is no accreditation or certification system to test whether a parser, etc. is “fully compliant.”) This rule is not realistic and even if it were, could not be verified. | Normal | 23-Jun-2005 | Vincent | LMI: Agreed. The document has been updated to reflect this comment. | |
| 240 | p.1-11, STA3 | Recommend changing this to state that users should defer to the conformance clause of each specification/standard, and making it general (not W3C-specific). As written, the rule may prevent business needs of agencies from being carried out, as these needs may be sometimes be satisfied with proprietary (agency-specific) extensions. | Normal | 16-Jun-2005 | Chiusano | LMI: We think this rule should stand but shold be clarified to state that no attempt be made to modify the XML Schema language per se. We agree that a reference to conformance/compliance/certification clause should be included and the document has been updated accordingly.. |
| 240 | [STA3] | Proprietary extensions to the W3C specifications MAY be used, but SHOULD BE USED with caution.. | Normal | 23-Jun-2005 | Vincent | LMI: If this refers to attempted modifications to the core XML Schema specification, we disagree. |
| 247 | p.1-11, section 1.5.1 | Recommend striking this
section, as most/all of the principles are so general that they cannot be
easily adhered to, and instead representing them as part of rules. Some are
also not clear. Examples: - Item #1 (Internet Use): What does
"straightforwardly usable" mean? Very broad term that is so
subjective that it would be difficult to find a case in which an
implementation was not "straightforwardly usable".- Item #3
(Legibility): "human-readable and reasonably clear" - very
subjective.- Item #4 (Simplicity): "as simple as possible" - very
subjective.- Item #5 (Component Reuse): "common features" - what
does this mean?- Item #6 (Standardization): "kept as close to one as
possible" - in what scope? Within an agency? Across the federal
government?- Item #7 (Customization and Maintenance): "must facilitate
customization and maintenance" - how does a schema accomplish this?-
Item #8 (Prescriptiveness): What does "prescriptiveness" mean here?
What are "precise, tight" content models ? - Item #9 (XML
Technology): Already covered earlier in document, in discussions on
standards.- Item #10 (Legacy formats): Define "legacy". |
Normal | 16-Jun-2005 | Chiusano | LMI: Some of these changes have been made. |
| 247 | 1.5.1 | Regarding Section 1.5.1, I
agree with Joe. The wording in this section is far too vague to be really
useful. For example, SVG is a W3C REC, but how “human readable” is it? There
is plenty of geospatial data wrapped in XML that may not be very “legible”. So
what? If the processing software can interpret XML and do something with it
(render it, filter it, stuff it in a database), that’s far more
important. “Simplicity” – This statement is extremely subjective and not measurable. “Standardization” – Expressing the same information in one way government-wide is a lofty goal, but leave this to NIEM, not to this XDG. How can a developer” make operation sense out of this? “Legacy formats” – This wording is bound to inflame anyone on the fence about moving to XML in the first place. Nearly every agency in the government *does* have to worry about legacy formats. To dismiss This whole section should be removed; at a minimum, it requires a significant re-write with more detail. I believe it is based on similar wording from a draft CCTS Users Guide. |
Normal | 2-Jul-2005 | Sall | LMI: Some of these changes have been made. |
| 276 | p.1-12, section 1.5.2 | Recommend turning this section into rules. It is quite verbose, and doesn't even really arrive at the central point until the third paragraph. | Normal | 16-Jun-2005 | Chiusano | LMI: Please provide the line number for the last document draft. |
| 276 | p.1-12, section 1.5.2 | Prescriptiveness – Federal schema design will balance prescriptiveness in any single usage scenario with prescriptiveness across the breadth of usage scenarios supported. Having precise, tight content models and Datatypes for schemas that represent data formats is a good thing. (I do not think this document does or should describe rules for XML document formats. This having been said, document formats need loose, flexible schemas with mixed content. So, it is important to associate tight content models and data types with data formats. Otherwise, there will be misunderstanding.) | Normal | 23-Jun-2005 | Vincent | LMI: We need to better understand the suggested change of this comment. |
| 297 | p.1-13, top | If this section is kept, recommend removing the reference to CCTS (for context). I believe that this document should not be tightly bound to any single data modeling methodology, including CCTS. | Normal | 16-Jun-2005 | Chiusano | LMI: What is the line number of this reference in the latest document draft ? |
| 302 | b | Recommend defining "data-centric" and "document-centric". For an example, see the EPA XML Design Rules document. | Normal | 16-Jun-2005 | Chiusano | LMI: This work is underway. |
| 302 | 1.5.3 | I agree with Joe that in
Section 1.5.3, you need to define “document-centric” and “data-centric”
(probably with an example). Also agree that your assertion about XSD vs. DTD
use cannot be validated. It would be far more useful in this section to point out specific advantages of XSD over DTD to motivate developers to pick the former over the latter, such as: - strong data typing with 44- built-in types - flexible constraint mechanism via “facets” including regular expressions - derivation by restriction and extension - uses XML syntax - precise control over multiplicity via minOccurs and maxOccurs (.e.g., can specify element repeats from 7 to 12 times) - namespaces - etc. |
Normal | 2-Jul-2005 | Sall | LMI: Please provide the document line-number from the latest draft. |
| 306 | p.1-13, section 1.5.3 | Recommend striking the assertion that data-centric approaches now outnumber document-centric approaches, for the following reasons: (a) it's not relevant, as XML will be used for both approaches regardness of which is more "popular", and (b) there is nothing provided to support the assertion. | Normal | 16-Jun-2005 | Chiusano | LMI: Agreed. The document has been updated to reflect this comment. |
| 311 | p.1-13, section 1.5.4 | Recommend striking this, or making it a rule. The last sentence was also covered earlier in the discussions around standards. | Normal | 16-Jun-2005 | Chiusano | LMI: Please clarify the line number or section in the latest draft of the document. |
| 311 | p.1-13 | This section is confusing to me. We distinguish between “Code generation” and “schema generation.” Schema generation is generating XSDs from some information source. Code generation is generating code (e.g., VB or VB.NET) from XSDs (also called “data binding” if you do an Internet search.) The title says “code generation” but the first sentence describes “schema generation.” In principle, I agree that these rules should not favor one product over another product for either code generation or schema generation. However, these rules should be designed to facilitate (vendor-neutral) schema generation and code generation. XML schemas are useful because they are XML – which means that you can very easily use the XML for schema generation and code generation. The corresponding disadvantage is a performance hit. If the rules do not leverage the XML characteristics of XML Schemas, then you may as well use DTDs. | Normal | 23-Jun-2005 | Vincent | LMI: Please provide the document line-number from the latest draft. |
| 321 | CHAPTER 2 COMMENTS | Recommend striking entire chapter, as it belongs in a data modeling manual not an NDR document. | Normal | 16-Jun-2005 | Chiusano | LMI: It seems important to provide the federal XML audience with the context from which XML Schemas are to be developed. It seems appropriate to cite such modeling systems as UML since that is a prevalent, gobal method for modeling information. Readers need to understand how their syntax-neutral information models will be translated into XML Schema data models. |
| 321 | Chapter 2 | I would move this to an appendix. I do not necessarily think you should strike it | Normal | 23-Jun-2005 | Vincent | LMI: We believe this section has direct applicability to the context from which XML developers are going to approach this document. |
| 321 | Section 2 | Section 2 does not provide
enough information for someone who doesn’t know much about UML modeling and
is far too obvious to anyone who already is familiar with it. Therefore,
either go into much more detail with a complete example (including XSD) or
refer readers to a number of good books and other resources about modeling,
such as the OMG site and UML Distilled: A Brief Guide to the Standard Object Modeling Language, Third Edition by Martin Fowler |
Normal | 2-Jul-2005 | Sall | LMI: Agreed. This document should more clearly state how UML models can be translated into XML Schema models. |
| 326 | Section 2-1 | I recognize that this
section does not prohibit a one-object-one-schema approach. However, does not make it clear that there
are alternatives. I think this section
should make clear that there are three alternatives: - One schema, one
namespace – all objects - Modular schemas, but many objects to one schema. (one or several namespaces per object) - Modular schemas, but one object to one schema. (one namespace per object/schema) |
Normal | 23-Jun-2005 | Vincent | LMI: This is possible, but we consider it a low priority. |
| 346 | Section 2-2 | It would be good to have XSD examples to show a “complex data element” and “simple data element”. Although I have a general idea of what you mean, I can think of several XSD constructs that might be considerd “complex data elements” and “simple data elements.” Examples would help clarify this. | Normal | 23-Jun-2005 | Vincent | |
| 379 | General: | Most rules in this chapter are missing explanations/justifications (I know that's obvious, just emphasizing it). | Normal | 16-Jun-2005 | Chiusano | LMI: OK |
| 382 | XMLNDR Section 3.1, GXS1, ELD1 | In Section 3.1, the second
sentence is an example of the “schema” vs. “Schema” confusion mentioned in an
earlier email. In GSX1, the Copyright Notice appears twice (beginning and end). The terms “CommonComplexElements: and “CommonSimpleElements” are never explained in this section. While I can imagine what this means from the UBL NDR base for which this document is derived, further clarification is needed. This section clearly needs an example, preferably one that can be used to support the other rules that follow. In 3.1.1, the repeated word “will” seems out of place. Suggest replacing “will” with SHOULD or MUST, as appropriate. In ELD1, the term “Schema expression” is used but never defined. I cannot find this terminology in W3C XSD Part 1 or 2, which is your only stated source. |
Normal | 2-Jul-2005 | Sall | LMI: The 2nd copyright
notice has ben removed. LMI: This work is underway. LMI: We will remove references to 'Schema expression' |
| 384 | p.3-1, GXS1 | This diagram is not very
clear, and it can be better organized. Some suggestions: Use bulleted lists
- Provide an example of each item (Target namespace, etc.). Perhaps it is best to have a single example that represents the entire box (i.e. with a targetNamespace declaration, etc.) with the various items labeled. |
Normal | 16-Jun-2005 | Chiusano | LMI: Please clarify during comment review. |
| 384 | [GXS1] | It is not useful to put any
of this information in unparsable comments <!-- and à. This information
should be in XML xsd:annotations in XML elements in a different namespace
(e.g, the drm namespace).The first child of the <xsd:schema element should
be xsd:import/xsd:include. I prefer
the following order:
xsd:import/xsd:include xsd:complexType xsd:simpleType xsd:element xsd:group xsd:attribute |
Normal | 23-Jun-2005 | Vincent | |
| 384 | XMLNDR GXS1 | Sorry. Forgot to mention
that GXS1 use of “MUST” and “as applicable” is confusing. For example, why do government-developed
schema has a “Copyright Notice”?
(stated as “applicable” at beginning and “required” at the end. If the
intention is notices about using specs developed by others, make this
clear. Who decides what is “applicable” in GXS1? The agency? The developer? |
Normal | 2-Jul-2005 | Sall | LMI: Agreed. Unless there is any clear reason to include a copyright notice, it should be removed. The term MUST has been changed to SHOULD. |
| 426 | p.3-2 | I would not strike the existing rule, but I would add an additional rule that makes it useful to applications. This is also something that NIST (or others) can test programtically. | Normal | 23-Jun-2005 | Vincent | LMI: What rule ? |
| 431 | p.3-2, section 3.1.1 | Recommend removing the discussion of application space handling, as it clouds the issue. The bottom line is that we want to be able to unambiguously identify in a schema what we intend to be the root element for XML instances that conform to that schema. Period. | Normal | 16-Jun-2005 | Chiusano | LMI: Agreed. The relevance of application space handling to the topic at hand is a bit unclear. The doicument has been updated to reflect this comment. |
| 448 | XMLNDR Section 3.2 | NMC1 - I believe Joe raised
this, but “dictionary entry name” and “fully qualified path” need to be
explained by definition and example. MDC1 – What is a “library” in this context? Where exactly are the “approved datatypes”? Since this isn’t UBL or CCTS that we are really talking about, this rule makes little sense to me. You certainly don’t mean the 44 built-in datatypes in XSD. MDC2 – Suggest you define “mixed content”. Even though this is standard XML/SGML nomenclature, not all techies know it. GENERAL – IMO, wherever a “MUST” is stated in a rule, a strong justification needs to be given. Essentially, you are limiting the flexibility of the XSD language and as a developer, I will always want to know why. |
Normal | 2-Jul-2005 | Sall | LMI: NMC1 - The document has been modified to reflect this comment. MDC1 - The document has been modified to reflect this comment. MDC2 - The document has been modified to reflect this comment. GENERAL - Agreed. |
| 450 | p.3-3, NMC1 | As a reader, I am saying to myself "What is a dictionary entry name?" and "What is a FQP"? Recommend moving this rule to after these concepts are discussed (assuming they are discussed later), or discuss them here. | Normal | 16-Jun-2005 | Chiusano | LMI: see previous comment |
| 450 | [NMC1] | It is unclear what you mean by “disctionary entry”. It is unclear what you mean by “fully qualified path”. | Normal | 23-Jun-2005 | Vincent | LMI: see previous comment |
| 454 | p.3-3, NMC2 | Recommend striking this rule. It is policy/governance, which is out of scope of NDR. Also not sure what is meant by "libraries" here (a moot point if rule is struck). | Normal | 16-Jun-2005 | Chiusano | LMI: This rule has been removed. |
| 454 | [MDC1] | It is unclear what you mean by “approved data types.” Are these W3C XML Schema xsd data types or some other data types. Does this prohibit the use of simpleTypes? Who is the approval authority? | Normal | 23-Jun-2005 | Vincent | LMI: The document has been modified to better explain what is meant by approved data types. |
| 456 | [MDC2] | Mixed content SHOULD NOT (should avoid) be used in data centric schema except where contained in an xsd:documentation element | Normal | 23-Jun-2005 | Vincent | LMI: Please clarify this comment. |
| 456 | MDC2 | (See IC Position Paper section 5.2 Allow for Possibility of Mixed Content) | 19-Jul-2005 | ICMWG | ||
| 460 | [ELD2] | I would strike the reference to document-centric schemas for the following reason (a) I do not think this document is about document-centric schemas and (b) in our work, we have never seen a need for an exception to the global element rule. All elements and complex types should be declared globally – period. There should not be any exceptions. If there are exceptions, this greatly complicates processing based on the rules | Normal | 23-Jun-2005 | Vincent | LMI: The document has been modified to renove all references to documen-centric (with the exception of those stating that document-centric rule/guidelines are out of scope) |
| 466 | p.3-3, NMS1 | As a reader, I am saying to myself "What is an internal schema module?". | Normal | 16-Jun-2005 | Chiusano | LMI: Agreed. The initial reference to this term requires sufficient description. |
| 466 | [NMS1] | This having been said, it is not clear to me what you mean by “internal schema modules”. | Normal | 23-Jun-2005 | Vincent | LMI: The document should now provide a sufficiently clear description of the term internal. |
| 466 | XMLNDR Section 3.4 - Namespaces (URN vs. URL) | I agree with all Joe’s
questions and suggestions regarding the NMS1-4 rules. The removal of
UBL-centric terminology is essential in this document, or else you must
clearly define each term you’ve leveraged. If you drop into the first person, use “Editor’s Note” or some such notation or possibly your initials. I remain unconvinced that URNs should be required over URLs for several reasons: If existing applications use URLs, then to change to URNs breaks rule NMS7 about URI persistence. Many agencies would rather have easily resolvable URIs than permanent ones. Where is it described exactly how an agency can get its URNs formally assigned and registered? If it’s the paper you mention, give complete reference with a URL (or URN ;-). In my experience, far more schemas use URLs than URNs. This means insisting on URNs will impact numerous applications. Is it worth the cost? URI SUGGESTION: Offer 2 parallel naming conventions (e.g., your 8 level descriptions), one illustrated with URNs and the other with URLs. Indicate the pros and cons of both. Then “recommend” the use of one over the other (if you must), but please strike SHOULD or MUST with regard to this choice. It is simply not going to be followed government-wide since it’s nearly a religious issue |
Normal | 2-Jul-2005 | Sall | LMI: In regards to
"Where is it described exactly how an agency can get its URNs formally
assigned and registered?"… this is out of the scope of this document and
should be added to the scope of the document associated with this NDRG that
deals with governance and registry concerns. Additional text has been added to the document that outlines, objectively the criteria against which URL's and URN's should be compared. Recommendations are made accordingly. |
| 469 | p.3-4, NMS2 | As a reader, I am saying to myself "What is a schema set version?". | Normal | 16-Jun-2005 | Chiusano | LMI: This rule has been reworded slightly and explanatory text has been added. |
| 469 | [NMS2] | Again, this rule, which you say “schema set” appears to favor the second model. | Normal | 23-Jun-2005 | Vincent | LMI: Please clarify this comment. It is unclear what is meant by "the second model" |
| 472 | p.3-4, NMS3 | As a reader, I am saying to myself "What is a Federal Namespace?". Also, what constitutes a "federally developed" schema module? If it was developed by a federal employee? | Normal | 16-Jun-2005 | Chiusano | LMI: The document has been updated |
| 472 | [NMS3] | It is unclear why there is this restriction. I would agree that schema modules should only contain schema modules based on the same NDR. However, if a private vendor were to develop schemas based on an NDR, then I see no reason why the federal government could not use those schemas. | Normal | 23-Jun-2005 | Vincent | |
| 475 | p.3-4, NMS4 | As a reader, I am saying to myself "What is a published namespace?" IOW, what makes a namespace "published" or "non-published"? However, in general, I would recommend striking this rule because (a) it is extremely restrictive (use of "never"), (b) what if an agency is absorbed into another agency and their namespace identifier needs to change? (c) most importantly, it should be part of a data management strategy. | Normal | 16-Jun-2005 | Chiusano | |
| 475 | XMLNDR NMS7 | Appears twice | Normal | 2-Jul-2005 | Sall | LMI: The duplicate rule has been removed. |
| 477 | pg. 3-4 | I do not think there is consensus on this rule. I would recommend a rule that allows URIs provided that: A URI used as a namespace SHOULD point to a file or directory that contains the schema. If the URI points to a directory, the directory should contain documentation and the schema.The namespace or some other information available to an application should allow the application to discover the location of the schema and its documentation in the directory. The URI location(s) should not be changed for the same version of the schema.Imported schemas should be located in directories relative to the primary schema that match xsd:import and xsd:include statements in the primary schemas. Relative paths should be used, as opposed to hard coded paths, in xsd:include and xsd:import statements | Normal | 23-Jun-2005 | Vincent | LMI: The document has been updated to outline discreet criteria against which the URN and URL namespace options can be measured. Reference is made to the documentation issue you cite (in addition to RDDL). |
| 478 | p.3-4, section 2.4.2 | All of a sudden, we have an "I" here ("I recommend" - with "recommend" mispelled). Who is this "I"? Should be more general ("It is recommended that..."). Also, we jump into the notion of URNs (the solution) here without even stating the problem! | Normal | 16-Jun-2005 | Chiusano | LMI: This does not appear to be in the latest draft of the document. Please confirm. |
| 505 | p.3-5, section 2.4.3 | This is a duplicate of the rule I referred to in #9 above | Normal | 16-Jun-2005 | Chiusano | |
| 508 | p.3-5, section 3.5 | Recommend striking this section. Versioning should be addressed in a data management strategy. | Normal | 16-Jun-2005 | Chiusano | |
| 508 | XMLNDR Section 3.5 - Versioning | While a versioning scheme
made sense for UBL because it is an effort developed by a focused technical
committee, it is hard to believe we can impose a versioning scheme that will
be acceptable government-wide. Some program requirements (from RFPs, etc.) mandate
their own versioning scheme. To follow one we suggest could mean not
complying with program requirements. Recommend recasting this section in terms of “recommendations” or “suggestions” and striking use of MUST or SHOULD |
Normal | 2-Jul-2005 | Sall | LMI: We recommend that the
government move toward a common approach regarding versioning of XML Schema
vocabularies. The versioning strategy will have a direct impact on the manner
in which a common federal vocabulary is used, and therefore will impact its
usefullness. The group may want to consider a no-namespace strategy for common federal Schemas so that they can be used easily within agency-specific situations. |
| 508 | VER*, VER8 | (See IC Position Paper section 5.3 Versioning Scheme is Not Well Defined) | 19-Jul-2005 | ICMWG | ||
| 510 | pg. 3-5 | As I have stated in email posts, I would avoid using the document-id for version control and would rely, instead, on the namespace. | Normal | 23-Jun-2005 | Vincent | [8/11] Apply URN/URL decision from namespaces and make the rule "SHOULD" |
| 514 | [VER3] | I would not allow a minor version change (any version change) without a change in the namespace. | Normal | 23-Jun-2005 | Vincent | LMI: We disagree and believe that inclusion of minor versions in the targetNamespace is problematic since backwards compatibility will be broken with each minor version rev. |
| 550 | XMLNDR Section 3.6 Modularity | This whole section needs a
significant re-write (expansion) with appropriate motivation and scoping,
definitions of all terms used, clear explanation of the diagram. Once again,
terminology from CCTS and UBL is incorporated without explanation. Since the intention of the diagram seems to be to show what is dependent on what and what the multiplicities are, be clear about these relationships. Example: “The diagram shows that a Fed Complex Data El Schema Mod consists of exactly one Fed Simple Data El Schema Mod, one Fed Qualified DataTypes Schema Mod, and one Fed Unqualified DataTypes Schema Module. The Fed Unqualified DataTypes Schema Module, in turn, is based Source Standards….” Please include XSD examples of each of the types of “modules” referenced in the diagram and show how they are imported or included. |
Normal | 2-Jul-2005 | Sall | [8/11] Expand section description of diagram. Ensure all terms and concepts are fully explained. Inquire about providing Spectrum as an example. |
| 550 | 3.6, SSM16 to SSM22 | (See IC Position Paper section 5.10 Modularity Section Needs Concrete Examples) | 19-Jul-2005 | ICMWG | [8/11] Build on other comment for line 550 by Ken Sall, by breaking up figure into three diagrams. | |
| 564 | p.3-8, Figure 3-1 | Recommend simplifying this diagram, else no one will read/comprehend it. | Normal | 16-Jun-2005 | Chiusano | [8/11] Breakup figure into three diagrams. |
| 564 | Figure 3-1 | I do not understand this diagram | Normal | 23-Jun-2005 | Vincent | [8/11] Breakup figure into three diagrams. |
| 567 | p.3-8, section 3.6.1 | This paragraph is very vague - I kept wondering why I was reading it (i.e. what is the significance). We may also consider striking it, since the discussion of VCSs was already covered in the Introduction. | Normal | 16-Jun-2005 | Chiusano | [8/11] Re-write section. Follow from ATG descriptions of the various types. Simplify model. |
| 578 | p.3-9, SSM1 | What is a "root schema expression"? Schemas don't have expressions (XSLT stylesheets do). | Normal | 16-Jun-2005 | Chiusano | Remove word "expressions". |
| 578 | [SSM1] | Again, this indicates the second model, not the first or the third. | Normal | 23-Jun-2005 | Vincent | No change |
| 578 | XMLNDR Section 3.6.2 - Schema Modules SSM1-to SSM15 | The lack of explanation of
terminology makes rules SSM1-15 hard to evaluate. SSM8 – Who is constructing the “Federal Common Complex Data Elements” and where does it reside? If I am a developer in the Dept. of Redundancy Department, why is this a rule for me? Won’t I simply be leveraging this “module”? If so, how do I reference it? SSM9 – This rule introduces what appears to be a namespace prefix “fed:” with no explanation or mapping to a URI. And back in the namespace rules section, the only URIs were of the (rough) form “urn:us”, so this is confusing. SSM9-15 – Please be consistent in all naming conventions. Some of these contain spaces and some do not. What are you really trying to accomplish by these naming conventions anyway? |
Normal | 2-Jul-2005 | Sall | [8/11] Address as done for comment 76. SSM8 define that a registry will exist. SSM9 place a pointer in the document that explains what the prefixes are. Revisit the names of each of the Federal schema modual and see if we can leverage the NIEM Universal core terms. |
| 580 | p.3-9, SSM2 | What is a "root schema"? And how can a root schema be "dependent upon" type definitions or element declarations defined in another namespace? It can *include* or *import* these (perhaps that is what was meant). | Normal | 16-Jun-2005 | Chiusano | [8/11] SSM2 replaces "is dependent upon" with "uses". Clarify the "that" from the part of SSM2, "...root schema modules from that namespace." Explain relationship between root schema and imported schemas. |
| 584 | p.3-9, SSM3 | Continuing along the same lines, did not understand this rule because the base concepts (e.g. internal schema module) have not been explained (apologies if I missed them). | Normal | 16-Jun-2005 | Chiusano | LMI: We believe this rule should be removed unless the group can provide justifcation for the inclusion (or import) of one root Schema into another root Schema. That is, assuming root Schemas follow a Request/Response model, then when would it make sense to include one RQ or RS into another RQ or RS ? |
| 588 | p.3-9, SSM4 | Since I believe we are saying (or intend) that all agency schemas will be conformant with these rules, this rule seems moot. | Normal | 16-Jun-2005 | Chiusano | LMI: We agree that this rul
seems extraneous, but to what extent is it true that all agency Schemas will
be conformant with this NDRG. Other comments submitted herein state otherwise
(regarding versioning, etc). We have removed this rule. |
| 588 | SSM4 | (See IC Position Paper section 5.4 Permit Non-Conformant Imports) | 19-Jul-2005 | ICMWG | ||
| 591 | p.3-9, SSM5 | Continuing along the same lines, did not understand this rule. | Normal | 16-Jun-2005 | Chiusano | LMI: This rule simply states that, from the perspective fo a root XML Schema, all other XML Schemas fall into 1 of 2 categories: internal OR external. |
| 591 | [SSM5] | An example would be helpful. It is unclear what you meant by “external schema modules” and “internal schema modules”. | Normal | 23-Jun-2005 | Vincent | LMI:
Figure 3-1 provides a visual depiction of how internal and external XML
Schemas are to be referenced from the root Schema. In support of your comment, we have added a textual reference to that figure. Also, explanatory text has been added. |
| 595 | p.3-9, SSM6 | Continuing along the same lines, did not understand this rule. | Normal | 16-Jun-2005 | Chiusano | LMI: This rule is meant simply to state that each internal XML Schema should be defined in the same namespace as the root Schema that needs to use its content. |
| 598 | p.3-9, SSM7 | Continuing along the same lines, did not understand this rule (etc. for rest of SSMx rules). | Normal | 16-Jun-2005 | Chiusano | LMI: We'd like to discuss this with the commenter. |
| 598 | [SSM7] | An example would be helpful. | Normal | 23-Jun-2005 | Vincent | LMI: Agreed. We have added an example to clarify. |
| 603 | p.3-10, SSM8 | What constitutes federal "common" complex data elements? Common within what scope? Across the entire federal government? Within a single agency? etc. | Normal | 16-Jun-2005 | Chiusano | LMI: An explanation has been added to the document. These elements pertain to a the federal government as a whole. |
| 606 | p.3-10, SSM9 | Is there really a need for us to require what schemas are named? Also, it seems odd to have a name of a schema that begins with a namespace prefix ID (fed:). | Normal | 16-Jun-2005 | Chiusano | LMI: We believe that a
consistent naming convention will promote simplicity for XML Schema
development as a whole. Regarding the namespace prefic, we are open to suggestions. Assuming a consistent naming convention, it will be necessary to denote somehow the domain to which an XML Schema applies. |
| 606 | [SSM9] | This implies one large schema that will be imported into every other schema. This will lead to performance problems and also version control problems (i.e, the contract analogy above.) | Normal | 23-Jun-2005 | Vincent | LMI: This comment may be
referring to the wrong rule. Please clarify. Is this rule referring to minor versioning imports ? |
| 610 | p.3-10, SSM10 | At this point, I started thinking: Is there really a need for us to require how agencies modularize their schemas? IOW, does it matter if their common simple data elements are in 1 schema, or spread out amongst 3? Isn't it the individual components (e.g. data type definitions) that matter for interagency sharing, not how they are packaged? | Normal | 16-Jun-2005 | Chiusano | LMI: The modularity design of federal XML Schemas will have a direct impact on versioning strategy and namespace design. As such, we believe that a thoughtful, consistent approach to this problem throughout the government is in everyone's interest. |
| 610 | [SSM10] | See comment above. XSD is not suitable for managing this type of information. Using XSD implies that you will use the schema for validation. However, if there is a library of 100 simple data elements and an application only needs 2, there is no reason to import the other 98. | Normal | 23-Jun-2005 | Vincent | LMI: We'd like to discuss
this with the commenter to better understand why the import is unnecessary.
We would agree that an include would be inefficient. |
| 617 | [SSM12] | See comment above. XSD is not suitable for managing this type of information. Using XSD implies that you will use the schema for validation. However, if there is a library of 100 simple data elements and an application only needs 2, there is no reason to import the other 98. | Normal | 23-Jun-2005 | Vincent | (see above) LMI: We'd like to discuss this with the commenter to better understand why the import is unnecessary. We would agree that an include would be inefficient. |
| 623 | [SSM14] | See comment above. XSD is not suitable for managing this type of information. Using XSD implies that you will use the schema for validation. However, if there is a library of 100 simple data elements and an application only needs 2, there is no reason to import the other 98. | Normal | 23-Jun-2005 | Vincent | (see above) LMI: We'd like to discuss this with the commenter to better understand why the import is unnecessary. We would agree that an include would be inefficient. |
| 628 | Comments on federal modules apply to agency modules | Normal | 23-Jun-2005 | Vincent | ||
| 628 | XMLNDR Section 3.6.4 - SSM16 to SSM22 | The whole modularity
discussion in 3.6.* may seem like the right idea on the intuitive level, but
it is so hard to see how it will work without a concrete, well-thought-out
example. For example, using the old UBL/CCTS Address complexType, how would
this be defined as a Federal object, how would it be imported, how could an
Agency modify it at the Agency level and then how could someone else modify
it at a lower level? Will the Federal level Address allow for military bases
that aren’t US states? Or is that up
to DoD to do by extending the Federal Address? SSM18 introduces <agencyToken> and <AgencyName> again without explanation or example. Is the token a namespace prefix? Is it an abbreviation for the agency? If so, what is the authoritative source of the agency acronyms? How is the AgencyName constructed? Is DOI “DeptOfInterior” “DepartmentOfInterior”, “Interior”, or what? How will we guarantee that everyone in the same agency uses the same agencyToken and AgencyName, or is that not the intention? Please don’t say that FIPS 95-2 is your source; it’s been withdrawn. |
Normal | 2-Jul-2005 | Sall | |
| 641 | [SSM16] | “Reusable” is confusing. When you say “reusable” it is unclear whether this means reusable using xsd:import and xsd:include or whether you mean “cut and paste”. Xsd:import and xsd:include are not good because of performance. Cut and past is only OK if you change the namespace (i.e., the contract analogy). | Normal | 23-Jun-2005 | Vincent | LMI: The document has been modified to explain that reusable does not mean cut and paste. Rather, the content is there for those XML Schemas that need to import it. From the perspective of a validating parser, imports do not incur the same performance lag as includes. |
| 676 | XMLNDR Section 3.6.5 - abbreviations and agencyid (vs. agencyToken) | Section
3.6.5 introduces what appear to be XDG-specific abbreviations such as “ccd”,
“csd”, “udt”, and “qdt”. These should be called out in a table for easy
reference. Section 3.6.5 also uses “agencyid” whereas the previous section uses “agencyToken”. How are these IDs and strings established? While FIPS 95-2 would seem appropriate to identify agencies, that standard was withdrawn in February 2005. |
Normal | 2-Jul-2005 | Sall | |
| 712 | p.3-13, section 3.7.1 | Recommend providing more context around the mention of xsd:appInfo. | Normal | 16-Jun-2005 | Chiusano | |
| 712 | XMLNDR GXS12 - appinfo and risks | If the XDG intends to
discuss risks in XML, it should include a special section on that, which
actually would be a good idea. Note that xsd:appinfo is only one of many
aspects. See a presentation on “XML Threat Prevnation” given to the XML
CoP. http://xml.gov/presentations/sarvega/xmlattacks.ppt I recommend changing MUST to SHOULD and adding words about taking security concerns into account, such as in a controlled environment. There are secure networks out there. |
Normal | 2-Jul-2005 | Sall | |
| 716 | GXS12 | (See IC Position Paper section 5.6 Permit xsd:appinfo) | 19-Jul-2005 | ICMWG | ||
| 719 | p.3-14, GXS2 | Recommend striking this rule, as the existence of duplicate schemas may lead to inconsistencies that whose disadvantages outweigh any perceived advantages from using this approach. Agencies can do this if they want to, but it should be at their own risk. | Normal | 16-Jun-2005 | Chiusano | LMI: We believe that the best approach to this is to provide a simple XSLT script that removes all annotations from an XML Schema. |
| 719 | XMLNDR Section 3.7.2 - DOC rules | I agree with Joe’s
comments. As written, these DOC rules seem to come from left field. There is
no motivation given and if it were, it would be CCTS-centric, which is not
appropriate for the XDG, as I understand its current focus. IMO, a more practical set of documentation rules should center on what a typical Data Element Dictionary contains and should use similar, familiar terminology. For example: - element name (DEN) - definition - datatype (XSD built-in or name of complexType) - obligation (optional, required, or conditional) - repeatability (maximum number of repetitions of element) - default value, if any - minimum and/or maximal value, if any - other constraints (e.g., format, although that should fall out from the datatype) - business logic, if any - etc. The wording should reflect that documentation MUST be present, but the exact contents SHOULD be controlled by contractual requirements. WISH LIST: To foster creation of this documentation, it would be wonderful if the XDG included a tool that could convert an Excel spreadsheet to an XSD template filled-in with the documentation from the spreadsheet |
Normal | 2-Jul-2005 | Sall | LMI: While we agree with
this comment, it is critical that a common consensus be reached by all
stakeholders regarding the inclusion of concepts such as 'Qualified
datatype', etc that this comment seems to be pushing against. Regarding the tool to convert xls to Schema... this would be useful for many organizations in addition to the federal space. |
| 719 | XMLNDR Section 3.7.2 - GXS2 - fully annotated vs. run-time schemas | If we insist on 2 versions of each schema (one for run-time without xsd:documentation), we should provide the XSLT that strips the documentation. The attached XSLT was contributed by a colleague at SAIC. Note that this will remove xsd:appinfo as well since it removes xsd:annotations and its children. | Normal | 2-Jul-2005 | Sall | LMI: Agreed! Our response to comment #763 suggested just this. Please provide a copy of this script to Greg Wilson (gwilson@ |
| 719 | GXS2 | (See IC Position Paper section 5.8 Run-time vs. Fully Documented Variants of Schemas) | 19-Jul-2005 | ICMWG | ||
| 723 | p.3-14, DOC1 | Recommend striking the specifics here, and just stating that a <xsd:documentation> element *should* (not must) exist. The specifics get into ISO/IEC 11179 and Core Components, and I don't believe that we should introduce any such methodology in this document unless it is absolutely necessary (adds layers of required understanding). | Normal | 16-Jun-2005 | Chiusano | LMI:
We believe it is useful to retain guidance that documentation be structured.
It will promote a consistent method to reference content meaning, and it may
promote tools support. Regarding the reference to Core Components, we believe that it is critical that the WorkGroup reach a consensus regarding whether terms such as 'Object Class', 'Property Term, etc should be referenced. It is true that these terms appear in the Core Components Technical Specification. |
| 743 | p.3-14, DOC2 | Recommend striking - CCTS-specific | Normal | 16-Jun-2005 | Chiusano | LMI: Agreed. The document has been updated to reflect this comment. |
| 754 | p.3-15, DOC3 | Recommend striking - 11179-specific | Normal | 16-Jun-2005 | Chiusano | LMI: We'd like to discuss this with the commenter. Specifically, is there a consensus within the group that this document should NOT be based on ISO 11179 ? |
| 763 | p.3-15, DOC4 | Recommend striking the specifics here, and just stating that a <xsd:documentation> element *should* (not must) exist. The specifics get into ISO/IEC 11179 and Core Components, and I don't believe that we should introduce any such methodology in this document unless it is absolutely necessary (adds layers of required understanding). | Normal | 16-Jun-2005 | Chiusano | LMI:
We believe it is useful to retain guidance that documentation be structured.
It will promote a consistent method to reference content meaning, and it may
promote tools support. Regarding the reference to Core Components, we believe that it is critical that the WorkGroup reach a consensus regarding whether terms such as 'Object Class', 'Property Term, etc should be referenced. It is true that these terms appear in the Core Components Technical Specification. |
| 795 | p.3-16, DOC5 | Recommend striking the specifics here, and just stating that a <xsd:documentation> element *should* (not must) exist. The specifics get into ISO/IEC 11179 and Core Components, and I don't believe that we should introduce any such methodology in this document unless it is absolutely necessary (adds layers of required understanding). | Normal | 16-Jun-2005 | Chiusano | LMI:
We believe it is useful to retain guidance that documentation be structured.
It will promote a consistent method to reference content meaning, and it may
promote tools support. Regarding the reference to Core Components, we believe that it is critical that the WorkGroup reach a consensus regarding whether terms such as 'Object Class', 'Property Term, etc should be referenced. It is true that these terms appear in the Core Components Technical Specification. |
| 812 | p.3-16, DOC6 | What is an "Association Property" element? | Normal | 16-Jun-2005 | Chiusano | LMI: We've added a description for this term. |
| 838 | XMLNDR Section 3.7.3 - Schema Guides? | have no idea what Section 3.7.3 - Schema
Guides is supposed to be. Does anyone else? |
Normal | 2-Jul-2005 | Sall | LMI: Its purpose is unclear. We have removed it. |
| 842 | XMLNDR Section 4.1.1 - Syntax Neutral Naming Rules / 11179 / OED - which one? | Recommend including a link
(below) to a free version of ISO 11179 because it’s not exactly a reference
that most XML developers will be familiar with. http://isotc.iso.org/livelink/livelink/fetch/2000/2489/Ittf_Home/PubliclyAvailableStandards.htm Also since later references are to parts other than Part 5, readers may need all 6 parts. If 11179 is not easy to obtain, many developers will ignore it. While I understand the need to discuss the Oxford English Dictionary (OED), again how will developers obtain this? It is expensive, voluminous (20 volumes, 22,00 pages, $1,500), and a little hard to justify to their managers. Perhaps you mean an abridged version, such as the Compact OED ($395), Shorter OED ($150), Concise OED ($30), or Pocket OED ($18)? (These are all real titles; list prices shown. All available from Amazon, even the 20-volume behemoth.) http://en.wikipedia.org/wiki/Oxford_English_Dictionary http://www.oed.com/ The section mentions “Oxford English Dictionary American Spellings”. I can find no such book with this exact title. Do you mean this 2000+ page baby? New Oxford American Dictionary (NOAD) Recommend that XDG include an appendix that lists a few dozen terms with their “correct” (American ;-) spelling, such as: Labor, Center, Organization, A Google search may produce such a list, perhaps http://en.wikipedia.org/wiki/American_and_British_English_spelling_differences http://en.wikipedia.org/wiki/Category:American_and_British_English_diffe My concern once again is that if we want XML developers to follow these naming rules, we should make it easier for them to find the resources they need. I believe the recommend dictionary reference should be for a practical, affordable resource. |
Normal | 2-Jul-2005 | Sall | |
| 843 | p.4-1, section 4.1.1 | first paragraph: Add a mention of harmonization to this paragraph. | Normal | 21-Jun-2005 | Chiusano | LMI: The document has been updated to reflect this comment. |
| 852 | p.4-1, section 4.1.1 | third paragraph, first sentence: The immediate mention of "All official dictionary entry names" is surprising to the reader, as there is no context set up. What dictionary are we speaking of? Why do we care about the notion of a dictionary entry name? It is only until later that it is clear, since Dictionary Entry Name is a property of a data element. Recommend prefacing the first sentence of this paragraph with "One of the propries of data elements that we will refer to below is a Dictionary Entry Name", etc. | Normal | 21-Jun-2005 | Chiusano | LMI: The document has been updated to reflect this comment. |
| 852 | 4.1.1, DEN1, GNR1 | (See IC Position Paper section 5.9 Oxford English vs. American Spelling) | 19-Jul-2005 | ICMWG | ||
| 857 | p.4-1, section 4.1.1 | fourth paragraph, first sentence: Why will a supplementary Controlled Vocabulary of...(etc,) be created? We again jump into an explanation with no context. Who will create this Controlled Vocabulary? How will it be referenced? Why is it needed? | Normal | 21-Jun-2005 | Chiusano | |
| 857 | p.4-1, section 4.1.1 | fourth paragraph, first sentence, "will be developed to identify the definition...": If a data element includes a Definition, why is it necessary to refer to Object Classes, Property Terms, and Qualifiers for the definition? | Normal | 21-Jun-2005 | Chiusano | |
| 857 | p.4-1, section 4.1.1 | fourth paragraph, first sentence, "This Controlled Vocabulary shall also be used to identify...": What is an example of this? And what would make one word "preferred" over another? | Normal | 21-Jun-2005 | Chiusano | |
| 857 | p.4-1, section 4.1.1 | fourth paragraph, first sentence, "The Controlled Vocabulary will also contain terms not found in the Oxford [and sentence that follows]...": Why will this ensure that each word within any of the names and definitions is used in a consistent and unambiguous way? I do not see the connection here. | Normal | 21-Jun-2005 | Chiusano | |
| 857 | XMLNDR Section 4.1.1 - Controlled Vocabulary and DEN3 | Where is the Controlled
Vocabulary? How do I obtain it? How do I add to it? Who decides what goes
into it? Regarding DEN3, while short sentences is a good idea for definitions, insisting upon use (SHALL) of this “Controlled Vocabulary” is very impractical, even if it existed. A more practical rule would state that the term being defined cannot refer to itself (as is often the case when developers define a term) and SHOULD try use to simple terms (subjective, I know). |
Normal | 2-Jul-2005 | Sall | |
| 867 | p.4-2, section 4.1.1.1 | Recommend striking the discussion of Dictionary Entry Name, Definition, and Business Term. If we intend to provide standard metadata for federation capabilities (i.e. to facilitate transfer of data/metadata between registries), it should be covered in a data management strategy. Corresponding rules should also be struck/updated (i.e. DEN1 - DEN18 struck, DEN19-on updated as they reference dictionary definitions, etc., also GNR2, GNR3, etc. and later in the chapter as well). | Normal | 21-Jun-2005 | Chiusano | |
| 928 | XMLNDR DEN7 - uniqueness of DEN | DEN7 says the DEN shall be
unique. What is the scope of this statement? Unique in the federal govt? Per
agency? Per project? Per namespace? Per schema? I hope this means per schema or namespace, otherwise it is virtually impossible to control or even ascertain until there is some federated registry out there in .gov land. Perhaps this needs to be explicitly related to the Global Element rule? |
Normal | 2-Jul-2005 | Sall | |
| 928 | DEN7 | (See IC Position Paper section 4.4 Clarify Uniqueness of Dictionary Entry Name (DEN)) | 19-Jul-2005 | ICMWG | ||
| 930 | XMLNDR DEN8 | What does DEN8 mean? “The Dictionary Entry Name shall be extracted from the definition.” It can’t mean that the DEN appears in the definition since that seems to disagree with the Note that follows DEN6. |
Normal | 2-Jul-2005 | Sall | |
| 944 | [DEN12] | This should be a “should”. I do not like it, but there are times when prepositions and conjunctions are necessary in element names | Normal | 23-Jun-2005 | Vincent | |
| 944 | XMLNDR DEN12 - verbs, nouns, and adjectives (oh, my!) | While I believe allowing
verbs in the DEN is a “good” thing, I’ve yet to see an example of this in
either the XDG or the various NDRs. Todd, can you suggest examples from your
work that could be added to the XDG? Also, are we sure we don’t want conjunctions and prepositions such as “and” and “of”? What about - CostOfGoodsSold - ProductAndServiceCode (PSC code in IAE) - CommercialAndGovernmentEntityID (CAGE code in IAE) |
Normal | 2-Jul-2005 | Sall | |
| 944 | DEN12 | (See IC Position Paper section 5.11 Permit Prepositions, Conjunctions and Articles in Element Names) | 19-Jul-2005 | ICMWG | ||
| 960 | XMLNDR DEN15 - Qualifier Terms | If the XDG is going to use 11179 and CCTS concepts such as “Qualifiers”, I strongly recommend clear explanations about when something is a Qualifer vs. a new Object Class and when something is a Qualifier for a Property Term vs. a new Property Term. I found this to be the most confusing and subjective aspect of the CCTS. Non-trivial examples for these cases should be a must (MUST?). | Normal | 2-Jul-2005 | Sall | |
| 1012 | p.4-7, section 4.1.2 | Need examples/justifications for each rule (and many other rules in this chapter for that matter). | Normal | 21-Jun-2005 | Chiusano | |
| 1012 | p.4-7 | Most rules are missing (only section/subsection headings are given). I realize I'm pointing out the obvious, but want to make sure that it is noted. | Normal | 21-Jun-2005 | Chiusano | |
| 1017 | [GNR2] | This rule is dependant on the modularity model you choose | Normal | 23-Jun-2005 | Vincent | |
| 1024 | XMLNDR GNR4-6, DEN13 - acronyms and abbreviations! | When I read DEN13, I
thought, “At last – practical guidance for acronyms and abbreviations –
expand them in the documentation/definition. But then I came to GNR4, GNR5,
and GNR6 that essentially limit our set to Appendix XX (B) which contains
only DUNS, ID, and URI (which of course, is the UBL set). Please strike GNR4, GNR5, and GNR6 or at least re-work them into something practical! The government space is replete with acronyms and abbreviations, some that when expanded form ridiculously long element names. In my first few weeks in my new job, I encountered over 200 acronyms. While I strongly agree with DEN13, I fail to see why we can’t use acronyms and abbreviations in element names, provided that the required definition in the required xsd:documentation element expands the term. Any human user of an instance that references the schema will be able to obtain the documented expansion. (Well, if they get the non-run-time version, that is.) One can only imagine that any process implied by GNR5 to add “federal approved” acronyms and abbreviations will be long in coming and hard to centralize. Do you honestly think DoD and the IC are going to expand NATO and WMD wherever they are used in XML? What about US and USAF? What did DON do regarding these rules? Do they spell out DepartmentOfTheNavy in each element containing “DON”? (Note the preposition and article in the expansion, BTW.) There are hundreds of well-understood terms that belong in Appendix B. These rules as written are simply impractical. At a minimum, change MUST to SHOULD in these 3 rules, or just make them “suggestions”. |
Normal | 2-Jul-2005 | Sall | |
| 1024 | DEN13, GNR4, GNR5 | (See IC Position Paper section 4.2 Allow Abbreviations and Acronyms) | 19-Jul-2005 | ICMWG | ||
| 1041 | [GNR9] | This is a bad rule. It adds unnecessary complexity. I understand that this is an OASIS rule, but it is one that makes no sense. As I stated in a post to the list, if you were to vary this rule, then you would have an upper camel case rule for elements, compelxt types, and attributes and a lower camel case rule for simple types. Otherwise, it should be upper camel case for everything. | Normal | 23-Jun-2005 | Vincent | |
| 1046 | [CTN1,2,3] | There is no reason to add the Type suffix to the coplexType name, This is a senseless rule. The rule should be MUST NOT use the suffix “Type.” | Normal | 23-Jun-2005 | Vincent | |
| 1061 | p.4-8, CTN3 | Remove reference to Core Component Types. This can be covered by 11179 (less standards/methodologies with which the reader must become familiar). | Normal | 21-Jun-2005 | Chiusano | |
| 1061 | XMLNDR CTN3 | CTN3 refers to ccts:CoreComponentTypes. This appears to be the only remaining use of that prefix (or even “CCTS”) in the XDG. | Normal | 2-Jul-2005 | Sall | |
| 1068 | Section 4 | XMLNDR Missing rules in 4.2.4, 4.2.5, and 4.3 | Normal | 2-Jul-2005 | Sall | |
| 1079 | [ATN1] | I suggest using local attribute only, not global attributes. Any global attribute could just as easily be a global element (if it is truly global) or should be a local attribute if it only applies to one or a handful of element. In sum, there is no need for globally declared attributes. There is a need for locally declared attributes that are applies globally. This is best done with an attribute group and then applying the attribute group to every element. | Normal | 23-Jun-2005 | Vincent | |
| 1089 | [STD1] | Echoing comments above – this seems to me to add an additional (and unnecessary) layer of complexity and overhead to the schema. I would be grateful for an example | Normal | 23-Jun-2005 | Vincent | |
| 1089 | XMLNDR Section 5.1 - STD1 terminology - xsd:DataTypes | STD1 uses “metadata
components” without defining the term. STD1 uses “xsd:DataTypes” in the same font and manner in which is uses elements from the XSD language. There is no such element or attribute in XSD. Replace it with “XSD datatypes” or “XSD built-in datatypes” (i.e., don’t use a namespace prefix when you aren’t referring directly to an element or attribute from that namespace. Same problem with CTD12 and CTD14 later in Section 5.1.3. |
Normal | 2-Jul-2005 | Sall | |
| 1099 | [CTD2,3,4,5] | I do not understand this rule? Does this preclude the use of xsd:choice and other content model constructs? | Normal | 23-Jun-2005 | Vincent | |
| 1118 | [CTD7] | I thought you were going to take out references to the UN/CEFACT data types? | Normal | 23-Jun-2005 | Vincent | |
| 1147 | XMLNDR CTD13 to CTD15 are unclear | In section 5.1.3, rules
CTD13 – CTD15 are not written clearly. As is: [CTD13] The Unqualified Datatype xsd:complexType definition xsd:simpleContent element MUST contain one xsd:extension element. This xsd:extension element MUST include an xsd:base attribute that defines the specific xsd:Built-inDatatype required. [CTD14] Each metadata component xsd:attribute "type" MUST define the specific xsd:Built-in Datatype or the user defined xsd:simpleType for the metadata component of the unqualified Datatype. [CTD15] Each metadata component xsd:attribute "use" MUST define the occurrence of that metadata component as either "required", or "optional". It seems that if they were re-worded, they could be made clearer. For example, consider this for CTD15: [CTD15] The “use” xsd:attribute MUST be limited to either the value "required" or "optional". Do not use the value “prohibited”. If that is not what you mean, then whatever you do mean is very unclear to me! |
Normal | 2-Jul-2005 | Sall | |
| 1152 | [CTD14] | Again, it seems to me you are adding a layer on top of XSD that already exists in XSD – for what purpose, I cannot imagine? | Normal | 23-Jun-2005 | Vincent | |
| 1164 | [GXS8,9] | This is a bad rule. I would be curious to understand the reasons for it. | Normal | 23-Jun-2005 | Vincent | |
| 1164 | XMLNDR GXS8 - xsd:all | While I don’t normally use xsd:all, I think categorically prohibiting it is a bad idea. Why rule out what 40+ contributors to XSD spec thought might be of potential use to someone? What’s the justification? Please soften to SHOULD NOT and give a reason. | Normal | 2-Jul-2005 | Sall | |
| 1164 | GXS8 | (See IC Position Paper section 5.5 Permit xsd:all) | 19-Jul-2005 | ICMWG | ||
| 1167 | XMLNDR GXS9 - xsd:choice | As I’ve stated before on
ubl-dev, I am strongly opposed to prohibiting the use of xsd:choice. While
SHOULD NOT is less restrictive than MUST NOT, I really think you need to
present a very strong case why xsd:choice is even less preferred than
xsd:sequence. Nearly every schema I’ve written has used xsd:choice. Does it make sense that if you have one complexType with a bunch of children elements that also contain compleTypes and you encounter one case where a different child element may appear, that you now have to create 2 separate complexTypes, one that allows Child A and the other that allows Child B? |
Normal | 2-Jul-2005 | Sall | |
| 1167 | GXS9 | (See IC Position Paper section 4.5 Need for xsd:choice) | 19-Jul-2005 | ICMWG | ||
| 1167 | ATD5 | (See IC Position Paper section 4.7 Need for xsd:anyAttribute) | 19-Jul-2005 | ICMWG | ||
| 1172 | [GXS11] | I would not provide an exception. I would prohibit it without an exception | Normal | 23-Jun-2005 | Vincent | LMI: |
| 1172 | XMLNDR GXS11 - xsd:union | I’m not sure why folks (including Todd) want to prohibit xsd:union. I have seen cases, for example in government forms, in which either the value is from fixed list or it could be a generic response, such as “N/A” or “other”. It seems that xsd:union would be useful for defining special types such as that. | Normal | 2-Jul-2005 | Sall | LMI: |
| 1172 | GXS11 | (See IC Position Paper section 4.8 Need for xsd:union) | 19-Jul-2005 | ICMWG | ||
| 1207 | XMLNDR ELD7 - empty elements | I recommend that ELD7 be
changed from MUST NOT to SHOULD NOT be declared (used?). I see no harm in having data elements in
which a few attributes convey all of the information. In other words, empty
elements aren’t just devoid of content; they may contain attributes. Perhaps
the rule should be: [ELD7] Empty elements SHOULD NOT be used unless they contain one or more attributes. I can think of geospatial applications in which empty elements with attributes would be useful. |
Normal | 2-Jul-2005 | Sall | LMI: Agreed. The document has been modified to state that empty elements should not be used when XML information can be carried in either a) attributes at a parent level or b) elements at the lower level. In certain circumstances, it is beneficial from both a content modeling perspective as well a software implementation perspective to use empty elements. |
| 1207 | ELD7 | (See IC Position Paper section 4.9 Need for Empty Elements) | 19-Jul-2005 | ICMWG | ||
| 1209 | XMLNDR ELD8 - xsd:any | I believe WSDL (or some
other Web Services spec – Joe?) permits xsd:any children. Would this rule
prevent us from using WSDL? There are times when any well-formed content is acceptable (modulo security concerns, perhaps). The inner content need not be checked for validity. For example, the XSD spec itself allows xsd:any children of the xsd:documentation element, so we can put text or HTML or even some other custom XML markup inside it. Recommend softening the rule to: [ELD8] The xsd:any element SHOULD NOT be used, unless the content of the parent element can be any well-formed XML for which validity is not a concern. |
Normal | 2-Jul-2005 | Sall | LMI: This document procides
guidance for XML Schema development only. The WSDL spec has its own XML
Schema (http://www.w3.org/2003/11/wsdl/), and XML developers should refer to
this (if needed) for guidace about how to construct WSDL interfaces. As a side
note, we believe that the federal community would benefit from having in
place a set of best practices regarding WSDL creation. This will save
development efforts and will, like this NDRG document, service to decrease
the barrier to systems interoperability. LMI: With this said, we agree that it is reasonable to change this rule to SHOULD NOT so long as the sender has no restriction that the parent element is validated. |
| 1209 | ELD8 | (See IC Position Paper section 4.6 Need for xsd:any) | 19-Jul-2005 | ICMWG | ||
| 1229 | XMLNDR Section 5.3.4 - missing rule(s) | Section 5.3.4 on “Using Attribute Groups” is devoid of content | Normal | 2-Jul-2005 | Sall | LMI: This section is underway. |
| 1231 | [ATD3] | The first part of this rule is problematic. As a general rule, schemas should not be changed. Also, as a general rule, schemas should not be used from the Internet to validate instances. If you use a resolvable URL, then you are forced to either change the schema if you want to validate from a local schema or you are forced to validate from the (Internet) resolvable URL. As a result, the URL should always be relative. The publication rules for schemas should be such that regardless of the location of the schema, the relative path should work. | Normal | 23-Jun-2005 | Vincent | |
| 1265 | XMLNDR Section 7 - terminology - Code List vs. Identifier List | Section 7 needs some
introductory material to explain the terms “code list” and “identifier list”,
using other terms that developers may know, such as “controlled vocabularies”
or “enumerations” or even “pick lists”.
Furthermore, if Code and Identifier are being used as in the sense of CCTS types, I fail to see how Identifier Lists makes sense. Would you want a schema to have an enumerated list of all the SSNs, knowing that set of valid SSNs probably changes every few minutes? In other words, my understanding of one of the distinctions between Code and Identifier is that the latter is fairly dynamic. |
Normal | 2-Jul-2005 | Sall | |
| 1266 | XMLNDR Section 7 - CDL or CIL, that is the question | The table in Section 1 says that Code List rules are “CDL”, yet they are ll listed as “CIL” in Section 7. (CDL makes more sense to me.) | Normal | 2-Jul-2005 | Sall | |
| 1277 | XMLNDR CIL4 - Code List Schema Template? | I would like to see the
Code and Identifiers List Schema Module Template referenced in CIL4
(CDL4). Exactly which Code Lists will be released with the XDG that may be applicable government-wide? Suggestion: Create a simple one for the controlled vocabulary used is the US Postal Service's state abbreviations (http://www.usps.com/ncsc/lookups/usps_abbreviations.html ). We are using this in the DRM XSD and it would be better to use an externally defined code list, as per CIL2 (CDL2). |
Normal | 2-Jul-2005 | Sall | |
| 1288 | XMLNDR CIL7 - Code List Subsetting | CIL7 (CDL7) says we may “identify” a subset of a code list. How exactly will this subsetting mechanism work, in particular if we want to subset an externally maintained list? For example, in the US Postal Service's state abbreviations (http://www.usps.com/ncsc/lookups/usps_abbreviations.html), what if I don’t want to allow the last 3 (6?) codes (which are not actually part of the 50 states)? | Normal | 2-Jul-2005 | Sall | |
| 1288 | CIL7 | (See IC Position Paper section 5.7 Elaborate on Code List Subsetting Mechanism) | 19-Jul-2005 | ICMWG | ||
| 1297 | Chapter 8 | Schematron is a wonderful technology, but should not be included in this document. | Normal | 23-Jun-2005 | Vincent | |
| 1302 | XMLNDR GXS3 - xsd:simpleType | GSX3 should be reworded. As
it stands, it could be taken to mean you shouldn’t restrict built-in types.
For example, if I am a developer and I want to restrict a stinrg to length 30
and it’s not a built-in type, does this rule discourage me from doing “the
right” thing? Suggested wording: [GXS3] Whenever possible, use one of the 44 built-in simpleTypes pre-defined in XML Schema. However, it is expected that some schemas will need to further restrict the built-in types for application-specific constraints that are more stringent than the built-in types (e.g., limiting the length of a string or using pattern facets). |
Normal | 2-Jul-2005 | Sall | |
| 1312 | XMLNDR GXS12 - xsd:appinfo | GXS12: Please include
rational for prohibiting use of xsd:appinfo. I prefer the IRS wording: [GXS8] IRS schemas SHOULD NOT use xsd:appinfo. If used, xsd:appinfo MUST only be used to convey non-normative information |
Normal | 2-Jul-2005 | Sall | LMI: Agreed. We believe it is reasonable NOT to prevent uses of the appInfo element under certain circumstances. The rule has been reWorded. |
| 1319 | XMLNDR Section 10.1 and IND1 - Validation (Owen? possible show stopper) | The second sentence in
Section 10.1 should read: “It is valid if it is well-formed and conforms to a supporting DTD or Schema.” The same paragraph uses that mysterious “XML schema expressions” phrase. It also says “by default, every federal XML instance must have a supporting fully conformant XSD Schema.” The words “by default” are meaningless here, I believe, and potentially confusing. What is the alternative to the “default” case? Maybe it is providing a DTD? By the way, the IC Metadata Working Group provides an XSD and DTD for every “schema” we issue. There are some parts of our community who do not trust XML Schema or do not have the proper tools to support it. Owen, if would be a show-stopper to the IC if our users were not allowed to use our DTDs for validation purposes. Note that the vast majority of our work is related to document-centric XML, a huge area, nonetheless. Suggest re-wording IND1: [IND1] All instances documents MUST validate against either an XML Schema or a DTD, with the former being preferred. |
Normal | 2-Jul-2005 | Sall | |
| 1323 | IND1 | (See IC Position Paper section 4.3 Need for DTDs) | 19-Jul-2005 | ICMWG | ||
| 1358 | XMLNDR Section 10.5 Empty elements and Null Values: IND5, IND6, ELD7, ATD4 | Section 10.5 Empty elements
and Null Values (IND5 and IND6) are really related to ELD7 (empty elements)
and ATD4 (nillable attribute). These
rules should be combined and located in one section. ….And that closes my review of the XDG, draft of 6/9/05….. |
Normal | 2-Jul-2005 | Sall | LMI: Agreed. We've moved the 2 rules cited to section 5.2.7 ('Empty Elements)' of the document. |