fdsn / stationxml Goto Github PK

Station has Equipment as a subelement with
minOccurs="0" maxOccurs="unbounded"

But in Channel, the Equipment subelement only has
minOccurs="0"
which makes it zero or one.

The purpose of the Equipment is to allow information about hardware that may be associated with the Channel, but does not fit into the other catagories (Sensor, PreAmplifies, DataLogger). There could be multiple pieces of Equipment, and so this should be allowed to be more than one.

Channel → Type seems to be a bucket to put something that exists in SEED, but isn't really meaningful anymore. It more or less duplicates the information in the channel instrument code from what I can tell.

Perhaps should consider either removing this, or making it more meaningful.

Good to document whether Created contains date the document was generated or last modification.

For most stationxml which are generated, for example fdsn web services, it is expected that they file will not change once created. But xml is just a text file, so editing is possible. Updating the date on modification is probably the correct thing to do.

This is from an old post to iris web services list, but I just stumbled into this issue again, so just putting it here so not forgotten if/when there is a stationxml revision.
http://ds.iris.edu/message-center/thread/1450/

Are there any guildlines for how the name of a unit in FDSNStationXML should be formed? Other than "do it like SEED"?

I know the unit says it is the same as SEED blockette 34, but the SEED spec says use SI but use all uppercase, which contradicts the SI convention that case matters. So for example with prefixes m is milli and M is mega, and for units g is gram while G is gauss and s is second while S is siemens. I suppose most of seismology is covered by volt, meter, second and count, but there are more and more types of data begin recorded at seismic stations and so more varieties of units we need to support. And at some point it would be nice to get away from a "formatted as FORTRAN-like equations with all alphabetic characters in upper case" way of writing units and make us of the existing standards for better portability and exchange within and outside of seismology. It seems sad that the units are still just unstructured strings that make it challenging for code to parse and correctly interpret. Following something like this might be useful:
http://physics.nist.gov/cuu/Units/

Follow up question, there are seemingly two types of "units" in FDSNStationXML, one used as an element and one as an attribute. The element one, UnitType, appears to say follow the SEED convention, so you have units with names like M/S, M and V. The unit attribute on FloatType is just a string with no documentation on how it is to be used, but looking at concrete uses of it in for example SecondType, VoltageType and DistanceType, it appears that the string should be things like SECONDS, VOLTS and METERS. So we have two different ways of specifying units in FDSNStationXML with different naming conventions.

Perhaps even more confusing, the SampleRateType specifies the fixed unit string as SAMPLES/S, and which combines both unit naming conventions.

Can you clarify the unit naming scheme? I would like to be able to parse the units, but it is much harder if there is not a clear mapping from unit to/from strings.

Is this something that might be unified/simplified in a future version?

Also, should
Delay and Correction in DecimationType be SecondType?
Amplitude in ResponseListElement and Numerator and Denominator in CoefficientsType be FloatNoUnitType as the units are in the enclosing element?
NumeratorCoefficient be FloatNoUnitType (or FloatType) to be like CoefficientsType?

In Channel the description of historicalCode is:

LevelDefault:A previously used code if different from the current code

which is probably not what was meant.

Dear all

