mandatory ‘version’ attribute

[bic-org-uk]

mandatory ‘version’ attribute

[franciscave]

I clearly forgot to include the attribute when I originally drafted the XSD. That was sloppy, but that has fortuitously put us in the current position where we have the option of removing the attribute entirely from the documentation, or making it optional and/or relaxing the value constraints.

Given that the XML binding is not specific to the REST implementation, I think we do need a mechanism for including the LCF version number in the XML payload. There are two ways we could do this:

• with an attribute
• in a namespace URI

The XML binding documentation also states the following:

 "The namespace for these XML bindings is "http://ns.bic.org.uk/lcf/1.0"."

But there is no namespace in the XSD.

So, I think we need to do three things:

• add a namespace URI to the XSD, and I suggest that the one in the documentation is fine, since the namespace should only change with a major (non-backwards-compatible) version number change.
• change the XML binding documentation to indicate that the version attribute is not mandatory, and add documentation to indicate that we recommend that the version attribute be included to indicate that the XML contains features that were introduced in the specified (minor) version of LCF, e.g. version="1.0.1"
• update the XSD to include the optional attribute, with data type 'xs:string' and no constraints on its value, as it is really provided for information rather than for validation against a schema.

[mdovey]

Ah, I'd not noticed the missing namespace as if you generate code from the jxb file, the entities schema inherits the namespace from the rest response schema (where the target namespace is specified).

In terms of not backwards compatible some of the schema changes we have introduced in 1.0.1 are not backwards compatible (e.g. the additional patron fields) - an (admittedly hypothetical) 1.0 client doing strict schema validation would reject a 1.0.1 patron entity.

[anthonywhitford]

If the understanding is that the version needs to be in the XML response in some manner, I'd go for the namespace, simply because it should keep it inline with the content in the URL, which already includes the v1.0 version. I don't see value in repeating the same information that is in the URL invoked, and (can be) in the namepace, by putting it in an element too.

[mdovey]

Firstly I think the version attribute should either be mandatory or dropped entirely. If a client or server cannot rely on it being present then it doesn't serve any purpose.

The documentation currently uses a version number of x.y.z whereas the schema namespace and REST URL prefix uses x.y. So the question is whether a client or server needs to know the full x.y.z version in use as opposed to the x.y version. I suspect not, and the .z is meant to be used to indicate errata, clarifications. Functional changes should involve a change of the x.y version.

Strictly speaking the changes we are introducing and currently labelling at 1.0.1 are functional changes and we should really be labelling these as 1.1. However, this might be overkill at the moment since there are no production 1.0.0 implementations.

[franciscave]

Yes, I had taken the view that to change from v1.0 to v1.1 before there are ANY implementations would be overkill and could frighten the horses.

We can drop the attribute entirely.

[franciscave]

The 'version' attribute has now been removed from the entity XML bindings and from the REST specification.

[anthonywhitford]

change merged