XSD Schema Versioning and Naming

[jimrigsbee]

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

[tom.baeyens]

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.

[jimrigsbee]

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

[koen.aers]

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

[aguizar]

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

[koen.aers]

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

[tom.baeyens]

"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.

[tom.baeyens]

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.

[tom.baeyens]

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

regards, tom.

[jimrigsbee]

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

[tom.baeyens]

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.

[aguizar]

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.

[tom.baeyens]

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.

[tom.baeyens]

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

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

regards, tom.

[aguizar]

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?