Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
# Reviewed 2026-10-15 against the pinned OAD and the provider's published reference, fetched
# with curl (https://developer.todoist.com/api/v1/); no live requests, no token. For #99.
# Source quotes (each checked against the raw page):
# Get Tasks: "Get all active tasks for the user. All provided parameters are used to narrow
# down the list of tasks."
# Get Task: "Returns a single active (non-completed) task by ID".
# Close Task: "Regular tasks are marked complete and moved to history, along with their
# subtasks. Tasks with recurring due dates will be scheduled to their next occurrence."
# Delete Task: "Delete a task and all of its subtasks."
# Archive Project: "For workspace projects, this will archive it for all workspace users,
# removing it from view."
# Pagination: "next_cursor: A string token for fetching the next page, or null if there are
# no more results"; "When next_cursor is null, you've reached the end of the results."
# (Quotes re-audited against the raw page with curl on 2026-10-15.)
# A complete read therefore follows next_cursor until it is null (the catalog's pagination
# overlay declares that cursor); a read that stops earlier, or fails on a page, is not
# complete, and nothing is concluded from what it did not return.
# So a task leaves GET /tasks when it is completed (a non-recurring one), deleted, or (not
# stated, see below) when its project is archived or the user loses access; absence is
# `removed`, never `deleted`. GET /tasks/{task_id} returns active tasks only, so a completed
# task cannot be read back as `checked: true`, nor a deleted one as `is_deleted: true`: no read
# tombstone is declared, and a 404 is `unavailable` (completed, deleted or out of reach).
# Not verified without a live account (not declared):
# - the status GET /tasks/{task_id} answers for a completed, a deleted, or an inaccessible
# task (the reference lists 404 among the responses but does not say which case gives it);
# - whether GET /tasks includes tasks of an archived project;
# - whether Tasks Completed By Completion Date (up to 3 months) lists every task that left
# the active list by completion, which would let a client tell completion from deletion.
# Needs Collection Completeness 0.2.0-draft (notFound). Composes with
# crud-causality-ac07532b0a0ac101cf8bae2a54177fb1d8ea3779-overlay.yaml in either order: it
# deep-merges into components.crudResources.
overlay: 1.0.0
info:
title: Todoist API v1 active-task completeness
version: 1.0.0
extends: https://raw.githubusercontent.com/ontola/openapi-directory/ac07532b0a0ac101cf8bae2a54177fb1d8ea3779/APIs/todoist.com/1/openapi.yaml
actions:
- target: $.components
update:
crudResources:
task:
collections:
tasks:
x-completeness:
absent: removed
notFound: unavailable
description: >-
GET /tasks returns "all active tasks for the user"; a complete
read sends no narrowing parameter (no project_id) and follows
every cursor. A task leaves it when completed ("marked
complete and moved to history"), when deleted, and possibly
when its project is archived or access is lost, so absence is
removed. GET /tasks/{task_id} "Returns a single active
(non-completed) task by ID", so a 404 can mean completed,
deleted or out of reach: unavailable, never deleted.
19 changes: 13 additions & 6 deletions overlays/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -514,7 +514,7 @@ fixed read is the request the drive app sends. No provider was called.

## Collection completeness

Two standalone overlays declare [Collection Completeness](../openapi-extensions/spec/collection-completeness/README.md)
Three standalone overlays declare [Collection Completeness](../openapi-extensions/spec/collection-completeness/README.md)
`x-completeness`, which syncables reads (`absent`, `notFound`, `gone`,
`parentAbsent`). No dated catalog selects them yet.

Expand All @@ -523,11 +523,18 @@ Two standalone overlays declare [Collection Completeness](../openapi-extensions/
| [Google Tasks v1 completeness](APIs/googleapis.com/tasks/v1/completeness-7ca47c73cf2308c9812692b482b3713b397bc88c-overlay.yaml) | Task lists and tasks `absent: removed`, `notFound: unavailable`; tasks `parentAbsent: unavailable`; the task read tombstone `deleted: true`. Needs crud-causality v2 (the fixed read that returns hidden tasks). | The pinned OAD (tasklists.list "Returns all the authenticated user's task lists"; Task.deleted "Flag indicating whether the task has been deleted"); what a 404 means is not documented |
| [GitHub Issues completeness](APIs/github.com/github-issues/1.1.4/completeness-9c5cfb87b3f8b64e11069373a73e3fc85de0de5e-overlay.yaml) | Issues `absent: removed`, `notFound: unavailable`, no `gone`; comments the same plus `parentAbsent: unavailable`. Page-number paging can skip an issue deleted or transferred during a read; it stays unconfirmed until its GET settles it. | [Get an issue](https://docs.github.com/en/rest/issues/issues#get-an-issue): 301 when transferred, 404 when transferred or deleted out of the caller's reach, 410 when deleted where the caller can read, and 410 for every issue when issues are turned off, so neither a 404 nor a 410 is declared a deletion |

A Todoist overlay drafted with these is left out: Todoist's API reference
could not be read for the task fields and single-task read it relies on,
and its pinned OAD is an authored subset without descriptions.
`tests/test_completeness_overlays.py` and
`tests/test_github_issues_completeness.py` compose each overlay with the
| [Todoist v1 active-task completeness](APIs/todoist.com/1/completeness-ac07532b0a0ac101cf8bae2a54177fb1d8ea3779-overlay.yaml) (#99) | Tasks `absent: removed`, `notFound: unavailable`; no read tombstone and no `gone`. | [API v1 reference](https://developer.todoist.com/api/v1/), read raw with curl: Get Tasks "Get all active tasks for the user"; Get Task "Returns a single active (non-completed) task by ID"; Close Task "Regular tasks are marked complete and moved to history"; Delete Task "Delete a task and all of its subtasks."; pagination "When next_cursor is null, you've reached the end of the results." A task that leaves the list may be completed, deleted or out of reach, and its read cannot return it as `checked` or `is_deleted`; no read answer is taken as a deletion, and a read that stops before a null `next_cursor` is not complete |

An earlier Todoist draft was left out because the reference could not be
read; read raw, it settles the declaration above. Not verified without a
live account, so not declared: the status `GET /tasks/{task_id}` answers
for a completed, a deleted or an inaccessible task; whether `GET /tasks`
includes tasks of an archived project; and whether "Tasks Completed By
Completion Date" (up to 3 months) lists every task that left the active
list by completion, which would tell completion from deletion.
`tests/test_completeness_overlays.py`,
`tests/test_github_issues_completeness.py` and
`tests/test_todoist_completeness.py` compose each overlay with the
overlays it needs, run the Collection Completeness and CRUD Causality
validators, and classify synthetic reads with the spec's `classify_read`.
No provider was called.
Expand Down
137 changes: 137 additions & 0 deletions overlays/tests/test_todoist_completeness.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,137 @@
"""Check the Todoist active-task completeness overlay (#99) against its pinned OAD.

The overlay is composed with its pinned OAD and the catalog's crud-causality
overlay, in either order. The result must pass the Collection Completeness
validator, add only x-completeness on the tasks collection, and classify
synthetic reads as the overlay intends: a task absent from a complete read is
removed (not deleted), and a 404 from reading it is unavailable whatever its
cause. No read tombstone is declared, since GET /tasks/{task_id} returns
active tasks only. No provider is called. Use --directory for a full-history
openapi-directory checkout; otherwise the full-SHA source URL is downloaded.
"""
import argparse
import copy
import importlib.util
from pathlib import Path
import subprocess
import sys
import tempfile
import unittest

import yaml

from generate_identity_catalog_fixtures import ROOT, apply, fetch

sys.path.insert(0, str(ROOT / "scripts"))
from validate_oad_pins import overlay_pin

spec = importlib.util.spec_from_file_location(
"completeness_validate", ROOT.parent / "openapi-extensions" / "spec" / "collection-completeness" / "validate.py")
completeness = importlib.util.module_from_spec(spec)
spec.loader.exec_module(completeness)

DIRECTORY = None
TODOIST = "APIs/todoist.com/1/"
OVERLAY = TODOIST + "completeness-ac07532b0a0ac101cf8bae2a54177fb1d8ea3779-overlay.yaml"
CRUD = TODOIST + "crud-causality-ac07532b0a0ac101cf8bae2a54177fb1d8ea3779-overlay.yaml"
PAGINATION = TODOIST + "pagination-ac07532b0a0ac101cf8bae2a54177fb1d8ea3779-overlay.yaml"


def load(path):
return yaml.safe_load((ROOT / path).read_text())


class TodoistCompletenessTests(unittest.TestCase):
@classmethod
def setUpClass(cls):
url, sha, source = overlay_pin(ROOT / OVERLAY)
assert overlay_pin(ROOT / CRUD)[0] == url
with tempfile.TemporaryDirectory() as cache:
if DIRECTORY:
raw = subprocess.check_output(["git", "-C", str(DIRECTORY), "show", sha + ":" + source])
else:
raw, _ = fetch(url, Path(cache))
cls.original = yaml.safe_load(raw)
cls.composed = copy.deepcopy(cls.original)
apply(cls.composed, load(CRUD))
apply(cls.composed, load(OVERLAY))

def declaration(self):
return self.composed["components"]["crudResources"]["task"]["collections"]["tasks"]["x-completeness"]

def test_composes_in_either_order_and_validates(self):
other = copy.deepcopy(self.original)
apply(other, load(OVERLAY))
apply(other, load(CRUD))
self.assertEqual(other, self.composed)
completeness.validate(self.composed)

def test_declares_only_tasks_completeness(self):
crud_only = copy.deepcopy(self.original)
apply(crud_only, load(CRUD))
composed = copy.deepcopy(self.composed)
tasks = composed["components"]["crudResources"]["task"]["collections"]["tasks"]
self.assertEqual((tasks.pop("x-completeness")["absent"], self.declaration()["notFound"]),
("removed", "unavailable"))
self.assertEqual(composed, crud_only)
self.assertNotIn("x-read-tombstone", self.composed["components"]["crudResources"]["task"])
self.assertNotIn("gone", self.declaration())

def test_the_pinned_document_says_what_the_overlay_relies_on(self):
self.assertEqual(self.original["paths"]["/tasks"]["get"]["summary"], "Get active tasks")
params = [p.get("name") for p in self.original["paths"]["/tasks"]["get"].get("parameters", [])]
self.assertIn("project_id", params)

def test_reads_of_a_task_that_left_the_active_list(self):
declaration = self.declaration()
not_found = completeness.resource_not_found(self.composed, "task")
self.assertEqual(not_found, "unavailable")
# Completed, deleted or out of reach: a 404 or 410 is unavailable, never deleted.
for status in (404, 410):
self.assertEqual(completeness.classify_read(declaration, None, "id", "t1", status, None, not_found),
"unavailable")
# A 200 with the task: it is still active (present), even with is_deleted or checked,
# since no read tombstone is declared.
for body in ({"id": "t1", "checked": False}, {"id": "t1", "checked": True, "is_deleted": True}):
self.assertEqual(completeness.classify_read(declaration, None, "id", "t1", 200, body, not_found),
"present")
# Another answer says nothing.
self.assertEqual(completeness.classify_read(declaration, None, "id", "t1", 500, None, not_found), "unknown")

def test_no_read_answer_is_ever_taken_as_a_deletion(self):
# #99: absence or a failed read is never proof of completion or
# deletion. Whatever a task's own read answers, the declaration
# yields present, unavailable or unknown, never deleted.
declaration = self.declaration()
not_found = completeness.resource_not_found(self.composed, "task")
bodies = (None, {}, {"id": "t1"}, {"id": "t1", "checked": True}, {"id": "t1", "is_deleted": True},
{"id": "t2"})
outcomes = {completeness.classify_read(declaration, None, "id", "t1", status, body, not_found)
for status in range(200, 600) for body in bodies}
self.assertNotIn("deleted", outcomes)
self.assertEqual(outcomes, {"present", "unavailable", "unknown"})

def test_a_complete_read_follows_the_cursor_to_its_documented_end(self):
# "When next_cursor is null, you've reached the end of the results."
# The catalog's pagination overlay pages GET /tasks by that cursor, so
# a read that stops before a null next_cursor is not complete (§3).
document = copy.deepcopy(self.original)
apply(document, load(PAGINATION))
self.assertEqual(document["paths"]["/tasks"]["get"]["x-pagination"], [{"scheme": "cursor"}])
scheme = document["components"]["paginationSchemes"]["cursor"]
self.assertEqual(scheme["response"]["bodyFields"]["next_cursor"]["role"], "nextCursor")
self.assertEqual(scheme["request"]["queryParameters"]["cursor"]["role"], "cursor")

def test_no_dated_catalog_selects_it(self):
name = OVERLAY.rsplit("/", 1)[1]
for catalog in (ROOT / "catalog").glob("*.json"):
with self.subTest(catalog=catalog.name):
self.assertNotIn(name, catalog.read_text())


if __name__ == "__main__":
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--directory", type=Path)
args, remaining = parser.parse_known_args()
DIRECTORY = args.directory
unittest.main(argv=[sys.argv[0], *remaining])
Loading