International Federation of Digital Seismograph Networks

Thread: stationXML version 1.1 and fdsnws/station service version 1.x

None
Started: 2019-11-28 15:00:53
Last activity: 2019-12-05 09:06:29
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

  • Hello 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