International Federation of Digital Seismograph Networks
Thread: stationXML version 1.1 and fdsnws/station service version 1.x
Philipp Kästli
Dear colleagues of FDSN WG3,
Our last fdsnws/station specification is 1.2 and dates (content-wise) of April 2, 2019 (an update in June refers to the formatting of the standards document only).
According to this document, the fdsnws/station response format is “StationXML” (or text), without indication of the version, and thus, implicitly, referring to StationXML 1.0
On May 3, 2019, FDSNwg 3 published a new version 1.1 of StationXML.
John and Chad describe the the compatibility situation as follows:
“Additionally, a number of backwards-compatible changes suggested at previous meetings and on the project site were incorporated. Conforming to the versioning rules, all 1.0 version documents are also compliant with schema version 1.1, with one exception: the <StorageFormat> element was removed from the schema, but is not widely used and not expected to cause incompatibility.”
We would summarize this as follows:
- stationXML 1.0 remains forward-compatible with 1.0, thus an “old” xml document is still readable for software implemented for the 1.1 format (with the exception mentioned)
- stationXML 1-1 is not backward-compatible with 1.1, thus a new document violates the old specification and is not readable for software implemented against the 1.0 specification.
This has implications on the fdsnws/station/1/ web service. The standards document v. 1.2 says the following on service versioning:
“Web service implementations are versioned according the following three-digit (x.y.z) pattern:
SpecMajor . SpecMinor . Implementation Where the fields have the following meaning:
SpecMajor : The major specification version, all implementations sharing this SpecMajor value will be backwards compatible with all prior releases. Values start at 1. “
And
“The following base URI pattern is to be used at each data center implementing FDSN services: <site>/fdsnws/<service>/<majorversion>/”
Thus, an FDSNWS user can expect that if she/he has implemented an fdsnws-station client according to the standard (thus, capable of digesting the stationXML of the time, e.g. 1.0), this client will never break, as long as she/he addresses the service under the same url …/fdsnws/station/1/… .
An updated service with a non-backward-compatible response should have a different url …/fdsnws/station/2/…
So, at the time being, it violates the fdsnws/station v. 1.x standard, and the justified expectation of some users, if a service fdsnws/station/1/ 1.x service returns the new stationXML 1.1 format.
(at the same time, an fdsnws/station service provider of 2020 may, when reading the fdsnws/station/1/ specification, may not pay attention that it pre-dates the stationXML 1.1 version, and consider returning that very format)
Proposed way out:
- have a new fdsnws/station/1/ specification version 1.2(.1) with the only change that it explicitly says that it is referring to stationXML 1.0 as its response format
- have a fdsnws/station/2/ specification 2.0 saying that the response format is 1.1 or any backward compatible upper version
Kind regards,
Daniel Armbruster
Philipp Kästli
Swiss Seismological Service @ ETHZ
Our last fdsnws/station specification is 1.2 and dates (content-wise) of April 2, 2019 (an update in June refers to the formatting of the standards document only).
According to this document, the fdsnws/station response format is “StationXML” (or text), without indication of the version, and thus, implicitly, referring to StationXML 1.0
On May 3, 2019, FDSNwg 3 published a new version 1.1 of StationXML.
John and Chad describe the the compatibility situation as follows:
“Additionally, a number of backwards-compatible changes suggested at previous meetings and on the project site were incorporated. Conforming to the versioning rules, all 1.0 version documents are also compliant with schema version 1.1, with one exception: the <StorageFormat> element was removed from the schema, but is not widely used and not expected to cause incompatibility.”
We would summarize this as follows:
- stationXML 1.0 remains forward-compatible with 1.0, thus an “old” xml document is still readable for software implemented for the 1.1 format (with the exception mentioned)
- stationXML 1-1 is not backward-compatible with 1.1, thus a new document violates the old specification and is not readable for software implemented against the 1.0 specification.
This has implications on the fdsnws/station/1/ web service. The standards document v. 1.2 says the following on service versioning:
“Web service implementations are versioned according the following three-digit (x.y.z) pattern:
SpecMajor . SpecMinor . Implementation Where the fields have the following meaning:
SpecMajor : The major specification version, all implementations sharing this SpecMajor value will be backwards compatible with all prior releases. Values start at 1. “
And
“The following base URI pattern is to be used at each data center implementing FDSN services: <site>/fdsnws/<service>/<majorversion>/”
Thus, an FDSNWS user can expect that if she/he has implemented an fdsnws-station client according to the standard (thus, capable of digesting the stationXML of the time, e.g. 1.0), this client will never break, as long as she/he addresses the service under the same url …/fdsnws/station/1/… .
An updated service with a non-backward-compatible response should have a different url …/fdsnws/station/2/…
So, at the time being, it violates the fdsnws/station v. 1.x standard, and the justified expectation of some users, if a service fdsnws/station/1/ 1.x service returns the new stationXML 1.1 format.
(at the same time, an fdsnws/station service provider of 2020 may, when reading the fdsnws/station/1/ specification, may not pay attention that it pre-dates the stationXML 1.1 version, and consider returning that very format)
Proposed way out:
- have a new fdsnws/station/1/ specification version 1.2(.1) with the only change that it explicitly says that it is referring to stationXML 1.0 as its response format
- have a fdsnws/station/2/ specification 2.0 saying that the response format is 1.1 or any backward compatible upper version
Kind regards,
Daniel Armbruster
Philipp Kästli
Swiss Seismological Service @ ETHZ
-
Jean-Marie Saurel
2019-12-05 09:06:29Hello Philipp and Daniel,
* As you recalled, the 1.1 changes are mostly the addition of tags that
were not present in 1.0 version.
Thus a code reading and expecting 1.0 version document should not break
and will just ignore the 1.1 additional tags.
Furthermore, the only tag present in version 1.0 that is missing for
sure in 1.1 version, the StorageFormat, was not mandatory in 1.0 version
(minoccurs=0).
So even this won't break a 1.0 version client which should not expect
the presence of this tag in any 1.0 stationXML.
* The only problem I could see is the StageGain from ResponseStage type.
In 1.0 version, this StageGain is mandatory for any type of Response,
including Polynomial response.
In 1.1 version, this StageGain is still mandatory for any type of
Response, with the exception of the Polynomial response for which it is
forbidden.
I admit that a stationXML 1.1 with a polynomial response would
effectively break a 1.0 compliant client.
But then, for a polynomial response, 1.0 representation is simply wrong.
I would favor a quick move toward the 1.1 version, keeping
fdsnws-station 1.2 standard, than allowing to keep a broken (for
polynomial responses) 1.0 version available.
Regards.
Jean-Marie Saurel.
Le 28/11/2019 à 15:02, "Philipp Kästli <kaestli<at>sed.ethz.ch>"@fdsn.org a
écrit :
Dear colleagues of FDSN WG3,
--
Our last fdsnws/station specification is 1.2 and dates (content-wise) of
April 2, 2019 (an update in June refers to the formatting of the
standards document only).
According to this document, the fdsnws/station response format is
“StationXML” (or text), without indication of the version, and thus,
implicitly, referring to StationXML 1.0
On May 3, 2019, FDSNwg 3 published a new version 1.1 of StationXML.
John and Chad describe the the compatibility situation as follows:
“Additionally, a number of backwards-compatible changes suggested at
previous meetings and on the project site were incorporated. Conforming
to the versioning rules, all 1.0 version documents are also compliant
with schema version 1.1, with one exception: the <StorageFormat> element
was removed from the schema, but is not widely used and not expected to
cause incompatibility.”
We would summarize this as follows:
-stationXML 1.0 remains forward-compatible with 1.0, thus an “old” xml
document is still readable for software implemented for the 1.1 format
(with the exception mentioned)
-stationXML 1-1 is *not* backward-compatible with 1.1, thus a new
document violates the old specification and is not readable for software
implemented against the 1.0 specification.
This has implications on the fdsnws/station/1/ web service. The
standards document v. 1.2 says the following on service versioning:
“Web service implementations are versioned according the following
three-digit (x.y.z) pattern:
SpecMajor . SpecMinor . Implementation Where the fields have the
following meaning:
SpecMajor : The major specification version*, all implementations
sharing this SpecMajor value will be backwards compatible with all
prior releases.* Values start at 1. “
And
“The following base URI pattern is to be used at each data center
implementing FDSN services: <site>/fdsnws/<service>/*<majorversion>*/”
Thus, an FDSNWS user can expect that if she/he has implemented an
fdsnws-station client according to the standard (thus, capable of
digesting the stationXML of the time, e.g. 1.0), this client will never
break, as long as she/he addresses the service under the same url
…/fdsnws/station/*1*/… .
An updated service with a non-backward-compatible response should have a
different url …/fdsnws/station/2/…
So, at the time being, it violates the fdsnws/station v. 1.x standard,
and the justified expectation of some users, if a service
fdsnws/station/1/ 1.x service returns the new stationXML 1.1 format.
(at the same time, an fdsnws/station service provider of 2020 may, when
reading the fdsnws/station/1/ specification, may not pay attention that
it pre-dates the stationXML 1.1 version, and consider returning that
very format)
Proposed way out:
-have a new fdsnws/station/1/ specification version 1.2(.1) with the
only change that it explicitly says that it is referring to stationXML
1.0 as its response format
-have a fdsnws/station/2/ specification 2.0 saying that the response
format is 1.1 or any *backward* compatible upper version
Kind regards,
Daniel Armbruster
Philipp Kästli
Swiss Seismological Service @ ETHZ
----------------------
FDSN Working Group III
Topic home: http://www.fdsn.org/message-center/topic/fdsn-wg3-products/ | Unsubscribe: fdsn-wg3-products-unsubscribe<at>lists.fdsn.org
Sent from the FDSN Message Center (http://www.fdsn.org/message-center/)
Update subscription preferences at http://www.fdsn.org/account/profile/
--------------------------------------
Institut de Physique du Globe de Paris
Observatoires Volcanologiques et Sismologiques
+33 1 83 95 74 37
+33 6 20 35 28 04 (portable)
1 rue Jussieu
75238 Paris cédex 5