divejson 0.2.0__tar.gz

divejson-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,119 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  tests:
+    name: Tests and the vendored corpus
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        # The floor, a current version, and the one the applications that install this
+        # package run. 3.10's stricter datetime.fromisoformat is exactly the kind of
+        # thing only running the floor catches, and until 3.14 was in this matrix the
+        # converter had never been run on the interpreter its first consumer uses.
+        python-version: ["3.10", "3.12", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      # Editable, which is the install that has no `divejson/_schema/`: a `force-include`
+      # reaches a built wheel and not an editable install, so this leg is what exercises
+      # the vendored corpus as the schema's source. The `wheel` job below covers the other.
+      - name: Install the package
+        run: pip install -e ".[dev]"
+
+      - name: The tests pass
+        run: pytest
+
+      # The conformance runner over this repository's own copy of the corpus, exactly as
+      # the specification repository runs it over the original against a pinned release.
+      # `--strict`, so that a format this implementation reads and the corpus has no
+      # pairs for fails the build rather than warning into a log nobody reads.
+      - name: The vendored corpus conforms
+        run: divejson conform fixtures --strict
+
+  specification:
+    name: The vendored tree is the specification at SPEC_REF
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check the specification out at SPEC_REF
+        run: |
+          ref="$(tr -d '[:space:]' < SPEC_REF)"
+          echo "SPEC_REF=$ref" >> "$GITHUB_ENV"
+          git clone --quiet https://github.com/divejson/divejson.git "$RUNNER_TEMP/spec"
+          git -C "$RUNNER_TEMP/spec" checkout --quiet "$ref"
+
+      # A subset check, not an equality one: this repository may carry pairs and mapping
+      # documents the specification has not adopted yet, and that is how an adapter lands
+      # self-contained. What it may never do is *change* a file the specification owns —
+      # that always goes to the specification first, and comes back on the next pin bump.
+      - name: Every file the specification owns is byte-identical here
+        run: |
+          differing=0
+          while IFS= read -r file; do
+            if ! cmp -s "$RUNNER_TEMP/spec/$file" "$file"; then
+              echo "::error file=$file::differs from the specification at $SPEC_REF"
+              differing=1
+            fi
+          done < <(git -C "$RUNNER_TEMP/spec" ls-files -- schema fixtures docs)
+          exit $differing
+
+      # A pin on a commit that never landed — a branch someone force-pushed away, a PR
+      # head that was rewritten — would leave this implementing a specification nobody
+      # else has, and the byte check above would pass happily.
+      - name: SPEC_REF is an ancestor of the specification's main
+        run: git -C "$RUNNER_TEMP/spec" merge-base --is-ancestor "$SPEC_REF" origin/main
+
+  wheel:
+    name: An installed wheel carries its own schema
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build hatchling
+
+      # `python -m build` builds the sdist and then builds the wheel *from the sdist*,
+      # which is the artefact question worth asking: a wheel built from the source tree
+      # can carry files the sdist forgot. `--no-isolation`, with the backend installed
+      # above, so nothing is fetched while building — an sdist that needed the network
+      # would make that fetch part of every `pip install` from source.
+      - name: Build the sdist, and the wheel from the sdist
+        run: python -m build --no-isolation
+
+      - name: Install the wheel into a virtualenv of its own
+        run: |
+          python -m venv "$RUNNER_TEMP/venv"
+          "$RUNNER_TEMP/venv/bin/pip" install dist/*.whl
+
+      # Run from `$RUNNER_TEMP`, where there is no checkout to fall back to: this is the
+      # position every application that installs the package is in.
+      - name: The installed package resolves the schema it carries, with no checkout near
+        working-directory: ${{ runner.temp }}
+        run: |
+          cp "$GITHUB_WORKSPACE/fixtures/valid/technical-dive.divejson" .
+          "$RUNNER_TEMP/venv/bin/divejson" validate technical-dive.divejson
+          "$RUNNER_TEMP/venv/bin/divejson" conform "$GITHUB_WORKSPACE/fixtures" --strict
+          "$RUNNER_TEMP/venv/bin/python" - <<'EOF'
+          import os, pathlib
+          import divejson
+
+          installed = pathlib.Path(divejson.__file__).resolve().parent
+          assert "site-packages" in str(installed), installed
+          vendored = pathlib.Path(os.environ["GITHUB_WORKSPACE"]) / "schema"
+          sources = sorted(vendored.glob("*/divejson.schema.json"))
+          assert sources, "the vendored tree carries no schema at all"
+          for source in sources:
+              packaged = installed / "_schema" / source.parent.name / "divejson.schema.json"
+              assert packaged.read_bytes() == source.read_bytes(), packaged
+          print(f"schemas checked against the vendored tree: {len(sources)}")
+          EOF

divejson-0.2.0/.github/workflows/pr-title.yml

@@ -0,0 +1,65 @@
+name: PR Title
+
+on:
+  pull_request:
+    # `edited` is the one that matters: it re-runs the check when a title is
+    # corrected, so a failing PR goes green without an empty commit to push.
+    #
+    # `synchronize` is not about the title at all - it is what would let this be
+    # a required check. A required check has to have passed on the PR's *latest*
+    # head SHA, so without a run per push, a PR that gains a second commit would
+    # sit at "Expected - waiting for status" for good. The title is read from the
+    # event payload rather than from the tree, so the extra runs reach the same
+    # verdict. Nothing is required on `main` today; this keeps the option open at
+    # no cost.
+    types: [opened, edited, reopened, synchronize]
+
+# The one list of types. CONTRIBUTING.md spells the same list out in prose -
+# keep the two in step.
+env:
+  TYPES: feat|fix|refactor|docs|test|chore|perf|ci|build|revert
+
+jobs:
+  semantic-title:
+    runs-on: ubuntu-latest
+
+    # Nothing is checked out and no API call is made - the title arrives in the
+    # event payload - so this job needs no token at all.
+    permissions: {}
+
+    steps:
+      # `main`'s ruleset allows only squash merges, and the repository's squash
+      # subject source is PR_TITLE rather than COMMIT_OR_PR_TITLE, so this title
+      # *is* the commit subject that lands. It is the only part of a branch that
+      # outlives the branch, which is why it is checked and the individual
+      # commits are not. That setting was corrected by hand after a non-semantic
+      # subject reached a default branch in this org; this check is the half that
+      # stops the bad title from being written in the first place.
+      #
+      # The title is passed through `env` rather than interpolated into the
+      # script. `${{ github.event.pull_request.title }}` written inside `run:`
+      # is substituted before bash parses the line, so a title containing
+      # backticks or `$(...)` would execute as shell.
+      - name: Check title is a conventional commit subject
+        env:
+          TITLE: ${{ github.event.pull_request.title }}
+        run: |
+          PATTERN="^($TYPES)(\([a-z0-9._-]+\))?!?: .+"
+
+          if printf '%s' "$TITLE" | grep -Eq "$PATTERN"; then
+            echo "OK: $TITLE"
+            exit 0
+          fi
+
+          echo "PR title is not a semantic commit subject:"
+          echo "    $TITLE"
+          echo
+          echo "Expected: <type>[(scope)][!]: <description>"
+          echo "Types:    ${TYPES//|/, }"
+          echo
+          echo "Examples: feat(schema): a cylinder may record a mix without a vessel"
+          echo "          fix(spec): profile.duration spans the samples, not the events"
+          echo "          docs(spec)!: the draft becomes 1.0"
+          echo
+          echo "Edit the title - this check re-runs on edit, no push needed."
+          exit 1

divejson-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,65 @@
+name: Release
+
+# A release is a `v*` tag on `main`, pushed by a maintainer. Nothing else publishes: the
+# filename of this workflow, the repository and the environment below are three of the
+# four things PyPI's trusted publisher for this project is registered against, so a
+# rename here is a release that stops working rather than one that publishes wrongly.
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    name: Build and check what is about to be published
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build hatchling
+
+      - name: Build the sdist, and the wheel from the sdist
+        run: python -m build --no-isolation
+
+      # The version is declared once, in the package, and the tag is written by hand — so
+      # this is the one place they can disagree. A tag that names a version nobody built
+      # would otherwise publish the previous one under the new name.
+      - name: The tag names the version that was built
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          if [ ! -f "dist/divejson-$version.tar.gz" ]; then
+            echo "::error::$GITHUB_REF_NAME does not name the version that was built"
+            ls -1 dist
+            exit 1
+          fi
+
+      # Against the built wheel rather than the checkout: what gets published is what has
+      # to run the corpus, and an artefact that cannot is one nobody should be able to
+      # `pip install` a minute later.
+      - name: The wheel that is about to be published runs the corpus
+        run: |
+          python -m venv "$RUNNER_TEMP/venv"
+          "$RUNNER_TEMP/venv/bin/pip" install dist/*.whl
+          "$RUNNER_TEMP/venv/bin/divejson" conform fixtures --strict
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      # Trusted publishing: PyPI mints a short-lived token from this job's OIDC identity,
+      # so there is no API token anywhere in this repository's secrets.
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

divejson-0.2.0/.gitignore

@@ -0,0 +1,9 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+uv.lock

divejson-0.2.0/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+Notable changes to the DiveJSON tools for Python. The format's own version
+(`major.minor`, declared in every document) is what readers and writers depend on, and it
+is versioned in [the specification repository](https://github.com/divejson/divejson);
+this file is about the package, whose version moves independently.
+
+## 0.2.0
+
+- **The package moved here**, out of the specification repository. That repository keeps
+  what a conformance suite is — the prose, the schema, the fixture pairs and the mapping
+  documents — and runs a released implementation against them; every implementation, in
+  whatever language, is a repository of its own. One of them living beside the
+  specification was an asymmetry every port would have inherited.
+
+- **First release to PyPI**: `pip install divejson`, where the only way to install it
+  before was from git. It is 0.2.0 rather than 0.1.0 because 0.1.0 already exists, as the
+  package in the specification repository's history — two different trees under one
+  version number is worth a number rather than an explanation.
+
+- **`divejson conform <corpus>`**, the conformance runner an implementation of the format
+  provides, and what both this repository's CI and the specification repository's run. It
+  walks `valid/`, `invalid/`, a directory of reader pairs per source format and
+  `write/<format>/` of writer pairs, and separates a case that **failed** (status 1) from
+  a corpus whose **shape** stopped cases from running at all (status 2) — an empty
+  directory, a pair missing one of its halves, pairs for a format the implementation does
+  not register. A suite that read "nothing to run" as success is what that distinction is
+  for, and it replaces the hand-kept fixture count that used to guard the same thing.
+
+- **The specification is vendored and pinned.** `SPEC_REF` names the commit that
+  `schema/`, `fixtures/` and `docs/` were taken from, and CI checks on every pull request
+  that every file the specification owns is byte-identical here and that the pin is an
+  ancestor of its `main`. The copy may run ahead — an adapter lands with its own pairs and
+  mapping document before the specification adopts them — but it may never contradict.
+
+- **`load_schema()` resolves a schema per minor version**, and a built wheel carries every
+  minor the vendored tree has rather than only the one this package validates against.
+  Spec §7 gives each minor its own schema, and the directories were already named for
+  them.
+
+- **`fitdecode` is a core dependency**, before anything imports it and deliberately not
+  behind an extra: `pip install divejson==<release>` has to be the whole install
+  everywhere, and a format behind an extra is one every consumer has to know to ask for
+  and every runner can quietly skip.
+
+- **`divejson.conform.compared`** is now the package's own rule for what a converted
+  document is compared on — everything except `exported_at` and `generator`, which are
+  facts about the run rather than about the input. It was a test helper, where a port or
+  an application checking its own determinism could not reach it.
+
+- `py.typed`, and an `__all__` on the package naming what it exports.

divejson-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,97 @@
+# Contributing
+
+Issues and pull requests on GitHub are the whole process — there is no mailing list, no
+CLA, and no meeting. This repository is an *implementation*; the format itself is decided
+in [divejson/divejson](https://github.com/divejson/divejson), whose `GOVERNANCE.md` says
+who decides and whose `CONTRIBUTING.md` says how a change to the format lands.
+
+## What is here, and what is only borrowed
+
+| path | what |
+| --- | --- |
+| `divejson/` | the package: the validator, the UDDF reader, the conformance runner, the CLI |
+| `tests/` | its tests |
+| `schema/`, `fixtures/`, `docs/` | **vendored** from the specification repository at the commit `SPEC_REF` names |
+| `SPEC_REF` | that commit, on one line — a tag once the format has one |
+
+The vendored three are not editable here. CI checks out the specification at `SPEC_REF`
+and asserts that every file it owns is byte-identical in this tree, and that `SPEC_REF`
+is an ancestor of its `main`. What the copy *may* do is run ahead: it can carry pairs and
+mapping documents the specification has not adopted yet, which is what lets a new reader
+land here self-contained, with the expected documents it produces and the document that
+explains them. It can never carry a different version of a file the specification already
+has.
+
+So a change lands in one of two orders.
+
+**A change to what validates** — the schema, or a rule the fixtures encode — starts in
+the specification repository, whose pull request is red against the current release and
+says what is missing. The change here then sets `SPEC_REF` to that pull request's head,
+which passes the byte check and fails only the ancestor one; the specification's pull
+request points its own pin at this one and goes green; it merges; this one re-pins
+`SPEC_REF` to the merged commit, merges, and is released. `main` here never pins a commit
+that is not on the specification's `main`.
+
+**A new reader, or a change to a mapping** goes the other way: it lands here first,
+self-contained and green, then a release, and then the specification adopts the pairs and
+the mapping document and moves its pin. The next change here bumps `SPEC_REF` and
+re-vendors whatever moved.
+
+## Working on the package
+
+```bash
+pip install -e ".[dev]"
+pytest
+divejson conform fixtures --strict
+```
+
+The tests cover the converter — the unit conversions above all, where a wrong factor
+produces a document that validates perfectly and describes a dive nobody took. CI runs
+them on the Python floor, on a current version, and on the version the applications that
+install this package run; it also builds the sdist, builds the wheel from *that*, and
+checks that an installed copy resolves the schema it carries with no checkout anywhere
+near it. That last one is the failure this arrangement is most exposed to: the package
+and the corpus sit in one tree here and in different worlds everywhere else.
+
+## Regenerating an expected document
+
+Each input under a pair directory is paired with the document it must produce, so a
+mapping change shows up as a failing pair. Regenerate the expected side, and read the
+diff before committing it — the point of the pair is that a human agreed with the new
+answer:
+
+```bash
+divejson convert fixtures/<format>/<name>.<ext> --force \
+  --exported-at "$(grep -m1 exported_at fixtures/<format>/<name>.divejson | cut -d'"' -f4)"
+```
+
+Both flags matter. Without `--force` the command refuses to replace a file that exists,
+which is the right default everywhere except here. And `exported_at` is one of the two
+members a converted document asserts about its own run rather than about the source, so
+left to default it moves every time — reusing the value already in the file you are
+replacing keeps the moving lines to the ones your change actually moved. A test runs this
+recipe over the whole corpus, writing elsewhere and comparing, because a documented
+command nobody runs is a command that stops working.
+
+The other such member is `generator`, which carries this package's version. Both are
+excluded from the comparison — `divejson.conform.compared` is the rule, and it is in the
+package because a port and an application checking its own determinism need the same one
+— so a release never regenerates anything, and the committed expectations keep whatever
+version wrote them. Regenerate when the *mapping* changes, and remember that a pair the
+specification already owns cannot be regenerated here: that change starts over there.
+
+## Pull request titles
+
+Use a semantic **PR title** — `<type>[(scope)][!]: <description>`, where type is one of
+`feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`, `ci`, `build`, `revert`.
+Pull requests are squash-merged with the title as the commit subject, so it is the only
+part of a branch that outlives the branch.
+
+`.github/workflows/pr-title.yml` checks the format and re-runs when a title is edited —
+a failing check is fixed by correcting the title, with nothing to push.
+
+## Licensing of contributions
+
+Everything in this repository is MIT, including the vendored schema, fixtures and
+documents, which are MIT in the specification repository too. By contributing you license
+your contribution under that license.

divejson-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The DiveJSON Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

divejson-0.2.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.5
+Name: divejson
+Version: 0.2.0
+Summary: Validator, converters and conformance runner for DiveJSON, an open dive-log interchange format
+Project-URL: Homepage, https://divejson.org
+Project-URL: Repository, https://github.com/divejson/divejson-py
+Project-URL: Specification, https://github.com/divejson/divejson/blob/main/spec/divejson.md
+Project-URL: Changelog, https://github.com/divejson/divejson-py/blob/main/CHANGELOG.md
+License-Expression: MIT
+License-File: LICENSE
+Keywords: dive-log,diving,interchange,json,scuba
+Requires-Python: >=3.10
+Requires-Dist: fitdecode>=0.11.0
+Requires-Dist: jsonschema>=4.18
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# divejson
+
+Python tools for [DiveJSON](https://divejson.org), an open interchange format for scuba
+dive logs: the validator, the converters that read other dive-log formats into DiveJSON,
+and `divejson conform`, the conformance runner an implementation of the format is checked
+with.
+
+The format itself — the normative specification, the JSON Schema and the conformance
+corpus — lives in [divejson/divejson](https://github.com/divejson/divejson). This is an
+implementation of it, in a repository of its own, and it **vendors** that repository's
+schema, fixtures and mapping documents from the commit named in
+[`SPEC_REF`](https://github.com/divejson/divejson-py/blob/main/SPEC_REF). CI checks the
+copy against the specification at that commit on every pull request, so which version of
+the format this package implements is a fact in the tree rather than a claim in a
+sentence.
+
+## Install
+
+```bash
+pip install divejson
+```
+
+Python 3.10 or newer.
+
+## Validate a document
+
+```bash
+divejson validate my-logbook.divejson
+```
+
+The JSON Schema, and then the requirements the specification states in prose and a schema
+cannot — identifier uniqueness, referential closure, profile-series integrity, the member
+order, the UTC offset on `exported_at`. Exit status is non-zero if any file fails, with
+one line per violation.
+
+## Convert a logbook into DiveJSON
+
+```bash
+divejson convert my-logbook.uddf
+```
+
+writes `my-logbook.divejson` beside the input and reports, line by line, what the source
+did not carry — no UTC offsets, a cylinder whose size nobody recorded, coordinates that
+were `0.000000`. **Nothing absent is filled in**: that report is the other half of the
+output, not a diagnostic, and it is what tells a diver which parts of their history their
+old application never kept. The mapping rules, the three places UDDF is genuinely
+ambiguous, and what is deliberately left unmapped are in
+[`docs/uddf-mapping.md`](https://github.com/divejson/divejson-py/blob/main/docs/uddf-mapping.md).
+
+## Run a conformance corpus
+
+```bash
+divejson conform fixtures --strict
+```
+
+Walks a corpus — `valid/` documents that must validate, `invalid/` ones that must not,
+and one directory of reader pairs per source format, named for the format — and says what
+this implementation makes of it. The exit status distinguishes two ways of not passing:
+
+| status | meaning |
+| --- | --- |
+| 0 | every case passed |
+| 1 | a case **failed**: a valid document that does not validate, an invalid one that does, a pair whose produced document differs from the expected one |
+| 2 | the corpus's **shape** is wrong: an empty directory, a pair missing one of its halves, or pairs for a format this implementation does not register — cases that never ran, which is not the same answer as cases that failed |
+
+`--only <format>` and `--skip <format>` narrow the run to a format's pairs, and neither
+reaches `valid/` or `invalid/`. `--strict` turns a format this implementation reads and
+the corpus has no pairs for from a warning into an error.
+
+## What it reads
+
+| format | what this package does | versions |
+| --- | --- | --- |
+| DiveJSON | validates | 1.0 |
+| UDDF | reads into DiveJSON | 3.0 – 3.2.3 |
+
+The UDDF reader matches element names rather than the declared version, so older
+documents using the same names are read too: the corpus it is checked against carries
+2.2.0, 3.2.0, 3.2.1 and 3.2.2, under three different root shapes.
+
+## Releasing
+
+A release is a tag. Move `__version__` in `divejson/__init__.py` — the build reads the
+version from there, so it is the only place it lives — head the changelog's new entries
+with it, land that, and push `v<version>`.
+`.github/workflows/release.yml` then builds the sdist and, from it, the wheel; checks
+that the tag names the version it built and that the wheel actually runs the corpus; and
+publishes to PyPI by trusted publishing, with no API token anywhere. Nothing else
+publishes, and a release is the only thing another repository can pin.
+
+## Notices
+
+`fitdecode` (MIT) is a dependency of this package. The FIT Protocol and FIT file format
+are proprietary to Garmin; this project is not affiliated with or endorsed by Garmin, and
+carries no part of the FIT SDK.
+
+## License
+
+MIT — see [`LICENSE`](https://github.com/divejson/divejson-py/blob/main/LICENSE). The
+vendored `schema/`, `fixtures/` and `docs/` are MIT in the specification repository too;
+the specification prose itself, which is CC BY 4.0, is not vendored here.

divejson-0.2.0/README.md

@@ -0,0 +1,101 @@
+# divejson
+
+Python tools for [DiveJSON](https://divejson.org), an open interchange format for scuba
+dive logs: the validator, the converters that read other dive-log formats into DiveJSON,
+and `divejson conform`, the conformance runner an implementation of the format is checked
+with.
+
+The format itself — the normative specification, the JSON Schema and the conformance
+corpus — lives in [divejson/divejson](https://github.com/divejson/divejson). This is an
+implementation of it, in a repository of its own, and it **vendors** that repository's
+schema, fixtures and mapping documents from the commit named in
+[`SPEC_REF`](https://github.com/divejson/divejson-py/blob/main/SPEC_REF). CI checks the
+copy against the specification at that commit on every pull request, so which version of
+the format this package implements is a fact in the tree rather than a claim in a
+sentence.
+
+## Install
+
+```bash
+pip install divejson
+```
+
+Python 3.10 or newer.
+
+## Validate a document
+
+```bash
+divejson validate my-logbook.divejson
+```
+
+The JSON Schema, and then the requirements the specification states in prose and a schema
+cannot — identifier uniqueness, referential closure, profile-series integrity, the member
+order, the UTC offset on `exported_at`. Exit status is non-zero if any file fails, with
+one line per violation.
+
+## Convert a logbook into DiveJSON
+
+```bash
+divejson convert my-logbook.uddf
+```
+
+writes `my-logbook.divejson` beside the input and reports, line by line, what the source
+did not carry — no UTC offsets, a cylinder whose size nobody recorded, coordinates that
+were `0.000000`. **Nothing absent is filled in**: that report is the other half of the
+output, not a diagnostic, and it is what tells a diver which parts of their history their
+old application never kept. The mapping rules, the three places UDDF is genuinely
+ambiguous, and what is deliberately left unmapped are in
+[`docs/uddf-mapping.md`](https://github.com/divejson/divejson-py/blob/main/docs/uddf-mapping.md).
+
+## Run a conformance corpus
+
+```bash
+divejson conform fixtures --strict
+```
+
+Walks a corpus — `valid/` documents that must validate, `invalid/` ones that must not,
+and one directory of reader pairs per source format, named for the format — and says what
+this implementation makes of it. The exit status distinguishes two ways of not passing:
+
+| status | meaning |
+| --- | --- |
+| 0 | every case passed |
+| 1 | a case **failed**: a valid document that does not validate, an invalid one that does, a pair whose produced document differs from the expected one |
+| 2 | the corpus's **shape** is wrong: an empty directory, a pair missing one of its halves, or pairs for a format this implementation does not register — cases that never ran, which is not the same answer as cases that failed |
+
+`--only <format>` and `--skip <format>` narrow the run to a format's pairs, and neither
+reaches `valid/` or `invalid/`. `--strict` turns a format this implementation reads and
+the corpus has no pairs for from a warning into an error.
+
+## What it reads
+
+| format | what this package does | versions |
+| --- | --- | --- |
+| DiveJSON | validates | 1.0 |
+| UDDF | reads into DiveJSON | 3.0 – 3.2.3 |
+
+The UDDF reader matches element names rather than the declared version, so older
+documents using the same names are read too: the corpus it is checked against carries
+2.2.0, 3.2.0, 3.2.1 and 3.2.2, under three different root shapes.
+
+## Releasing
+
+A release is a tag. Move `__version__` in `divejson/__init__.py` — the build reads the
+version from there, so it is the only place it lives — head the changelog's new entries
+with it, land that, and push `v<version>`.
+`.github/workflows/release.yml` then builds the sdist and, from it, the wheel; checks
+that the tag names the version it built and that the wheel actually runs the corpus; and
+publishes to PyPI by trusted publishing, with no API token anywhere. Nothing else
+publishes, and a release is the only thing another repository can pin.
+
+## Notices
+
+`fitdecode` (MIT) is a dependency of this package. The FIT Protocol and FIT file format
+are proprietary to Garmin; this project is not affiliated with or endorsed by Garmin, and
+carries no part of the FIT SDK.
+
+## License
+
+MIT — see [`LICENSE`](https://github.com/divejson/divejson-py/blob/main/LICENSE). The
+vendored `schema/`, `fixtures/` and `docs/` are MIT in the specification repository too;
+the specification prose itself, which is CC BY 4.0, is not vendored here.

divejson-0.2.0/SPEC_REF

@@ -0,0 +1 @@
+9dfba28c950113b5e3e5ae9b48eddb256bfa93fa