[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Comments on Naming and Design Rules (cd-UBL-NDR-1.0)
Due to an annoying mail filter (curse those HTML mail readers), I did not receive notice of the proposed NDR Committee Draft document before it was balloted. So i was not able to review the document before voting. Therefore, I am using the 4 week TC comment period to submit my comments. Please find these in the attached text document. The official OASIS response form does not accept this type of submission so I am lodging a reference to this email on that system for future reference. -- regards tim mcgrath phone: +618 93352228 postal: po box 1289 fremantle western australia 6160
Line 30-31 (Abstract) The statement... "This specification documents the naming and design rules and guidelines for the construction of XML components from ebXML Core Components." appears to have been changed from the more correct ... "This specification documents the naming and design rules and guidelines for the construction of XML components for the UBL vocabulary." This latter statement concurs with the current body of the Introduction (lines 180-181). The former belongs to ATG2. I thought we had agreed to chnage this already. Line 189-190 (section 1.1 Audiences) Given the charter above it is not "the UBL Library Content Subcommittee will use this document to create normative form schema for business transactions." it should be the Tools and Techniques SC who are the primary audience within UBL. Line 199 (section 1.2 Scope) "two parties using objects" should say "two parties using document components". we don't just define objects. Lines 207 (section 1.3 Terminology and Notation) The example for [Definition] says 'definitions are normative' which is untrue and may be misleading especially as in lines 217-218 we say 'only rules are normative'. Lines 225 and 228 (section 1.3 Terminology and Notation) Appendix A should say Appendix C Line 309 (section 1.4.2 Design for Extensibility] the reference to XML DTD based systems is too specific. the argument applies to all types of XML vocabularies regardless of what schema language they use. Line 319 (section 1.4.2 Design for Extensibility] This section should reference the CM paper. Line 347 (section 2. Relationships to ebXML) I have previously made the comment that UBL does not employ the methodology described in the CCTS - because the CCTS does not have one. Line 348 (section 2. Relationships to ebXML) Don't we reference CCTS 2.01, not CCTS 2.0 ? Line 355 (section 2. Relationships to ebXML) We should say that ebXML CC are syntax-independent and that UBL is an XML respresentation of these. Line 380 (section 2.1 Mapping Business Information Entities to XSD) We should make a clear statement that UBL is a library of BIEs. Line 396 (section 2.1 Mapping Business Information Entities to XSD) Typos: 2 periods and the first of many mis-spellings of 'specialized' as 'specialised'.(needs global search and replace - i wont list them all) Line 398 (section 2.1 Mapping Business Information Entities to XSD) Typos: representationterms is mis-spelt Line 401 (section 2.1 Mapping Business Information Entities to XSD) When we say facets are we including sets of possible values (e.g. code sets) as well? Line 402 (section 2.1 Mapping Business Information Entities to XSD) I suspect DatatypeDatatype is not what is meant. But this is a good opprtunity to suggest this naming convention of using "ccts:", "ubl:" and so forth is being used inconsistently and is more confusing than enlightening. It makes sentences terribly difficult to follow. Line 405-406 (section 2.1 Mapping Business Information Entities to XSD) This document has a problem keeping the concept of data type (as used by CCTS) and datatype (as used by XSD) separate - they work at different levels of data definition. i thought we had agreed that we would use "datatype" for the XSD and "Data type" for the CCTS. Line 442-447 (section 2.1 Mapping Business Information Entities to XSD) The statement about OAG is not correct and it may be best to leave this out. Line 550 (section 3.2.1 Naming Constraints) 'pieces of information' is actually 'meta-data'. Line 557 (section 3.2.1 Naming Constraints) NMC1: I am not sure, but if we have an ABIE used in more than one association wouldn't this mean the ABIE had more than one FQP? Line 567 (section 3.2.2 Modeling Constraints) the term 'XML expression' may be better than 'development'. Line 569 (section 3.2.2.1 Defining Classes) UBL is based on instantiating ebXML ccts:BusinessInformationEntities not CoreComponents. Line 571 (section 3.2.2.1 Defining Classes) We do not define classes for BBIEs only ABIEs - BBIEs are properties of object classes. Line 572-574 (section 3.2.2.1 Defining Classes) It appears this last sentence duplicates the previous one. Line 601-669 (section 3.3.1.4 Reusable Elements) We should use an example that incldues either a code or ID so we can show how they are not global. Line 680-681 (section 3.3.1.4 Reusable Elements) This argument for the use of local codes is at odds with the fact that we have several mandatory codes defined in the UBL library. Line 773 and 800 (section 3.5 Versioning Scheme) the variable known as <name> should be defined. Line 852-856 (section 3.5 Versioning Scheme) I still find this logic difficult to follow. Is it saying... "The xsd:extension mechanism ensures that minor version will be backward compatible within their major version." Line 862-863 (section 3.5 Versioning Scheme) [VER10] This is not an NDR rule it is a UBL principle. Also the statement is not correct. No UBL version should break semantic compatibility with prior versions. Line 869 (section 3.6 Modularity) there are some hyphens "-" which don't seem right here. Line 908-909 (section 3.5 UBL Modularity Model) Figure 3-2 Classes: the title is misleading - i would have thought 'schema dependency' is more descriptive. Line 972-973 (section 3.6.4 External schema modules) Editorial note still in here. Line 974 (section 3.6.4.7 UBL CommonAggregateComponents schema module) terms should be separated by spaces Line 988-989 (section 3.6.4.7 UBL CommonAggregateComponents schema module) [SSM10] i am not sure why this is a rule or what it actually means. do we need a rule that says we refer to this module by its name? in what sense is the phrase "ubl:COmmonAggregateComponents Schema Module" used? this also applies to [SSM12](lines 1017-1018),[SSM14](lines 1040-1041),[SSM17](lines 1078-179) and [SSM19](lines 1104-1105) Line 997-998 (section 3.6.4.7 UBL CommonAggregateComponents schema module) [NMS8]is this rule defining the namespace prefix to be used. why not say so? see also [NMS10] (lines 1027-1028), [NMS12] (lines 1055-1056), [NMS14](lines 1089-1090) and [NMS16] (lines 1113-1114). Line 999 (section 3.6.4.8 UBL CommonBasicComponents schema module) terms should be separated by spaces Line 1003-1006 (section 3.6.4.8 UBL CommonBasicComponents schema module) The section that reads... "The BBIE Properties are reusable in multiple BBIEs and per the CCTS are of type BBIE Property Type which are in turn of type Datatype. The BBIEs are reusable across multiple schema modules and per the CCTS are of Type BBIE Property Type." - is confusing. Is it trying to say... "BBIE Properties Types may be used for multiple BBIEs across multiple schema modules. Each BBIE Property Type is in turn a Data type as defined by the CCTS."? Line 1057 (section 3.6.4.10 CCTS Datatypes schema modules) Datatypes should be Data types. Line 1062 (section 3.6.4.10 CCTS Datatypes schema modules) ccts:datatype defines a set of valid values and also facets (we have it does earlier). Line 1069-1072 (section 3.6.4.10.1 CCTS Unspecilised Datatypes Schema module) UBL code list schema modules do not import CodeTypeUnspecialized Datatypes to avoid circular dependencies. Line 1091(section 3.6.4.10.2 CCTS Specialised Datatypes) title should be "CCTS Specialized Datatypes schema modules" to be consistent with other headings. Line 1096, 1097 (section 3.6.4.10.2 CCTS Specialised Datatypes) the term 'users' should be 'implementors of UBL' Line 1121(section 3.7 Annotation and Documentation) should 'core component parameters' be 'core component parameters schema'? Line 1134(section 3.7.2 Embedded Documentation) Rather than refer to UBL library spreadsheets, they are called document assembly models. Line 1138-1139 (section 3.7.2 Embedded Documentation) "information identified by LCSC" should say "meta data from the UBL document assembly models" Line 1141-1143 (section 3.7.2 Embedded Documentation) This sentence could be simplified by saying.. "For example, UBL assumes a value of "ALL" for every ebXML context classification." Line 1212 (section 3.7.2 Embedded Documentation) "synonym" should be "synonymous". Line 1266 (section 3.7.2 Embedded Documentation) "Core Component" should say "Core Component Type". Line 1338 (section 4.1 General Naming Rules) Appendix B needs updating. (see comments later) Line 1385 (section 4.2 Type Naming Rules) "Core Component Type" should say "Core Component Types". Line 1394-1397 (section 4.2.1 Complex Type Names for CCTS Aggregate Business Information Entities) the type name for an ABIE does not have its object class removed. For example, the ABIE 'Address' has a dictionary entry name of 'Address. Details', its object class is 'Address' and its complexType name is 'AddressType'. The rule that follows ([CTN1]) is correct, but the description preceeding it is not. Line 1556 (section 4.3.3 Element Names for CCTS Association Business Information Entities) "is bound to" could be better phrased as "re-uses". Line 1565-1567 (section 4.3.3 Element Names for CCTS Association Business Information Entities) [ELN4] is in the wrong place, it relates to BBIEs and should be after [ELN2] (line1536 - section 4.3.2) Line 1573-1575 (section 4.4. Attribute Naming Rules) [ATN1] needs to be extended with the truncation rule. that is, if the object class of the supplementary component is the same as the object class of Core Component Type or Data type to which it relates then the object class term is dropped from the attribute name. Line 1577 (section 4.4. Attribute Naming Rules) Add an example that shows ccts:SupplementaryComponent known as "Code. Name" becomes ubl:attribute "name" for the ccts:CoreComponentType "Code" and the complexType of "CodeType". Line 1621-1626 (section 5.1.3 Complex Types) Is confusing and unnecessary - this point is better made in section 3.2.2.1. for example, in line 1621 "Aggregate Business Information Entities" should say "Association Business Information Entities". these are the relationshsips between two ABIES. also, UBL does not treat BBIEs as object classes and i would not promote CCTS as defining object based concepts. Line 1627 (section 5.1.3 Complex Types) [CTD1] should say "For every object class..." not "For every class...". Line 1669-1670 (section 5.1.3.2 Basic Business Information Entitities) The statement.. "Basic Business Information Entities (BBIEs), in accordance with the Core Components Technical Specification, always have a primary representation term, and may have secondary representation terms, which describes their structural representation." is not correct. I think it means to say... "Basic Business Information Entities (BBIEs), in accordance with the Core Components Technical Specification, always have a representation term. This may be a primary or secondary representation term. Representation terms describe the structural representation of the BBIE." Line 1695 (section 5.1.3.3 Datatypes) The text belongs in section 2.1. The rule [CTD6] seems redundant. apart from simpleType and complexType what else could Data types be defined as? Line 1709 (section 5.1.3.3.1 Unspecialised Datatypes) The phrase, "The ccts:UnspecialisedDatatypes reflect the instantiation of the ccts:CoreComponentTypes", should say "The ccts:UnspecializedDatatypes reflect the instantiation of the Representation Terms of the ccts:CoreComponentTypes". Line 1710-1712 (section 5.1.3.3.1 Unspecialised Datatypes) the fonts are confused in this section. Line 1808 (section 5.2.1 General Element Declarations) this section has no content? Line 1814-1815 (section 5.2.2 Elements Bound to Complex Types) [ELD1] if the term 'class' is supposed to embrace all elements used then what about codes and IDs which are local? Line 1830 (section 5.2.2 Elements Representing ASBIEs) the phrase "...and ccts:BasicBusinessInformationEntities" should be "...or properties like ccts:BasicBusinessInformationEntities". Line 1832 (section 5.2.2 Elements Representing ASBIEs) rather than say "reference" it may be better to say "re-use". Line 1848 (section 5.2.5 Global Elements) it is worth adding some text that says something about how qualified BBIEs are re-uses of BBIEs in a specific context. Line 1874 (section 5.3.1 User Defined Attributes) [ATD2]Identifier. Content is not an attribute, it is expressed in the value of the element. Line 1901 (section 5.3.4 DatatypeSchema Location) Is this the correct title? - the rule applies to all UBL schema locations. Line 1908 (section 5.3.5 XSD:Nil) is [ATD7] is a repetition of [ELD6] (section 5.2.4)? Line 1912 (section 5.3.5 XSD:Any) [ATD8] repeats [ELD9] (section 5.2.6) Line 1914 (section 6 Code Lists) "handle them as schema modules" could say "handle them as individual schema modules". Line 1926 (section 6 Code Lists) [CLD1] not all UBL codes are defined. Line 1935-1937 (section 6 Code Lists) [CLD3] code lists can be restricted as well as extended. Line 2035 (section 7.11 Extension and Restriction) This section should reference the CM paper. Line 2094-2095 (section 8.5 Empty Content) [IND5] does this duplicate [ELD6] (section 5.2.4)? Line 2102-2103 (Appendix A) This introduction isn't necessary here. Line 2110 (Appendix A) "(DOC0" should be "(DOC)" Line 2148-2157 (Appendix B) The title should be 'Approved Abbreviations'. Abbreviations include initialisms, acronyms and apocopations. DUNS would be most likely used as an Agency ID value - so i suggest we dont need it here. It is not normally a property term. There are also some entries missing here... GUID "Globally Unique Identifier" UNDG "United Nations Dangerous Goods" CV2 "Credit Card Verification Numbering System" Appendix C Technical Terminology NB No line numbers in this section? "class diagram" this looks unfinished - it mentions OMG and RUP definitions. "component" - this is not the way UBL uses this term. "context driver" - not the correct definition "core component catalog" - not applicable here and not used in the text "core component library" - not applicable here and not used in the text "core component type" - the text should be "A UBL BIE consists of one and only one Content Component Type that carries the actual content plus one or more Supplementary Components giving an essential extra definition to the Content Component." also I am not sure CCTs can't have a business context (look at the definition of Amount - definitely a commercial definitions in the domain of finance). "datatype" - both different defintions used here (XSD and CCTS are not the same). "Instance root/doctype" - not sure this is needed, complete or sensible. "Lower-level element" - is this the right meaning? "Naming Convention" - we don't have these for Core Components but we do for BIEs and supplementary components. "Schema" - not the right definition "schema module" - defined twice "Syntax Neutral Model" - says "TBD" (i prefer syntax-independent model, syntax-neutral is an impossibility) Appendix D [CCTS] - should be version 2.01 [CCFeedback] - not applicable [GOF] - not applicable (XHTML) - do we use this ?
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]