[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [ubl-cmsc] review of Customizations Document
Danny, excellent review, many many thanks! I think this gives me something to do over the next couple of hours ;) It is obvious that we (Matthew, Arofan, myself, etc.) are too close to the trees to see the forest; this kind of review by someone who's not so close is extremely valuable and will give us a lot of food for thought. Some of your questions do have answers. Some are new, and we'll have to either try to resolve them by email or at the F2F in London. Can people in this list let me know if they're coming to London or not? I'm aware of Arofan and myself being commited to being there, what about others? I will first try to incorporate your suggestions into the document. Then we'll try to respond, if we can, to your questions at the end of the document. Dan Vint wrote: > Ok I've reviewed the Customizations Guidelines for content and > illustrations. At the end of > this I have a bunch of questions that I think should be answered > somewhere. Many have to do > with the Context Methodology, that I think should have a general > description in this document. > > The introduction and background information look pretty good. It was > after this that I started > having difficulties with the structure. In my copy the numbering of the > levels is not correct > which doesn't help, so some of this may be just that problem. Anyway, > I'm think about an > organization and titles that would look something like this: > > 1 Introduction > > 2 Background > 2.1 The UBL Schema > 2.2 Customizations of UBL Schemas > 2.3 Customization of Customizations > > 3 Compatible UBL Customization > 3.1 Use of XSD Derivation > 3.1.1 Extensions > 3.1.2 Restrictions > 3.1.3 Combined Extension and Restriction > 3.2 Documenting the Customization > 3.3 Identifying Extensions - use of xsi:type > 3.4 Component design - complextype for everything > 3.5 Use of Namespaces > > 4 Non-Compatibly UBL Customization > 4.1 Use of Ur-Types > 4.2 Building New Types > > 5. Future direction > > Notices > > Some of these are just renamed from the current structure, the new > sections and their content > is described below. Basically I see some information that is trying to > be conveyed, burred in > less than obvious places, and in some cases add to confusing the topic > they are in. The new > sections raise the importance of the information and give you a clear > location to talk about > these issues. > > **************** > > The following is my review of the document, I reference the sections as > they are in the > existing document. > > Section Compatibility: Customization through Derivation > ------------------------------------------------------- > > There is a lot of references things that can/can't be done without a > concrete example. It is > sort of like a textbook where the author will do something like that and > say "derivation or > proof is left to the reader", I think if we want to allude to things > that we should give a > supporting example or remove these references. An example is "(not all > of which can be > accomplished through direct XSD derivation)". > > The three bullet items are a little confusing. First I would add another > level of bullets that > would help the example above. I would create the following > > o Compatible UBL Customization > - Content of bullet 1 > > o Non-Compatible UBL Customization > - Content of bullet 2 > - Content of bullet 3 > > This will also help to match to outline I proposed as well. The current > content of these > bullets was hard to follow. For instance I was trying to figure out how > bullet 2 was different > or not supported by XSD. Later in the document is a slightly different > version of this list > that I think gave me better information or what was missing here. The > text is in a single > paragraph that immediately follows the section title "Customization > through other means". > > In "Use of XSD Derivation" that last sentence should probably have a > rule attached or greater > emphasis. Currently it seems to easy to loose this. > > Section Extensions > ------------------ > > I think we should try and keep this information in parallel with the > Restrictions section. To > me most of these bullets would be the content of the new sections (or > the basis of the > discussion) in my outline. The following is comments on these bullets as > they currently stand. > > End of the first bullet is a statement about UBL not allowing anonymous > types. I belive this > is a decision that is under discussion, so we need to make sure this > fits the final result. > Also, if we do end up allowing anonymous types, our examples should > expand to show them as > well as the what can/can't be done with them. > > Bullet 2 I was generally confused about the content. I understand where > it is trying to go, > but was lost in these words. I think this should be a section of its own > with an example. > > Bullet 3 Again I think this is a section we should have that "reviews" > the general naming and > design decisions. Also there is a "recommended" status on this, I would > think this should be > "required" if this is to be a public schema available for others to > extend (per the context > model and requirements). > > Bullet 4 Another new section on Namespace issues to go along with the > design rules. > > Section Restrictions > -------------------- > > I would change the start of the first paragraph to be more like the > start of the Extensions > section: "XSD restrict is used when information must be removed from the > UBL type ..." > > To provide support for the Non-compatible sections of this document, I > think it would be > useful to review/list the things that can/can't be done with > xsd:restrict. For instance: > > XSD restriction has a number of constraints that must be observed: > - any restriction must still be valid in terms of the original type, > for instance: > - you can reduce the required number repetitions > - you can't eliminate a required element or make it optional > - you can eliminate optional elements > > Section Compatibility: Context and Documentation > ------------------------------------------------- > > The second and third paragraph in this section seem out of place. If you > think these are > needed, I would put them in a Future Directions section of their own. > right now they confuse > the issue of documentation. > > We have the bullet list of context drivers, I would like to see some > examples of possible > values. Some are sort of obvious, but like System capabilities, I'm not > sure what that might > entail. > > It seems to me (and based upon the illustration) that each context > change should be one set of > schemas/extensions. I apply each one individually. As such I should be > able to just place the > documentation at the "top level" of the schema and not each component as > required in the > paragraph following the bullet list. If you allow multiples, then the > need for documentation > at each component becomes necessary and not all contexts may be applied > to every change. > > I think we need a definitive statement the multiples are allowed or not. > The example actually > shows multiples so this would need to change accordingly. Personally I > don't think you want to > allow multiples, otherwise how to manage the extensions? With multiples, > your diagram is not > as clean and it might be impossible to implement this stuff. > > > Section Customizations through other means > ------------------------------------------- > > The second paragraph alludes to ways that are non-compatible that will > potentially fix > reordering/placement issues (not defaulting to the end of the > structure). If this is true we > need an example of this - if I'm reading it right, I don't think this is > possible. > > 1st illustration > ----------------- > > I sort of follow this. I think you are using things like (a?, b?, c?) as > an example of the > model at each level. If that is true I think you need to things. I think > you need to make it > clear what is UBL and what is the Acme companies extensions. Second > issue is in the lower > right box all of a sudden there is a 'g' element added - I don't think > this illustration > shows where this came from. > > We might want to show the Compatible path and then non-compatible path > on this illustration or > something like it. > > 2nd illustration > ---------------- > > I think this is clear. To me this definitely implies a single context > being applied at a time. > I think this is the proper way to do this, but if we allow multiple > contexts, we should have > a second illustration to show the more complex situation and where/how a > second set of > extensions would fit in in that model. I also wonder if these really are > contexts that are > expected to be applied in a certain order. Am I making changes for the > US location or the > Insurance industry? I could look at it either way and the results could > be very different. > > Section Use of Ur-Types > ------------------------- > > Typo middle of first paragraph, you have Ur-ype > > I'm curious why making a new type, of existing UBL elements would be > consider to be non- > compatible. Assuming I'm not changing the defined use of those elements, > just that I need a > different group shouldn't be a reason to come up with the non-compatible > label. Also I guess > this implies that I can only add to existing complexTypes and be > compatible, I can't create a > new type. I need to check the schema, is there a complex type for the > high level document > object? is for the PurchaseOrder is there a PurchaseOrderType that I can > extend? > > Can I have a mixed compatible and non-compatible set of extensions in > the same schema? or if I > need non-compatible methods, should the whole set of extensions be based > upon the Ur-types > instead of the UBL types? Will need reasons for this. > > I found the last paragraph of this section unintelligible - I don't know > what you are trying to > tell me here. > > Section Building Types Using Core Components > --------------------------------------------- > > I don't see a reason for why I can add my new/strange element to an > existing structure and > have that compatible, but I can't create a type of existing UBL things, > and apply that to > the content model of my element and still have that be compatible. If > this is a true > statement (non-compatible) then we need some reasons why. > > I would move the last paragraph of this section to a "General Naming and > Design Requirements" > section. > > > General comments > ---------------- > > We need at least one complete example. For instance I don't see why I > can't use an adapter > schema methodology with redefine to make this work unless you show me > what you intend. The > little examples are ok for what you are covering, but no where do I get > the big picture. This > would then show the namespace issues, how to document, etc. May need a > non-compatible example > as well. > > Current illustrations are not properly placed. They need a figure number > and title and > somewhere in the text there should be a reference and explanation of > what is there. > > Examples might read a little better if we introduced the Acme: namespace > for things we are > adding/creating outside of UBL. > > > > ************** > > The following are the questions that I'm left with after just reading > this document. Now maybe > they are detailed in another document that I haven't read, but because > the topic is opened > here I think some sort of short answer is at least required in this > document with a pointer > for further details see something else. > > How do I determine if a given Context customization exists already? > > Are there any rules for substituting a more generalized and useful set > of customizations over > an existing one that may not be as good or complete? > > Is there a defined order of the Contexts? If there isn't it would seem > to make finding common > schemas more difficult. Suppose A defines a Business, Industry, then > Geopolitically > arrangement, but B comes at from a Geopolitical, Business, Industry > view. Both A and B use the > same values, it might be difficult to find this without some order > involved. > > Related to above. I'm in Insurance and only in the US. Now if someone > has created a set of US > extensions to the Purchase Order, we are saying I have to accept those > and add mine? Or is > there a way to come up with just US Insurance specific changes? I think > the plan is that I > would have to take the US extensions, restrict things out I don't want, > then add my US > specific things - correct? > > Can I restrict allowed derivations with XSD schema features? Would UBL > ever use these? > > All of this seems to assume that UBL is the starting point, will we > allow someone to import > another organizations elements and methodology? My guess is that this > would cause a non- > compatible UBL customization. I think we should probably make this clear > and maybe have a > strong reason why. > > I need to review the schemas, but we say our elements are based upon > restricting/extending the > Ur-types so they will be somewhat compatible with the non-compatible > methods. I don't think > this is the current state of the schemas and should be by the time we > publish this. > > One issue I think we need to answer is the portability/maintainability > of our extensions. It > looks like you intend to modify the UBL schemas directly (unless an > adapter method is used). > How can I manage my extensions in a manner that makes them easy to port > to the next release of > UBL or apply it to someone elses extensions? > > Should we have a flag/documentation that labels an extended schema as a > compatible or non- > compatible. You could write some things to check what we extended, but > it would be clearer to > have this stated rather than calculated. Also can I have a mixed schema, > part based upon UBL > and just a few things that come from the non-compatible side. I can see > two cases that might > have different answers: > - Needing a type based upon existing UBL elements > - Needing the UR-type to change required elements > > I think we need a section to cover questions like: > - How to apply namespaces > - element naming conventions for extensions > - component design requirements for extensions (an element based > upon a type, no local > elements, etc) > - where elements/codes get added in the extension process > > Is there going to be a mechanism to promote extensions back into the UBL > core schemas? What is > the impact on my extensions? > > What are the versioning requirements for UBL in terms of adding a > required element? Is > this a major or minor version? This impacts how my extensions work. If I > know that unless > we go to a major release (breaking backwards compatibility), I know that > I won't get a > required element in an existing structure. Now it might be that it > should be required, but > until a major release, it should remain as optional. > > I think we may have a problem like above with extensions of extensions. > Might need some > recommendations or warnings that adding a required element higher up, > may break > compatibility lower down as the element order shifts based upon > additions, and required > elements might break an existing stream. > > > ------------------------------------------------------------------------ > > Ok I've reviewed the Customizations Guidelines for content and illustrations. At the end of > this I have a bunch of questions that I think should be answered somewhere. Many have to do > with the Context Methodology, that I think should have a general description in this document. > > The introduction and background information look pretty good. It was after this that I started > having difficulties with the structure. In my copy the numbering of the levels is not correct > which doesn't help, so some of this may be just that problem. Anyway, I'm think about an > organization and titles that would look something like this: > > 1 Introduction > > 2 Background > 2.1 The UBL Schema > 2.2 Customizations of UBL Schemas > 2.3 Customization of Customizations > > 3 Compatible UBL Customization > 3.1 Use of XSD Derivation > 3.1.1 Extensions > 3.1.2 Restrictions > 3.1.3 Combined Extension and Restriction > 3.2 Documenting the Customization > 3.3 Identifying Extensions - use of xsi:type > 3.4 Component design - complextype for everything > 3.5 Use of Namespaces > > 4 Non-Compatibly UBL Customization > 4.1 Use of Ur-Types > 4.2 Building New Types > > 5. Future direction > > Notices > > Some of these are just renamed from the current structure, the new sections and their content > is described below. Basically I see some information that is trying to be conveyed, burred in > less than obvious places, and in some cases add to confusing the topic they are in. The new > sections raise the importance of the information and give you a clear location to talk about > these issues. > > **************** > > The following is my review of the document, I reference the sections as they are in the > existing document. > > Section Compatibility: Customization through Derivation > ------------------------------------------------------- > > There is a lot of references things that can/can't be done without a concrete example. It is > sort of like a textbook where the author will do something like that and say "derivation or > proof is left to the reader", I think if we want to allude to things that we should give a > supporting example or remove these references. An example is "(not all of which can be > accomplished through direct XSD derivation)". > > The three bullet items are a little confusing. First I would add another level of bullets that > would help the example above. I would create the following > > o Compatible UBL Customization > - Content of bullet 1 > > o Non-Compatible UBL Customization > - Content of bullet 2 > - Content of bullet 3 > > This will also help to match to outline I proposed as well. The current content of these > bullets was hard to follow. For instance I was trying to figure out how bullet 2 was different > or not supported by XSD. Later in the document is a slightly different version of this list > that I think gave me better information or what was missing here. The text is in a single > paragraph that immediately follows the section title "Customization through other means". > > In "Use of XSD Derivation" that last sentence should probably have a rule attached or greater > emphasis. Currently it seems to easy to loose this. > > Section Extensions > ------------------ > > I think we should try and keep this information in parallel with the Restrictions section. To > me most of these bullets would be the content of the new sections (or the basis of the > discussion) in my outline. The following is comments on these bullets as they currently stand. > > End of the first bullet is a statement about UBL not allowing anonymous types. I belive this > is a decision that is under discussion, so we need to make sure this fits the final result. > Also, if we do end up allowing anonymous types, our examples should expand to show them as > well as the what can/can't be done with them. > > Bullet 2 I was generally confused about the content. I understand where it is trying to go, > but was lost in these words. I think this should be a section of its own with an example. > > Bullet 3 Again I think this is a section we should have that "reviews" the general naming and > design decisions. Also there is a "recommended" status on this, I would think this should be > "required" if this is to be a public schema available for others to extend (per the context > model and requirements). > > Bullet 4 Another new section on Namespace issues to go along with the design rules. > > Section Restrictions > -------------------- > > I would change the start of the first paragraph to be more like the start of the Extensions > section: "XSD restrict is used when information must be removed from the UBL type ..." > > To provide support for the Non-compatible sections of this document, I think it would be > useful to review/list the things that can/can't be done with xsd:restrict. For instance: > > XSD restriction has a number of constraints that must be observed: > - any restriction must still be valid in terms of the original type, for instance: > - you can reduce the required number repetitions > - you can't eliminate a required element or make it optional > - you can eliminate optional elements > > Section Compatibility: Context and Documentation > ------------------------------------------------- > > The second and third paragraph in this section seem out of place. If you think these are > needed, I would put them in a Future Directions section of their own. right now they confuse > the issue of documentation. > > We have the bullet list of context drivers, I would like to see some examples of possible > values. Some are sort of obvious, but like System capabilities, I'm not sure what that might > entail. > > It seems to me (and based upon the illustration) that each context change should be one set of > schemas/extensions. I apply each one individually. As such I should be able to just place the > documentation at the "top level" of the schema and not each component as required in the > paragraph following the bullet list. If you allow multiples, then the need for documentation > at each component becomes necessary and not all contexts may be applied to every change. > > I think we need a definitive statement the multiples are allowed or not. The example actually > shows multiples so this would need to change accordingly. Personally I don't think you want to > allow multiples, otherwise how to manage the extensions? With multiples, your diagram is not > as clean and it might be impossible to implement this stuff. > > > Section Customizations through other means > ------------------------------------------- > > The second paragraph alludes to ways that are non-compatible that will potentially fix > reordering/placement issues (not defaulting to the end of the structure). If this is true we > need an example of this - if I'm reading it right, I don't think this is possible. > > 1st illustration > ----------------- > > I sort of follow this. I think you are using things like (a?, b?, c?) as an example of the > model at each level. If that is true I think you need to things. I think you need to make it > clear what is UBL and what is the Acme companies extensions. Second issue is in the lower > right box all of a sudden there is a 'g' element added - I don't think this illustration > shows where this came from. > > We might want to show the Compatible path and then non-compatible path on this illustration or > something like it. > > 2nd illustration > ---------------- > > I think this is clear. To me this definitely implies a single context being applied at a time. > I think this is the proper way to do this, but if we allow multiple contexts, we should have > a second illustration to show the more complex situation and where/how a second set of > extensions would fit in in that model. I also wonder if these really are contexts that are > expected to be applied in a certain order. Am I making changes for the US location or the > Insurance industry? I could look at it either way and the results could be very different. > > Section Use of Ur-Types > ------------------------- > > Typo middle of first paragraph, you have Ur-ype > > I'm curious why making a new type, of existing UBL elements would be consider to be non- > compatible. Assuming I'm not changing the defined use of those elements, just that I need a > different group shouldn't be a reason to come up with the non-compatible label. Also I guess > this implies that I can only add to existing complexTypes and be compatible, I can't create a > new type. I need to check the schema, is there a complex type for the high level document > object? is for the PurchaseOrder is there a PurchaseOrderType that I can extend? > > Can I have a mixed compatible and non-compatible set of extensions in the same schema? or if I > need non-compatible methods, should the whole set of extensions be based upon the Ur-types > instead of the UBL types? Will need reasons for this. > > I found the last paragraph of this section unintelligible - I don't know what you are trying to > tell me here. > > Section Building Types Using Core Components > --------------------------------------------- > > I don't see a reason for why I can add my new/strange element to an existing structure and > have that compatible, but I can't create a type of existing UBL things, and apply that to > the content model of my element and still have that be compatible. If this is a true > statement (non-compatible) then we need some reasons why. > > I would move the last paragraph of this section to a "General Naming and Design Requirements" > section. > > > General comments > ---------------- > > We need at least one complete example. For instance I don't see why I can't use an adapter > schema methodology with redefine to make this work unless you show me what you intend. The > little examples are ok for what you are covering, but no where do I get the big picture. This > would then show the namespace issues, how to document, etc. May need a non-compatible example > as well. > > Current illustrations are not properly placed. They need a figure number and title and > somewhere in the text there should be a reference and explanation of what is there. > > Examples might read a little better if we introduced the Acme: namespace for things we are > adding/creating outside of UBL. > > > > ************** > > The following are the questions that I'm left with after just reading this document. Now maybe > they are detailed in another document that I haven't read, but because the topic is opened > here I think some sort of short answer is at least required in this document with a pointer > for further details see something else. > > How do I determine if a given Context customization exists already? > > Are there any rules for substituting a more generalized and useful set of customizations over > an existing one that may not be as good or complete? > > Is there a defined order of the Contexts? If there isn't it would seem to make finding common > schemas more difficult. Suppose A defines a Business, Industry, then Geopolitically > arrangement, but B comes at from a Geopolitical, Business, Industry view. Both A and B use the > same values, it might be difficult to find this without some order involved. > > Related to above. I'm in Insurance and only in the US. Now if someone has created a set of US > extensions to the Purchase Order, we are saying I have to accept those and add mine? Or is > there a way to come up with just US Insurance specific changes? I think the plan is that I > would have to take the US extensions, restrict things out I don't want, then add my US > specific things - correct? > > Can I restrict allowed derivations with XSD schema features? Would UBL ever use these? > > All of this seems to assume that UBL is the starting point, will we allow someone to import > another organizations elements and methodology? My guess is that this would cause a non- > compatible UBL customization. I think we should probably make this clear and maybe have a > strong reason why. > > I need to review the schemas, but we say our elements are based upon restricting/extending the > Ur-types so they will be somewhat compatible with the non-compatible methods. I don't think > this is the current state of the schemas and should be by the time we publish this. > > One issue I think we need to answer is the portability/maintainability of our extensions. It > looks like you intend to modify the UBL schemas directly (unless an adapter method is used). > How can I manage my extensions in a manner that makes them easy to port to the next release of > UBL or apply it to someone elses extensions? > > Should we have a flag/documentation that labels an extended schema as a compatible or non- > compatible. You could write some things to check what we extended, but it would be clearer to > have this stated rather than calculated. Also can I have a mixed schema, part based upon UBL > and just a few things that come from the non-compatible side. I can see two cases that might > have different answers: > - Needing a type based upon existing UBL elements > - Needing the UR-type to change required elements > > I think we need a section to cover questions like: > - How to apply namespaces > - element naming conventions for extensions > - component design requirements for extensions (an element based upon a type, no local > elements, etc) > - where elements/codes get added in the extension process > > Is there going to be a mechanism to promote extensions back into the UBL core schemas? What is > the impact on my extensions? > > What are the versioning requirements for UBL in terms of adding a required element? Is > this a major or minor version? This impacts how my extensions work. If I know that unless > we go to a major release (breaking backwards compatibility), I know that I won't get a > required element in an existing structure. Now it might be that it should be required, but > until a major release, it should remain as optional. > > I think we may have a problem like above with extensions of extensions. Might need some > recommendations or warnings that adding a required element higher up, may break > compatibility lower down as the element order shifts based upon additions, and required > elements might break an existing stream. > -- Eduardo Gutentag | e-mail: eduardo.gutentag@Sun.COM Web Technologies and Standards | Phone: +1 510 550 4616 x31442 Sun Microsystems Inc. | 1800 Harrison St. Oakland, CA 94612 W3C AC Rep / OASIS TAB Chair
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]