[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: re: Draft responses to NDR comments from the public review
Sorry this has taken some time and I can appreciate how much effort you’ve put into this already, but here are my reactions to the dispositions. See comments inline below... > Fellow UBL TC members, > > > I have reviewed the three comments received at the public comment email address and I offer the responses below as candidate dispositions for each. > . . . . . . Ken > > Comment from Klaus-Dieter Naujok <tc154chair@mail-etc.net> > > https://lists.oasis-open.org/archives/ubl-comment/201503/msg00001.html > > > > The UBL TC notes that ISO IS 15000-5:2014 post-dates the release of UBL 2.1, while the UN/CEFACT CCTS 2.01 that was designated ISO TS 15000-5:2005 remains current and has not been superceded. For these reasons, the reference in the NDR is not inappropriate. > Regarding the comment of the NDR possibly being in conflict with the revised ISO 15000-5:2014, the UBL TC notes this is unlikely given the commitment of TC154 to maintaining backwards compatibility to ISO TS 15000-5:2014 as documented in the following report: > http://ec.europa.eu/enterprise/sectors/ict/files/invoicing/e-invoicing-standardisation-overview-issues-and-conclusions-for-future-actions_en.pdf > > (Page 14) > > ISO TC154 is committed to upgrade the ISO TS15000-5 CCTS to a full IS standard and this work item has been approved on the basis that backwards compatibility with the current widely implemented TS version is maintained. This is the UBL NDR specification we are talking about not UBL 2.1, so are we answering the right question? The NDR can be used to create XML vocabularies from CCTS libraries - we use UBL 2.1 as an exemplar but it is not the only application. Can we just replace the old references to ISO TS 15000-5:2005 with "UN/CEFACT CCTS 2.01 (that was designated ISO TS 15000-5:2005)”? This makes it clear which CCTS it is based on. We don’t need to discuss ISO 15000-5:2014 because it is not a specification used for this publication. We could add…. "The UBL TC wish to ensure the investments made by implementers are protected by stabilising on the UN/CEFACT CCTS 2.01 (that was designated ISO TS 15000-5:2005 when published) while this remains current and has not been superseded.” The full title for refacing should be: “UN/CEFACT Core Components Technical Specification – Part 8 of the ebXML Framework Version 2.01 (15 November 2003)” as taken from the document in the normative references. I appreciate this is different to the way it is presented in the UBL 2.1 standard but of course (as you pointed out) UBL 2.1 was published before there was an ISO 15000-5:2014 and back then we had one commonly agreed version of CCTS 2.01. Now there is also a different ISO version (albeit backward compatible) we should be precise which version these NDR are based on. > > Comment from OASIS TC Administration <tc-admin@oasis-open.org> > > https://lists.oasis-open.org/archives/ubl-comment/201503/msg00002.html > > > > The UBL TC acknowledges, with appreciation, the edits to be made to references used in the document. > > > Comments from the OASIS Technical Advisory Board > > https://lists.oasis-open.org/archives/ubl-comment/201504/msg00002.html > > > (a summary of JIRA tickets entered by TAB members) > > https://issues.oasis-open.org/issues/?jql=project%20%3D%20TAB%20AND%20affectedVersion%20%3D%20%22UBL%20Naming%20and%20Design%20Rules%20Version%203.0%20%22 > > > > https://issues.oasis-open.org/browse/TAB-1158 > > - re: why not just an "information bundle"? > - rejected > > - because what is being specified is the creation of multiple validation artefacts (schemas) describing information bundle definitions, that constrain the information bundles (instances) ... the NDRs do not create information bundles - the introduction section makes the distinction in the first sentence of the third paragraph "the process by which the user data syntax constraint mechanisms are created from the abstract definition of the information bundles", which is consistent with referring to "information bundle definitions" in the conformance section We do use the term ‘collection’ more than ‘set’ (e.g. Extension collection). I also think that we define the Information Bundle as "The formal description of the semantics of the recorded information to be exchanged” so it is the definitions - not the instances. The NDRs may not create information bundles, but they create expressions of information bundles in XML syntax. So how about saying… "A collection of information bundles defined in XML syntax …” so we are completely clear. > - re: Imprecise reference to normative content > - agreed > > - the text will be modified to read "where the words shall or required are used" > - re: conformance clause relying on examples > - rejected > > - reviewing the examples (entered as <note> elements) in the XML of the content there are zero occurrences of the words "must" or "required" in the prose of any of them > - re: normative text outside of the context of rules > - rejected > > - reviewing the XML, all rules are edited using the element <informaltable> and there no occurrences outside of a rule of the word "must" that is used to describe a constraint of the specification - the conformance clause refers to not violating "any rule or requirement expressed in normative sections of this specification" ... perhaps the phrase "or requirement expressed in normative sections" could safely be removed thus leaving the sentence to read "does not violate any rule of this specification", but I see no problem with leaving the sentence as it is - the list is not necessary in the conformance section as the list is simply all of the rules - Appendix C provides a summary list for convenience and reference into the specification We may be overthinking this. As a layman i also find the clause hard to follow. I think we are just trying to say “must conform to the ’shall’ rules”. What if we reordered Appendix C (Summary of rules) into C.1 Mandatory (i.e. ’shall’) and C.2 Optional (i.e. ‘may’). Then we can refer to rules listed in Appendix C.1 as those required for conformance. Something like… "A collection of information bundles defined in XML syntax and their associated user data validation artefacts conforming to these naming and design rules does not violate any rule expressed in the normative sections of this specification (and summarised in Appendix C.1).” This gives us the list that was suggested as well. > https://issues.oasis-open.org/browse/TAB-1157 > > - re: the non-normative annex using the normative keywords > - rejected > > - Appendix C is an informative summary of only the verbatim introductory paragraph of the rules found in the normative text. For brevity and reference purposes, the complete text of the rules is not copied, only the introductory paragraph of each, so that the reader can determine which rule they may wish to examine more closely. That the verbatim citations happen to include a copy of normative keywords is not meant to convey additional requirements, as reinforced by the appendix being marked as "Non-Normative”. i agree > https://issues.oasis-open.org/browse/TAB-1156 > > - re: 1.1.2 > - rejected > > - in the definition of "naming and design rules" the local link behind the text "Core Component Technical Specification" is to the entry "Core Component Technical Specification", also in 1.1.2 - in the PDF in full-page mode the action leaves the impression the link is self-referential, however, when page scrolling is turned on in Acrobat the link moves the reader to a point just above the entry for "Core Component Technical Specification" > - in the HTML this correct behaviour is more pronounced > It is probably better to not have any of the links for this definition as they all refer to sections nearby anyway. Adding a link to go back or forward a few lines may create confusion (as it has with this reviewer). > > https://issues.oasis-open.org/browse/TAB-1155 > > - re: shaded background > - rejected > > - the shaded background is a formatting property only of markup examples and not of the prose: where an example is comprised only of markup (DCL06 as cited), the example appears to be fully shaded; where the example is comprised of both markup examples and prose (DCL08 is an example), the formatting properties can be distinguished i don’t really understand the concern as all markup examples are shaded on both my PDF and HTML versions. > https://issues.oasis-open.org/browse/TAB-1154 > > - re: heavy normative style > - acknowledged but no changes proposed > > - it is acknowledged that the algorithmic-sounding text appears arcane, but the pseudo-code in the associated example formulae is meant to illustrate the requirement in place of using a grammar to illustrate the requirement - can the person commenting recommend a particular grammar suited to expressing the conditional properties illustrated using the "IF" construct? How about this? Name (mandatory; derived) • this value shall be derived from the Dictionary Entry Name with the Object Class Qualifier and Object Class removed together with any underscores, intervening spaces and periods. Abbreviations may be applied to Property Terms and Representation Terms as required. Representation Terms are omitted if the value is "Text" or the Property Term Primary Noun is equivalent to the Representation Term. Then for the Dictionary Entry Name I think we need to refer to the CCTS for the Dictionary Entry Name definition (rather than try to re-state it). See CCTS section 6.1.4.2.4 Rules for Business Information Entity Dictionary Entry Names. So we could just say... Dictionary Entry Name (mandatory; derived) • this value shall be the extracted from the Business Information Entity definition in accordance with CCTS section 6.1.4.2.4 "Rules for Business Information Entity Dictionary Entry Names". > https://issues.oasis-open.org/browse/TAB-1153 > > - re: GEN01 note > - accepted > - the note is suggested to be changed to: > "A tool implementing collaborative interaction among project members > responsible for the information being maintained would support such > a process well." > > i agree > https://issues.oasis-open.org/browse/TAB-1152 > > - re: use of the word "optional" > - rejected > > - the use of the word "optional" in the phrase "that extension collection shall be optional and not repeated" is in reference to the cardinality "optional and not repeated" and is not the use of a keyword, thus the extension collection shall have the cardinality of optional and not repeated - the phrase "optional and not repeated" is typically recognized as a term of cardinality and so the extra verbiage need not be present When you read the whole sentence "A document may be allowed to contain at most one extension collection, and if it is, that extension collection shall be optional and not repeated.” it does seem redundant to say “and not repeated” because you say “at most one”. It also seems redundant to say "shall be optional “ because you say “may be allowed”. So it seems to read that we are saying it is optional and may only occur once - and if it does it does occur, it is optional and may only occur once. How about just saying “A document may be allowed to contain at most one extension collection.”? I think it says the same thing. > https://issues.oasis-open.org/browse/TAB-1151 > > - use of the term "information bundle" > > - as the use of "information bundle" is described in the Introduction as coming from ISO/IEC 14662 and represents the semantic abstract of what becomes an entire document - the term "component" is used in all of the UBL specifications (0.7, 1.0, 2.0 and 2.1) as a concise term for a single item in the information bundle - in the text cited by the reviewer, the UBL NDR is formally defining the use of the term "component" as being a member of the collection of components that describes the "information bundle" ... thus, the terms "information bundle" and "component" are not the same thing, and UBL has long used the term "component" and so defines it in the context of "information bundle" as defined by ISO/IEC 14662 - the text cited by the reviewer goes on to describe the component's type is dealt with in the NDR as being described by the BIEs of CCTS, and as the reviewer notes, the paragraph is consistently using the CCTS terminology as described in CCTS - the editors felt it useful to the reader to reiterate these basic definitions and abbreviations of CCTS so as not to require the reader to hunt down the definitions in the CCTS specification - there is no attempt to redefine the CCTS specification or shift the vocabulary: in the abstract a UBL document is an information bundle comprised of components defined by CCTS properties ... this abstraction is realized as an XML document ... the NDR governs the creation of validation artefacts of the XML documents as defined by the information bundle definitions defined as a collection of components I think it could be clearer about the relationship of the terms. For example we say (in the Section 3 introduction) .. "Each document is an information bundle of business information entities sharing one or more common libraries of business information entities. Each business information entity is referred to as a component of the information bundle of the document or library. Each component corresponds to an XML element.” Does it make more sense to say.. "Each document is defined as an information bundle of components that may reference one or more common libraries of other components. Each component is defined as a business information entity (in terms of the CCTS) and corresponds to an XML element.” ? > https://issues.oasis-open.org/browse/TAB-1150 > - the duplication in section 2.1 is noted, but the use of "shall" in paragraphs 2 and 3 are satisfying the statement in the first paragraph that there are always two steps present - that this is echoed in the rule is a consequence of the rule needing a normative keyword - so the uses outside of the rules are expository and the uses inside of the rules are normative - the editors will consider rewriting the expository text not to use the normative keywords: "There is always a process by which CCTS information regarding information bundles is managed." and "There is always a process in which user data validation artefacts are produced." ... then the normative keywords in the rules support the expository text. I agree your proposed change addresses the issue raised. We only use the word “shall” in a normative and precise way. But I am also concerned we think this is “always”. I am not sure we want to insist on how the artefacts are maintained and mentioning specific technology is unnecessary and may outdate the specification quickly. In my view if we say anything about the process it can only be as a best practice recommendation rather than some form of conformance rule. The NDR rules take one type of artefact (Data Model) and explain how to transform this into another (XML). How that Data Model is developed and maintained is not key to the use of the NDR. In fact if the user can create the XML serialisation of the Data Model (in genericode) using a text editor, they should still be able to comply to the NDRs. > https://issues.oasis-open.org/browse/TAB-1149 > > - moving the extension concepts to be definitions is an acceptable suggestion > > - the concept "XML document validation" supports multiple references in the document to validation artefacts and the checking of constraints on user data expressed in XML, while the normative references make no references to "validation" and some readers will be unfamiliar with the XSD abbreviation - given the third paragraph of section 2 adequately sets the context of XSD in the role of expressing document constraints, the editors can remove section 1.1.4 entirely I agree > https://issues.oasis-open.org/browse/TAB-1148 > > - so noted, with appreciation > > > https://issues.oasis-open.org/browse/TAB-1147 > > - so noted, with appreciation > > > https://issues.oasis-open.org/browse/TAB-1146 > > - so noted, with appreciation > > > https://issues.oasis-open.org/browse/TAB-1145 > > - so noted, with appreciation > > > https://issues.oasis-open.org/browse/TAB-1144 > > - so noted, with appreciation > > > https://issues.oasis-open.org/browse/TAB-1143 > > - so noted, with appreciation > > > https://issues.oasis-open.org/browse/TAB-1142 > - accepted to move 11179 to the list of normative references (it is referenced in normatively in NDR section 1.1.2) > https://issues.oasis-open.org/browse/TAB-1141 > > - the reviewers are asked clarify the details of this issue > > - is it not true that, for example, clause 3.2 being labeled as non-normative confers the same non-normative status on descendent clauses? The editors can add the non-normative status to descendent clauses, but that seems redundant. I think the question relates to the parent's heading not the children. So Section 3.1 , 4.1 and 5.1 should be explicitly labelled as [Normative]. In principle 2.1 should be too but I think that should be [Non-Normative] (see above). > https://issues.oasis-open.org/browse/TAB-1140 > > - so noted, with appreciation > > -- > Check our site for free XML, XSLT, XSL-FO and UBL developer resources | > Free 5-hour lecture: > http://www.CraneSoftwrights.com/links/video.htm > | > Crane Softwrights Ltd. > http://www.CraneSoftwrights.com/o/ > | > G. Ken Holman > mailto:gkholman@CraneSoftwrights.com > | > Google+ profile: > http://plus.google.com/+GKenHolman-Crane/about > | > Legal business disclaimers: > http://www.CraneSoftwrights.com/legal > | > > > --- > This email has been checked for viruses by Avast antivirus software. > > http://www.avast.com ----------------- Regards Tim McGrath tim.mcgrath@documentengineeringservices.com Fremantle, Western Australia 6160 AUSTRALIA Phone: +61438352228 Skype: t.mcgrath
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]