1 2 Previous Next 17 Replies Latest reply on Jan 5, 2006 2:23 AM by Scott Stark

    XSD Schema Versioning and Naming

    Jim Rigsbee Newbie

      Do we want to support multiple schema versions in the product?

      If so I would load the XSD based on the namespace given in the jPDL XML root. (Easy change to SchemaValidationHelper)

      Or do we want to just keep upgrading the same XSD file. If so, I would recommend we rename the file to remove versioning.

      Alot of this depends on what level of backward compatibility the product will handle.

      Jim

        • 1. Re: XSD Schema Versioning and Naming
          Tom Baeyens Master

          the idea is to have 1 xsd for each minor version number: 3.0, 3.1, 3.2, ...

          XML schema can change (preferrably only additions) at minor version updates. but in point releases (e.g. 3.0.1, 3.0.2, ...) should support the same xml.

          so it is about time that we create the 3.1 version of the xsd. we also need to find out how the WTP xml editors work with respect to the xsd. For the graphical designer we need to know exactly how the WTP XML editor finds (and caches?) the xsd.

          regards, tom.

          regards, tom.

          • 2. Re: XSD Schema Versioning and Naming
            Jim Rigsbee Newbie

            Okay,

            Subject to making sure we don't break the XML editor in the GPD;
            I propose the following steps:

            1. Make a new 3.1 xsd from the current xsd in the tree as it contains updates for 3.1.
            2. Roll back the XSD for 3.0 to remove the 3.1 features.
            3. Change SchemaValidationHelper to match namespaces to XSD documents in the xml package.
            4. Namespaces will contain the major version number only such as 3, 3.1, 3.2, etc. Minor releases do not impact the namespace.

            Do I have the groups blessings to move forward with this? JIRA issue

            Jim

            • 3. Re: XSD Schema Versioning and Naming
              Koen Aers Master

              You have my blessing ;)
              I will add support to the GPD to be able to configure the xsd included in the process definition template.

              Regards,
              Koen

              • 4. Re: XSD Schema Versioning and Naming
                Alejandro Guizar Master

                Koen,

                Wouldn't configuring the schema require a complementary change in the jBPM library? I mean, you can't just use the 3.1 schema without upgrading to jBPM 3.1.

                -Alex

                • 5. Re: XSD Schema Versioning and Naming
                  Koen Aers Master

                  Alex,

                  You *can* already configure another core jBPM version in the preferences page of the plugin. The idea is that somehow, the xsd of the core jBPM version gets used when a new process definition is created.

                  Regards,
                  Koen

                  • 6. Re: XSD Schema Versioning and Naming
                    Tom Baeyens Master

                     

                    "jimrigsbee" wrote:
                    1. Make a new 3.1 xsd from the current xsd in the tree as it contains updates for 3.1.


                    there is only one real update: nodes are allowed to have the attribute async="true"

                    2. Roll back the XSD for 3.0 to remove the 3.1 features.


                    that is removing async="true"

                    3. Change SchemaValidationHelper to match namespaces to XSD documents in the xml package.


                    i don't get this yet

                    4. Namespaces will contain the major version number only such as 3, 3.1, 3.2, etc. Minor releases do not impact the namespace.


                    i agree

                    Do I have the groups blessings to move forward with this?


                    yes

                    One important note. It would be good if you could consider relaxing the xsd a bit. We have had a few occasions where the gpd produced XML that was readable by the parser, but it was invalid occording to the xsd. the gpd needs to put the namespace reference in there to get the xml code completion. so the process failed to deploy.

                    regards, tom.

                    • 7. Re: XSD Schema Versioning and Naming
                      Tom Baeyens Master

                      since this is currently an issue for which one of our clients is waiting, we are going to move forward with this.

                      i'm going to apply following changes:

                      1) refactor the event elements. instead of defining all event types inline and giving them a list of possible event types, i'm going to define one event element with a type attribute of string. that reflects better the nature of the xml. we will only loose the xml code completion in the gpd. if we want that code completion back, we must fix this by customizing the WTP XML editor instead of tweaking the xsd.

                      2) we're going to relax the sequence requirements currently imposed by the xsd. in the parsing of the xml, there is no restrictions on strictly separating the different sub elements cause we walk the dom tree by looping over all sub elements of a given name. we are looking into the xsd on how we can relax those constraints... grouping seems to be the best option, but we are still looking.

                      3) we are going to rename the name space to support versioning.

                      The old xsd namespace and xsd-URL will remain the same:

                      namespace: http://jbpm.org/3/jpdl
                      url: http://jbpm.org/xsd/jpdl-3.0.xsd


                      The new namespaces will look like this

                      namespace: http://jbpm.org/jpdl-3.0.xsd
                      url: http://jbpm.org/jpdl-3.0.xsd
                      
                      namespace: http://jbpm.org/jpdl-3.1.xsd
                      url: http://jbpm.org/jpdl-3.1.xsd


                      the XML schema of point releases like e.g. 3.0.x will be compatible.

                      regards, tom.

                      • 8. Re: XSD Schema Versioning and Naming
                        Tom Baeyens Master

                        tracking of this item is done in jira: http://jira.jboss.com/jira/browse/JBPM-473

                        regards, tom.

                        • 9. Re: XSD Schema Versioning and Naming
                          Jim Rigsbee Newbie

                          Explanation of change to SchemaValidationHelper. Right now we pass in the 3.0 XSD schema file name. the helper class loads this file to validate a process definition document.

                          If we are going to support multiple namespaces, we need to map the namespace to a local XSD file so that validation can be done without a network connection (plus we aren't sourcing the schemas on any website AFAIK)

                          JAXP processors like Xerces supports this through XML catalog technology. It matches the namespace and loads the proper XSD file.

                          ANOTHER OPTION: we could require the user to specify what version of the schema they want to use in the jbpm.properties. This is less flexible.

                          Jim

                          • 10. Re: XSD Schema Versioning and Naming
                            Tom Baeyens Master

                            i'm working my way through the xsd spec, tutorials, xerces and the wtp xml editor...

                            what a pain.

                            i'm almost there. i guess what you are referring to is the EntityHandler. i have updated that. i'll probably check in tomorrow. i made a few changes that you can see and i would appreciate your comments on them.

                            i use the SAXParserFactory instead of instantiating a new SAXParser. i have no idea what the difference is, but this is how it was exampled in the xerces and jaxp docs.

                            i have renamed SchemaValidationHelper to JpdlParser

                            i have removed some of the features that you enabled since they were not strictly necessary.

                            behaviour seems similar as before now. except for the validation tests. that is why i didn't check in yet.

                            regards, tom.

                            • 11. Re: XSD Schema Versioning and Naming
                              Alejandro Guizar Master

                              I suggest that the namespace names be different from the schema locations, to distinguish between logical structures and actual resources:

                              namespace: http://jbpm.org/jpdl/3.0
                              url: http://jbpm.org/xsd/jpdl-3.0.xsd
                              
                              namespace: http://jbpm.org/jpdl/3.1
                              url: http://jbpm.org/xsd/jpdl-3.1.xsd


                              The advantage is that you can offer alternate locations for the schema documents (say, http://jboss.org/products/jbpm/xsd/jpdl-3.0.xsd) without confusing any of them for the namespace of jPDL documents.

                              • 12. Re: XSD Schema Versioning and Naming
                                Tom Baeyens Master

                                this what i have now in the codebase:

                                namespace: http://jbpm.org/jpdl-3.0
                                url: http://jbpm.org/jpdl-3.0.xsd
                                
                                namespace: http://jbpm.org/jpdl-3.1
                                url: http://jbpm.org/jpdl-3.1.xsd


                                it's based on what i saw frequently (it doesn't seem to be a convention, though), it's easy to remember and it doesn't conflict with the previous version url of the schema.

                                with your reasoning, i would suggest:

                                namespace: jpdl-3.0
                                url: http://jbpm.org/jpdl-3.0.xsd
                                
                                namespace: jpdl-3.1
                                url: http://jbpm.org/jpdl-3.1.xsd


                                what do you think ?
                                who's going to do it ?

                                regards, tom.

                                • 13. Re: XSD Schema Versioning and Naming
                                  Tom Baeyens Master

                                  ah, of course... that's not unique enough.

                                  hmmm. then i think we should keep it as it is.

                                  regards, tom.

                                  • 14. Re: XSD Schema Versioning and Naming
                                    Alejandro Guizar Master

                                    MS uses uniform resource names for their namespaces. For example, the document element of their assembly manifest is:

                                    <assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0"/>

                                    They also include a fixed version attribute, which seems to be a generalized practice. J2EE descriptors also use that:
                                    <web-app xmlns="http://java.sun.com/xml/ns/j2ee" version="2.4"/>

                                    URNs are not hierarchical (just like Java packages), making them better choices for namespace names. However, the syntax seems to be confusing for the reader unfamiliar with the differences between them and URLs (see this topic).

                                    With this in mind, another alternative is:
                                    namespace: urn:jbpm-org:jpdl-3.0
                                    url: http://jbpm.org/jpdl-3.0.xsd
                                    
                                    namespace: urn:jbpm-org:jpdl-3.1
                                    url: http://jbpm.org/jpdl-3.1.xsd

                                    What do you think?

                                    1 2 Previous Next