How to specify leap seconds in metadata

The standards.md document currently states:

Structure is:

time: 2016-082T23:59:60Z
type: +
description: Positive leap-second (a 61-second minute)
correction_data:
    - msmod --timeshift -1 -ts 2016,182,23:59:59.999999
    - msmod --actflags ‘4,1’ –tsc 2016,182,23:59:59.999999 –tec 2016,182,23:59:59.999999
correction_end_sync_instrument: subtracted one second from displayed instrument time

only time and type are required

[REC {/}] Embedded in a StationXML <Comment>. Possible future namespace element, as for clock drift. Below is a StationXML example

<Comment subject=”Leap Second”>
<Value>“{time: 2016-082T23:59:60Z, type: '+', description: 'Positive leap-second (a
61-second minute)', correction_data: ['msmod --timeshift -1 -ts 2016,182,23:59:59.999999', ' msmod –actflags ‘4,1’ –ts 2016,182,23:59:36 –te 2016,183,00:00:36'], correction_end_sync_instrument: subtracted one second from displayed instrument time"</Value>
</Comment>

I suggest a change to

Structure is:
leapseconds:
    values:
       - 
          list_file_strings: "3692217600      37      # 1 Jan 2017"
          type: "+"
   corrected_in_basic_miniseed: false
   corrected_in_syncs_instrument: true
values is an array/list, to allow for more than one leap-second during a deployment.

list_file_string should be directly copied from leap-seconds.list, which is available online at several sites, including https://data.iana.org/time-zones/tzdb/leap-seconds.list. The user should verify that the "File expires on" date is later than the last instrument channel's end-date.

type indicates whether the second number in the list_file_string is greater than the previous line's value ("+") or less than the previous line's value ("-"). As of June 2024, all leap seconds have been type "+"

corrected_in_basic_miniseed indicates whether the "raw" miniSEED data (if any) correctly integrates the leap second. For most OBS deployments, this value should be false as dataloggers without GPS don't (yet?) have a way to integrate leap seconds.

corrected_in_syncs_instrument: indicates whether the instrument sync times have been corrected for the leap second(s). They should generally be, but in some cases (many sync times and/or more than one leap second) this may be best left to an algorithm that inputs these values than to a human operator.

[REC {/}] The information should be embedded in a StationXML <Comment> with subject='Clock Corrections'. This is a possible future namespace element (see #1 ), as is clock drift. Below is a StationXML example
<Comment subject=”Clock Corrections”>
<Value>“{leapseconds: {values: [[list_file_string: '3692217600      37      # 1 Jan 2017,' type: '+']],   
                       corrected_in_syncs_instrument: true,
                       corrected_in_basic_miniseed: true}"</Value>
</Comment>

The advantages of the proposed changes are:

Simpler entry of leap-second values by the user, with less need for interpretation
Clearer information about what has been corrected and what has not
A clearer tie to the drift-based clock corrections (changing subject to "Clock Corrections", which would be shared with the drift-based clock corrections

I removed the information about how the leap second was corrected because it seems like a lot of information for the user to enter. The standards.md document should still include this information as a recommendation for data file processing

It may be wise to also change the structure of the clock drift corrections to something like:

     drift:
        type: "linear"
        start_sync_reference: "2016-09-10T00:00:00Z"
        end_sync_reference: "2017-07-13T11:25:00.6189Z"
        end_sync_instrument: "2017-07-13T11:25:01Z"

and also use subject="Clock Corrections" in the associated StationXML< Comment>. This would give a clearer hierarchy in the StationXML file

FDSN / OBS-standards

How to specify leap seconds in metadata #17