# Versions and time zones

> Work with the .well version field and the well site time zone using WELL_FORMAT_VERSION, parseFormatVersion, compareFormatVersions and isIanaTimeZone.

## The version this library writes

```ts
import { WELL_FORMAT_VERSION } from '@welldot/core';

WELL_FORMAT_VERSION; // '2.4'
```

`serializeWell` always writes this version. `parseWell` reads `1`, `2` and any `"2.x"` ([Versions and deprecation](/format/concepts/versions-and-deprecation)).

## Parsing and comparing versions

Since 2.4 the version is the string `"M.m"`, compared as two integers ([Versioning](/format/spec/v2/format-reference#versioning)). Never compare version strings as text: `"2.10"` sorts before `"2.9"` as text but is the later revision.

```ts
import { compareFormatVersions, parseFormatVersion } from '@welldot/core';

parseFormatVersion('2.4'); // { major: 2, minor: 4 }
parseFormatVersion(2); // { major: 2, minor: undefined }, a v2.0–v2.3 file
parseFormatVersion(2.4); // undefined: a JSON number is malformed
parseFormatVersion('2.4.1'); // undefined: patch levels are not allowed

compareFormatVersions('2.10', '2.9'); // 1 (positive: the first is later)
```

`parseFormatVersion` returns `undefined` for every malformed form, so you can report the value to the user as the spec requires ([parser version handling](/format/spec/v2/format-reference#parser-version-handling)). `compareFormatVersions` throws on malformed input.

A typical check before writing to a shared archive:

```ts
import { WELL_FORMAT_VERSION, compareFormatVersions } from '@welldot/core';

const archiveReads = '2.3'; // the newest revision your readers support
if (compareFormatVersions(WELL_FORMAT_VERSION, archiveReads) > 0) {
  console.warn(
    `This tool writes ${WELL_FORMAT_VERSION}; update the readers first.`,
  );
}
```

## The well site time zone

Permit deadlines and validity are judged on the local calendar date at the well. Since 2.4, `location.properties.timezone` stores the site's IANA time zone, and the local date of an instant is that instant converted to the zone ([datetime conventions](/format/spec/v2/format-reference#datetime-conventions)).

```json
"location": {
  "lat": -1.4558,
  "lng": -48.5039,
  "properties": { "timezone": "America/Belem" }
}
```

A value that is not an IANA name is malformed. Check it before writing:

```ts
import { isIanaTimeZone } from '@welldot/core';

isIanaTimeZone('America/Belem'); // true
isIanaTimeZone('-03:00'); // false: offsets are not time zones
isIanaTimeZone('BRT'); // false
```

`@welldot/utils` uses the zone for local dates (`instantLocalDate`, `getWellTimeZone`) and warns with `missing_timezone` when a file has permit condition fulfillments but no zone ([Permits](/utils/guides/permits)).