General Timestamp API

NTF’s General Timestamp API Consortium exists to foster the development and implementation of a new “general timestamp” structure, and a portable and efficient API library built around this new structure.


The information contained in a current timestamp is usually a date and time, sometimes with fractional seconds. This has usually worked because the folks who take them know the context in which the timestamp was taken. Usually.

But there are problems with this approach. It may be that the time is being corrected, and the reported time is known to be “off”. The system clock may be a bit fast or slow, and if it’s been a while since the clock was synchronized the time may have “drifted”. Put another way, there is no indication of the amount of error that may have accumulated since the clock was last synchronized with a believable time source.

Usually, the “timescale” that we see most often is UTC, Coordinated Universal Time. Was the time stamp taken from a system that uses UTC? If so, what timezone was in use? TAI, International Atomic Time, is another timescale that is in common use. Navigational satellite systems like GPS use TAI. UTC has leap-seconds, which are designed to keep our “wall clocks” aligned with solar time. Solar time keeps the sun at its highest point in the sky at noon. Which timescale was being used by the system?

The system clock has to play by some strict rules. Have you ever thought about what might go on when making an airplane seat reservation? There are a limited number of seats, and as the plane fills up there are often more folks interested in taking a flight than there are seats on the plane. When it gets down to the wire, the first person who asks for a seat gets it, but that reservation is not “completed” until the order is actually placed and the ticket is paid for. If the person decides to take a different flight, their reservation is “released”. In order for this system to work, the underlying “database system” relies on timestamps that must always “move forward”. If the system clock is running slowly for some reason, it’s OK to “jump” the clock forwards to correct this difference. But if the system clock is fast or running ahead, the clock cannot “jump” backwards, because that would break the rules about relying on who got the reservation first. There are ways to handle correcting for this situation, but it’s a bit tricky and complex to do in a way that doesn’t cause problems in other areas.

The good news about the current style of timestamp is that it’s very easy to use. The bad news is that the current style of timestamp doesn’t contain enough information to be particularly useful.

About the General Timestamp API

With some careful thought, one can come up with a new type of timestamp that contains all the information one might need. But just having a new timestamp format is only part of the problem. Before a new timestamp format can be really useful there has to be an easy way to work with it. This means providing an efficient and portable library to “work” with these timestamps. The sort of work we’re talking about includes arithmetic, adding or subtracting timestamps; comparing timestamps; and converting timestamps from one timescale to another.

There are two aspects to the General Timestamp project. One is the definition of a new “timestamp structure” that will contain enough information to be much more generally useful. The second aspect is an efficient and portable library API that will operate on these timestamps - arithmetic on, and conversion and comparison of these new timestamps.

The new timestamp structure will include things like the time, any known expected correction to “true” time, error measurements, the timescale used, and other similar information. More information about this can be seen here, and better still would be to join and participate in the General Timestamp API Consortium.