I convert dataless SEED in StationXML with the java tool of iris : stationxml-converter-1.0.9.jar. When I check the consistency of the StationXML with its schema (http://www.fdsn.org/xml/station/fdsn-station-1.0.xsd), I can see erros in polynomial responses because a Stagegain is mandatory (<xs:element name="StageGain" type="fsx:GainType">).
It doesn't really make sense to me to add a StageGain to a polynomial response. What is the movivation for that?
I am wandering if it is a bug because the documention tell us

This complex type represents channel response and covers SEED blockettes 53 to 56

thougth this is the blockette 62 which describes polynomial reponses.
Thus the polynomial response may have been added in the schema without entertainning this difficulty?

many thanks for your answers
arnaud lemarchand
volcano observatories of IPGP
France

I think attributes need quoting, but the examples sometime do and sometimes don't.

For example in Network the is

code=’IU’

but also

endDate=2018-01-27T00:00:00

I believe all attributes should be quoted, so should be:

endDate='2018-01-27T00:00:00'

I can see no advantage to allowing a PersonType to have multiple names. Everywhere that PersonType is used, it is already in a list, so if multiple people need to be there, they should each be a separate Person.

In the current documentation of Station XML there are some deprecation warnings for some (currently few) elements.

I would suggest to group all these deprecation warnings and possibly also other upcoming/expected changes, like switch from required <-> non required, count rules, etc. in a dedicated section. This would help new with new implementations.

The station.operator[.agency] and network.operator[.agnecy] definitions are not very clear.
We should have a better description of what is expected.

Besides, it is unclear how network.operator and station.operator work together.
Are rhe operators of a station the concatenation of the network's operators and the station operators ? Or are the operators field in the network and station unrelated and station.operator should present a complete list of the operators ?

Given the volume of historical metadata, we will have to live with all the variations of count, but now would be a good time to establish that the singular, lowercase count is the preferred unit for digitized data. SI units are singular, and case sensitive, and so I think count is the most consistent value. What is put in the documentation will guide people going forward, and so we should give a nudge in the direction of consistency.

Would be good if all count unit examples were given in singular lower case.

Perhaps also adding something to section 5.4 would help standardize this.

If a channel has no known response/sensitivity, the spec should define how to encode this. Usages might be both it is should be known but isn't, or where it is undefinable, like a textual LOG channel. Currently there are many options, all of which exist or have existed on servers.

Options:

1. Do not have a <Response> element on the channel
2. An empty <Response> element
3. An empty <InstrumentSensitvity> inside a <Response> (but invalid xml)
4. An obviously wrong <InstrumentSensitivity>like:

<Response>
  <InstrumentSensitivity>
    <Value>0.0</Value>
    <Frequency>0.0</Frequency>
    <InputUnits>
      <Name>NULL</Name>
      <Description>NULL</Description>
    </InputUnits>
    <OutputUnits>
      <Name>COUNTS</Name>
      <Description>Digital Counts</Description>
    </OutputUnits>
  </InstrumentSensitivity>
</Response>

For a client, having to deal with all of these variations as effectively meaning the same thing is kind of a pain and so would be really useful if the spec and/or schema would pick one representation of unknown/undefined and mandate it.

stationxml examples often use all caps units, but docs also say SI units are preferred. Better if the examples follow the SI standard where possible.

Example accelerometer response:

            <InputUnits>
              <Name>M/S**2</Name>
              <Description>Acceleration in Meters Per Second Per Second</Description>
            </InputUnits>

should be lower case m/s**2 instead.

Will there be an element in FDSN StationXML to explicitly store the digital object identifier?

CounterType is defined as non-negative integers, which is right for things like SelectedNumberChannels, but is not right for things like Stage number, as in stationxml this should never be zero. Similar for Numerator number in filters subelements within Coefficients, PolesZeros, etc.

Create a new type, perhaps EnumerationType, and use when the number should start at one. This also allows documentation that this value should increase and not skip numbers within an element, so Stages should be numbered 1,2,3,... and not 0,5,7,...

Something like:

<xs:simpleType name="EnumerationType">
<xs:annotation>
<xs:documentation>Integers greater than or equal to 1 for enumerating list of items. Should start at 1 and increase by one for each item in the list.</xs:documentation>
</xs:annotation>
<xs:restriction base="xs:integer">
<xs:minInclusive value="1"/>
</xs:restriction>
</xs:simpleType>

Currently Stage number says:

Start from name=’1’ and iterate sequentially.

but should be

Start from number=’1’ and iterate sequentially.

Datetime description is confusing:

Integer values used to represent the year, day, hours, minutes. Decimals represent seconds, a boolean represents the timezone.

What is a boolean timezone? This also doesn't say how the integers are to be combined. Very confusing.

Should also say instead that it is ISO 8601 string, give a link to the ISO spec or perhaps the W3C xschema spec. I think at some point it was preferred to be one of a limited versions of the ISO spec, so perhaps limit to a few like: YYYY-MM-DDThh:mm:ss.SSSSSSZ, YYYY-MM-DDThh:mm:ssZ, YYYY-MM-DDThh:mm:ss.SSSZ, YYYY-MM-DDZ,

Add a sentence that using times in UTC is preferred, and that the Z timezone identifier should be appended to as processing systems often interpret times without timezones as local time. Appending the Z helps eliminate a common source of error.

It should have an example.

Add sentence to section 5.4 to state that the short, abbreviated unit name is preferred over full words, so that m/s is preferred over meter/second. The later is verbose, doesn't add any clarity, and having two ways to specify the same thing is usually worse than just one.

Guidance in the docs will help in the future, even though we will have to live with crazy SEED unit names for a long time to come.

Network uses startDate and endDate as attributes

Network Comment uses BeginEffectiveTime and EndEffectiveTime as elements.

DataAvailability Extent uses start end as attributes.

Equipment uses InstallationDate and RemovalDate as elements.

All basically serve the same purpose but have different representations. Probably too late for this, but would be really nice if the start and end dates of a "thing" were always represented in the same way.

The only indication in the docs that something is a subelement of something above it is the lack of the section number in front of it. And for sub-sub elemnts there really isn't anything.

Some kind of indentation, or containment box so it is visually easy to see what is contained in what would be useful.

Good example is Station → Operator → Contact → Phone → PhoneNumber which is followed by Station → Operator → WebSite. Visually they look like they are on the same level, but PhoneNumber is 3 levels down in the hierarchy.

The sourceID parameter (BaseNodeType used for Network, Station, and Channel) should recommend the FDSN Source Identifiers: http://docs.fdsn.org/projects/source-identifiers/en/v1.0/

Example:
http://docs.fdsn.org/projects/stationxml/en/latest/reference.html?highlight=sourceID#network-required

Examples show stations like BK.ANMO, which isn't a real station, even though BK is a real network and ANMO is a real station in another network.

I think this is confusing, and potentially scatters stationxml around that is valid and looks legitimate but wrong.

Examples that are made up should use the XX network code so it is clear that they are not real. Perhaps also use station code ABCD if a placeholder station is needed. If you choose to use real world examples, then use the real codes.

Example in section 3.2.4 is not valid as <Stage> must contain one of <PolesZeros>, <Coefficients>, <ResponseList> or <FIR>.

Validating examples, see #58 , would of course help catch this type of issue.

Hi - we have some records with azimuth values of 360. According to the SEED manual p68:

"Traditionally, the mass (boom) on vertical seismometers is oriented to the north, but sometimes this is not possible. If you know the vertical orientation, place it in the azimuth field. If the orientation is 0 degrees, use an azimuth of 360.0. If you do not know the orientation, set the azimuth to 0.0.”

Can we change the schema to permit 360 as value -- currently it is excluded.

Examples probably should not use actual entities, especially copyrighted ones.

For example, Agency has:

Example: <Agency>Mad Magazine, Inc.</Agency>

and as much as I like a little humor, the actual owners of Mad magazine might not appreciate being used in an FDSN specification.

The FDSNStationXML doesn't indicate that it contains Network elements. And nothing in the Network docs indicate it should be contained in the FDSNStationXML. Similar for Station, Channel and Response.

Fine to have the Network, Station, etc exist as separate subsections, but something within the docs for each should indicate the containment hierarchy.

Historically SEED used a date far in the future, like 2500-01-01, to indicate a active network, station or channel. In stationxml since the endDate attribute is optional, it is better to indicate something is still active by not having an endDate attribute rather than picking a future date. Docs should make this clear.

Incorporate the new FDSN source-identifiers into stationXML, perhaps either as a new attribute on network/station/channel, or within the existing Identifier elements.

http://docs.fdsn.org/projects/source-identifiers/en/v1.0/

There are many cases, preamp gain-only stages as well as many SOH channels, where there is no known frequency dependency to the response. Often these are represented by a Stage with only a StageGain, but this means that there is no place to put the input and output units, and the client is left to guess them based on the preceding and following stages. And this is a problem if there is only one stage.

Adding a Unity filter that simply extended BaseFilterType to hold the units would make working with these types of stages easier and clearer as well as making it easier to force units to be specified within the schema.

Related to #20

Mathematically, a Coefficients filter has to have at least one numerator, which can be 1. Otherwise the output time series would be all zeros.

A no-coefficient Coefficient filter might be used to just be a container for units, but this should be discouraged. Requiring at least one numerator would force using of at least a single coefficient, even if it is 1.

Change:

<xs:element name="Numerator" minOccurs="0" maxOccurs="unbounded">

to

<xs:element name="Numerator" minOccurs="1" maxOccurs="unbounded">

Similarly a FIR filter should have at least one NumeratorCoefficient so change

<xs:element name="NumeratorCoefficient" minOccurs="0" maxOccurs="unbounded">

to

<xs:element name="NumeratorCoefficient" minOccurs="1" maxOccurs="unbounded">

This is likely not the right place to report this, but I don't know where else to put it.

The network citation lookup tool gives really weird output in some cases, even for network DOIs minted directly on FDSN web site:

CC @jwassermann

There are two definitions of units in stationxml, FloatType uses a simple string attribute while UnitsType is an element (used in the InputUnits and OutputUnits in BaseFilterType and SensitivityType as well as CalibrationUnits in Channel ).

Would be better if there was a single style of "units" that was used in all places.

We are working on software to create StationXML files for ocean-bottom seismometer deployments. This work is in close collaboration with the new Atomic Response Object Library (AROL), and we dig deep into StationXML definitions. We are happy to see the StationXML documentation project and would like to offer a few questions about what we think are ambiguities in the present documentation.

All of our questions are beneath the <Stage> level:

<PoleZeros><Normalization Frequency>

The documentation says "should be the same for all stages and within the passband, if any"
Do you mean for all <PoleZeros> stages? (these are the only ones I know of with a <NormalizationFrequency>) or do you also include <StageGain><Frequency>s?

<StageGain><Frequency>:

There is no mention of a requirement for all <StageGain> frequencies to be equal: is this the case. Also, can <Frequency> = 0 be used for stages whose gain does not vary with frequency (this seems to be common usage)?

<Decimation><Offset>, <Delay> and <Correction>:

Our instruments correct the digital stages' delay at the software level. How should this be entered? We currently set <Correction> = 0 at all levels except the last, in which we put the entire correction value

How is <Delay> related to <Offset>? In the simplest cases, I would imagine that <Delay> = <Offset> / <InputSampleRate>, but I can imagine that for additional analog delays this would be otherwise. It would be nice if this were clarified.

Stages without a filter

How does one enter a stage without a filter? (pure amplifier, either on analog or digital end). Currently, I use:

• for an analog gain stage: a <PolesZeros> stage with empty <Pole>s and <Zero>s, <NormalizationFrequency> = None and <NormalizationFactor = 1.0>.
• for a digital gain stage: a <Coefficients> stage with <Numerator> = [1.0 ] and <Denominator> = [].

It would be useful to have a recommended formula for these cases or — even simpler for the user — <Analog> and <Digital> "filters" with no filter coefficients. Alternatively, one could remove the requirement of having a <Filter> in a <Stage>, but this might harm backward-compatibility

Regards,
Wayne Crawford [email protected] and Luis Arean [email protected]

Example with the lake elevation NOT being at sea level would be more useful.

Elevation of the water surface in meters for underwater sites, where 0 is mean sea level. If you put an OBS on a lake bottom, where the lake surface is at elevation=0, then you should set WaterLevel=0.

The docs show required when a subelement is required, which is good. But would also be very useful to show somewhere if the subelement has other cardinality. Currently you can't tell the difference between a subelement that is optional (minOccurs="0" and maxOccurs="1") and many (minOccurs="0" and maxOccurs="unbounded"). I don't think this happens in stationxml, but other variations like at least once (minOccurs="1" and maxOccurs="unbounded") are also possible.

Example is Channel Comment, which can be zero or more, but no indication is given in the docs.

Best if all examples pass the IRIS stationxml validator to avoid giving out examples that do not follow best practice. This would be easier if the examples were full stationxml, but is hard because the initial elements are abbreviated. Perhaps adding a download link to each example that was a complete stationxml file would be helpful.

For example, running validator on StationXML/docs/examples/kinemetrics_etna_fba-3.xml , which I think is used to generate the accelerometer example gives:

304,Error,BK,ANMO,BHZ,10,,,expected equipment/sensor but was null
320,Error,BK,ANMO,BHZ,10,,,Azimuth must be included for channels with H instrument values
402,Warning,BK,ANMO,BHZ,10,,,[stage 01] invalid input units M/S**2
402,Warning,BK,ANMO,BHZ,10,,,[stage 03] invalid output units COUNTS
402,Warning,BK,ANMO,BHZ,10,,,[stage 04] invalid input units COUNTS
402,Warning,BK,ANMO,BHZ,10,,,[stage 04] invalid output units COUNTS
402,Warning,BK,ANMO,BHZ,10,,,[stage 05] invalid input units COUNTS
402,Warning,BK,ANMO,BHZ,10,,,[stage 05] invalid output units COUNTS

Currently LatitudeBaseType has:

<xs:restriction base="fsx:FloatType">
<xs:minInclusive value="-90"/>
<xs:maxExclusive value="90"/>

which means that a station can be at the south pole, but not at the north pole.

Think that should be maxInclusive.

The description of the resourceId attribute of InstrumentPolynomial looks like it was copied from equipment, but doesn't make sense in here.

It should be expected that equipment with the same ID should indicate the same information/be derived from the same base instruments.

Also same in Stage

In Network the example for the code attribute has:

code=’IU’

which mostly looks correct, but the quote character used in the docs is a:

U+2019 : RIGHT SINGLE QUOTATION MARK {single comma quotation mark}

which is not the same as an ascii single quote (ascii 39). The ascii double quote (ascii 34) is also allowed in xml, but I do not think other fancy unicode quotes are allowed.

Someone that copy-pastes this will likely generate invalid xml.

Currently, LatitudeType and LongitudeType have:

<xs:attribute name="datum" type="xs:NMTOKEN" use="optional" default="WGS84"/>

saying that if I do not specify a datum, it is WGS84. I have nothing against WGS84, but having a default value means that if I know I am using WGS84 my stationxml looks exactly the same as if I don't even know what a datum is. I doubt anyone checks this, but if the datum ever did matter, there is no way to know if it really is WSG84 or not.

In general, I think leaving a value out should either imply it doesn't matter, or the actual value is unknown. Removing the default value would make it clear that the datum is in most instances unknown, and if the metadata creators actually know the datum, they can optionally specify it.

This is completely separate from any arguments about whether or not a generic station lat/lon should be interpreted as WSG84 by systems using stationxml where the datum is not specified. But regardless the schema for metadata shouldn't actively make assertions about the datum without the consent and approval of the metadata creator.

Currently Network has default minOccurs, eg 1, and so a stationxml document that represents zero networks cannot be valid. Adding minOccurs="0" to Network would allow an empty result to be a valid document which is useful to represent the results of a processing step that filters out all networks.

I noticed that the minor version is not included in the namespace, i.e. 1.0 and 1.1 share the same namespace (http://www.fdsn.org/xml/station/1 -- with full version included as an attribute version="1.1") and thus it's not possible to add (removed) 1.0 tags as foreign tags in 1.1 documents (e.g. StorageFormat). Any thoughts on this? I'm used to namespaces including the full version number somehow (e.g. http://geofon.gfz-potsdam.de/ns/seiscomp3-schema/0.10), but no expert on normal practice in this domain by any means.

Currently the filters (PolesZeros, etc) have minOccurs=0 on each within ResponseStageType. This allows a Stage like:

          <fsx:Stage number="2">
            <fsx:StageGain>
              <fsx:Value>1.000000000000E+00</fsx:Value>
              <fsx:Frequency>1.000000000000E+00</fsx:Frequency>
            </fsx:StageGain>
          </fsx:Stage>

to be valid. However, the comments imply that this should not be allowed:

There should be one response per stage.

In addition, this also means that the Stage does not have input and output units, which are important in understanding the overall response.

I believe the minOccurs attributes are leftover from an earlier version and should be removed, disallowing a Stage with only a StageGain.

For cases where the stage really is only a gain, there should still be a placeholder, like a unity Coefficients filter to provide units and so it is clear what is meant.

All units should be SI.

example:
<xs:attribute name="unit" type="xs:string" use="optional" fixed="SECONDS/SAMPLE"/>

Obviously requires major version bump.

Also see:
iris-edu/stationxml-validator#94

Elevation and Depth both use DistanceType, but Waterlevel uses FloatType but is used similarly.

Change Waterlevel to be
<xs:element name="WaterLevel" type="fsx:DistanceType" minOccurs="0">

in this example, the units are given even though there is a default in the schema. It is overly verbose and I don't think this is a best practice.

It also uses non-SI unit names, which I think should also not be done in the examples.

      <Latitude unit="DEGREES">34.945911</Latitude>
      <Longitude unit="DEGREES">-106.457199</Longitude>
      <Elevation unit="METERS">1820.0</Elevation>

Lots of stationxml in the real world and in the examples contain units like:

             <InputUnits>
                <Name>M/S**2</Name>
                <Description>Acceleration in Meters Per Second Per Second</Description>
              </InputUnits>

              <InputUnits>
                <Name>V</Name>
                <Description>Volts</Description>
              </InputUnits>

            <OutputUnits>
              <Name>COUNTS</Name>
              <Description>Digital Counts</Description>
            </OutputUnits>

The use of a description for the commonly used units, especially when it is used over and over within the stationxml file, is verbose and adds nothing to understanding.

Add sentence to unit Description saying:

Description is only needed when the unit name is not a well know SI unit or there is need for clarification. Prefer not to use a Description for common units like m/s, m/s**2, count, etc.

Add sentence to Section 5.4 saying similar.

If triaxial channels (A,B,C) are (in contrary to 1,2,3) allowed to be non-orthogonal, then they probably cannot be described as coinciding with the edges of a cube (which is, afaiu, orthogonal by definition). If A,B,C are meant to be orthogonal as well, then i don't understand the difference to 1,2,3.

On left within Stage, the docs show:

<Polynomial> required

but Polynomial is not required in a Stage as it is within an <xs:choice>.

Background

In Geoscience Australia, we have been working on an AusArray Passive Seismic Imaging Project. We process and analyse seismic waveform data from both permanent and temporary stations.

Problem
Some seismic stations may have GPS clock drift problems.
We have been able to use a cross-correlation method to identify and determine the time drift amount for each date. Typically we get a CSV data like the following:

network, station, date, clock_correction_seconds
7D,DE43,2012-11-27,1.0398489013215846
7D,DE43,2012-11-28,0.9408504322549281
7D,DE43,2012-11-29,0.8418519631882714
7D,DE43,2012-11-30,0.7428534941216148
7D,DE43,2012-12-01,0.6438550250549583
7D,DE43,2012-12-02,0.5448565559883017
7D,DE43,2012-12-03,0.445858086921645
7D,DE43,2012-12-04,0.3468596178549885
7D,DE43,2012-12-05,0.247861148788332
……

What we want to do
to store this CSV data into the stationXML as a standard element, so that any user can retrieve this time correction data and apply it to the waveform time series in subsequent analysis.

My initial thought is to add an extra element in the station xml file - see the attached example file
modifiled_stationXML.txt

This can be done through python script using Obspy library
Then we can retrieve and use the csv data by python code:
 
from obspy import read_inventory
our_new_station_xml= 'modified_inventory_select.xml'
our_inv = read_inventory(our_new_station_xml)
csv_str = our_inv.networks[0].stations[0].extra.gpsclockcorrection.value

Then parse the csv_str data to get the last two columns (date, clock_correction_seconds) for further use.

Please help !!!

• Does this comply with the standard FDSN stationXML?
• Any tools to validate it against the xsd schema?

Xschema annotations are lax, allowing any well-formed XML. So there is no need to escape tags within the xschema document. Of course the documatation extractor should run an html char escaper over the text before publishing to html, but that should probably be done anyway.

For example this:

<xs:annotation>
    <xs:documentation>Name of the software module that generated this document.
    </xs:documentation>
    <xs:documentation>Example:&lt;Module&gt;SeisComp3&lt;/Module&gt;</xs:documentation>
</xs:annotation>

could be written instead as this, using < and > which is easier to read when looking at the rawschema:

<xs:annotation>
    <xs:documentation>Name of the software module that generated this document.
    </xs:documentation>
    <xs:documentation>Example:<Module>SeisComp3</Module></xs:documentation>
</xs:annotation>

Or could even be written with an new tag such as <example> which makes the documation extraction processing much easier.

<xs:annotation>
    <xs:documentation>Name of the software module that generated this document.
    </xs:documentation>
    <example><Module>SeisComp3</Module></example>
</xs:annotation>

This idea could also be used to replace the Regarding embedded documentation keywords by simply using attributes on the elements in the annotation. For example:

<xs:annotation>
        <xs:documentation>Comment text.</xs:documentation>
          <xs:documentation>LevelChoice:N Example:&lt;Value&gt;Temporary network deployment&lt;/Value&gt;</xs:documentation>
          <xs:documentation>LevelChoice:S Example:&lt;Value&gt;GPS CLock is unlocked&lt;/Value&gt;</xs:documentation>
          <xs:documentation>LevelChoice:C Example:&lt;Value&gt;Large number of spikes&lt;/Value&gt;</xs:documentation>
</xs:annotation>

could be written as:

<xs:annotation>
          <xs:documentation>Comment text.</xs:documentation>
          <xs:documentation LevelChoice="N"><Example><Value>Temporary network deployment</Value></Example></xs:documentation>
          <xs:documentation LevelChoice="S"><Example><Value>GPS CLock is unlocked</Value></Example></xs:documentation>
          <xs:documentation LevelChoice="C"><Example><Value>Large number of spikes</Value></Example></xs:documentation>
</xs:annotation>

or even better as

<xs:annotation>
          <xs:documentation>Comment text.</xs:documentation>
          <Example LevelChoice="N"><Value>Temporary network deployment</Value></Example>
          <Example LevelChoice="S"><Value>GPS CLock is unlocked</Value></Example>
          <Example LevelChoice="C"><Value>Large number of spikes</Value></Example>
</xs:annotation>

Using annotation of this style makes the documentation much easier to read in the raw form, makes editing and maintenance much easier, and is just nicer.