| DRAFT - Federal XML Developers Guide Comments Matrix | ||||||
| Line #/Rule # | Proposed Change | Priority (High, Normal) | Date Submitted | Submitter Name | Accepted change (Y/N) | Rationale for change that is not accepted |
| All | General guidance vs. rules based (change all applicable 'MUST' rules to 'SHOULD') | High | 15-Jun-2005 | Ambur | ? | |
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| p.1-13, section 1.5.3 | Recommend defining "data-centric" and "document-centric". For an example, see the EPA XML Design Rules document. | Normal | 16-Jun-2005 | Chiusano | ||
| 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 | ||
| 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 | ||
| CHAPTER 2 COMMENTS | Recommend striking entire chapter, as it belongs in a data modeling manual not an NDR document. | Normal | 16-Jun-2005 | Chiusano | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| General: | Most rules in this chapter are missing explanations/justifications (I know that's obvious, just emphasizing it). | Normal | 16-Jun-2005 | Chiusano | ||
| p.3-3, NMS1 | As a reader, I am saying to myself "What is an internal schema module?". | Normal | 16-Jun-2005 | Chiusano | ||
| p.3-4, NMS2 | As a reader, I am saying to myself "What is a schema set version?". | Normal | 16-Jun-2005 | Chiusano | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| p.3-5, section 3.5 | Recommend striking this section. Versioning should be addressed in a data management strategy. | Normal | 16-Jun-2005 | Chiusano | ||
| p.3-8, Figure 3-1 | Recommend simplifying this diagram, else no one will read/comprehend it. | Normal | 16-Jun-2005 | Chiusano | ||
| 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 | ||
| p.3-9, SSM1 | What is a "root schema expression"? Schemas don't have expressions (XSLT stylesheets do). | Normal | 16-Jun-2005 | Chiusano | ||
| 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 | ||
| 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 | ||
| 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 | ||
| p.3-9, SSM5 | Continuing along the same lines, did not understand this rule. | Normal | 16-Jun-2005 | Chiusano | ||
| p.3-9, SSM6 | Continuing along the same lines, did not understand this rule. | Normal | 16-Jun-2005 | Chiusano | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| p.3-13, section 3.7.1 | Recommend providing more context around the mention of xsd:appInfo. | Normal | 16-Jun-2005 | Chiusano | ||
| 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 | ||
| 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 | ||
| p.3-14, DOC2 | Recommend striking - CCTS-specific | Normal | 16-Jun-2005 | Chiusano | ||
| p.3-15, DOC3 | Recommend striking - 11179-specific | Normal | 16-Jun-2005 | Chiusano | ||
| 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 | ||
| 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 | ||
| p.3-16, DOC6 | What is an "Association Property" element? | Normal | 16-Jun-2005 | Chiusano | ||
| p.4-1, section 4.1.1 | first paragraph: Add a mention of harmonization to this paragraph. | Normal | 21-Jun-2005 | Chiusano | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| [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 | ||
| [STA2] | [I would strike the rest of this section.] | Normal | 23-Jun-2005 | Vincent | ||
| 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 | |||
| [STA3] | Proprietary extensions to the W3C specifications MAY be used, but SHOULD BE USED with caution.. | Normal | 23-Jun-2005 | Vincent | ||
| 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 | ||
| 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 | ||
| Chapter 2 | I would move this to an appendix. I do not necessarily think you should strike it | Normal | 23-Jun-2005 | Vincent | ||
| 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 | ||
| 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 | ||
| [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 | ||
| 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 | ||
| [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 | ||
| [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 | ||
| [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 | ||
| [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 | ||
| [NMS1] | This having been said, it is not clear to me what you mean by “internal schema modules”. | Normal | 23-Jun-2005 | Vincent | ||
| [NMS2] | Again, this rule, which you say “schema set” appears to favor the second model. | Normal | 23-Jun-2005 | Vincent | ||
| [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 | ||
| 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 | ||
| 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 | ||
| [VER3] | I would not allow a minor version change (any version change) without a change in the namespace. | Normal | 23-Jun-2005 | Vincent | ||
| Figure 3-1 | I do not understand this diagram | Normal | 23-Jun-2005 | Vincent | ||
| [SSM1] | Again, this indicates the second model, not the first or the third. | Normal | 23-Jun-2005 | Vincent | ||
| [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 | ||
| [SSM7] | An example would be helpful. | Normal | 23-Jun-2005 | Vincent | ||
| [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 | ||
| [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 | ||
| [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 | ||
| [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 | ||
| [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 | ||
| Comments on federal modules apply to agency modules | Normal | 23-Jun-2005 | Vincent | |||
| [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 | ||
| [GNR2] | This rule is dependant on the modularity model you choose | Normal | 23-Jun-2005 | Vincent | ||
| [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 | ||
| [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 | ||
| [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 | ||
| [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 | ||
| [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 | ||
| [CTD7] | I thought you were going to take out references to the UN/CEFACT data types? | Normal | 23-Jun-2005 | Vincent | ||
| [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 | ||
| [GXS8,9] | This is a bad rule. I would be curious to understand the reasons for it. | Normal | 23-Jun-2005 | Vincent | ||
| [GXS11] | I would not provide an exception. I would prohibit it without an exception | Normal | 23-Jun-2005 | Vincent | ||
| [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 | ||
| Chapter 8 | Schematron is a wonderful technology, but should not be included in this document. | Normal | 23-Jun-2005 | Vincent | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| XMLNDR NMS7 | Appears twice | Normal | 2-Jul-2005 | Sall | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| Section 4 | XMLNDR Missing rules in 4.2.4, 4.2.5, and 4.3 | Normal | 2-Jul-2005 | Sall | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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 | ||