osmlab · k-yle · Sep 18, 2025
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## 4.0.0 (----------)
+
+- 💥 BREAKING CHANGE: `uploadChangeset` now returns a object instead of a single changeset ID. This is because:
+  1. the function supports chunking uploads into multiple changesets if it exceeds the limit of 10,000 features per changeset.
+  2. For each feature that was created, the response now includes a mapping between the temporary ID used by the uploader, and the permanent ID allocated by the server.
+- 💥 BREAKING CHANGE: The type defintions for `Changeset` have been changed to mark several properties as optional. (see [#14](https://github.com/osmlab/osm-api-js/issues/14))
+- 💥 BREAKING CHANGE: `Changeset.created_at`, `Changeset.closed_at`, and `ChangesetComment.date` are now a `string`, not a `Date`. This makes it more consistent with the XML format, and easier to serialise to JSON.
+- 💥 BREAKING CHANGE: `ChangesetComment.uid` is now a `number`, not a `string`. This matches the behaviour of OSM's new json API.
+- 💥 BREAKING CHANGE: `Changeset.discussion` has been renamed to `Changeset.comments`. This matches the behaviour of OSM's new json API.
+
 ## 3.3.0 (2025-09-18)
 
 - [uploadChangeset] add an `onProgress` callback, so that apps can show a progress bar while uploading

diff --git a/examples/uploadChangeset.md b/examples/uploadChangeset.md
@@ -26,12 +26,17 @@ await uploadChangeset(
 
 Response:
 
-```json
-12345
+```jsonc
+{
+  // 12345 is the changeset number
+  "12345": {
+    // the contents of this object is the diff result.
+    // - for created features, this object allows you to map the temporary ID used by the uploader, to the permananet ID that the server allocated to this feature.
+    // - for updated & deleted features, it includes the new version number
+  },
+}
 ```
 
-(changeset number)
-
 ## Detailed Examples
 
 ### Updating existing features

diff --git a/src/__tests__/__snapshots__/e2e.test.ts.snap b/src/__tests__/__snapshots__/e2e.test.ts.snap
@@ -109,10 +109,9 @@ exports[`end to end tests > getCapabilities 1`] = `
 exports[`end to end tests > getChangeset (no discussion) 1`] = `
 {
   "changes_count": 10,
-  "closed_at": 2021-12-16T09:29:15.000Z,
+  "closed_at": "2021-12-16T09:29:15Z",
   "comments_count": 2,
-  "created_at": 2021-12-16T09:29:14.000Z,
-  "discussion": undefined,
+  "created_at": "2021-12-16T09:29:14Z",
   "id": 227200,
   "max_lat": -36.8801278,
   "max_lon": 174.7400986,
@@ -136,27 +135,27 @@ exports[`end to end tests > getChangeset (no discussion) 1`] = `
 exports[`end to end tests > getChangeset (with discussion) 1`] = `
 {
   "changes_count": 10,
-  "closed_at": 2021-12-16T09:29:15.000Z,
-  "comments_count": 2,
-  "created_at": 2021-12-16T09:29:14.000Z,
-  "discussion": [
+  "closed_at": "2021-12-16T09:29:15Z",
+  "comments": [
     {
-      "date": 2024-06-30T08:59:15.000Z,
+      "date": "2024-06-30T08:59:15Z",
       "id": 736,
       "text": "",
-      "uid": "12248",
+      "uid": 12248,
       "user": "kylenz_testing",
       "visible": true,
     },
     {
-      "date": 2024-06-30T08:59:55.000Z,
+      "date": "2024-06-30T08:59:55Z",
       "id": 737,
       "text": "sup bro",
-      "uid": "12248",
+      "uid": 12248,
       "user": "kylenz_testing",
       "visible": true,
     },
   ],
+  "comments_count": 2,
+  "created_at": "2021-12-16T09:29:14Z",
   "id": 227200,
   "max_lat": -36.8801278,
   "max_lon": 174.7400986,
@@ -533,10 +532,9 @@ exports[`end to end tests > listChangesets 1`] = `
 [
   {
     "changes_count": 2,
-    "closed_at": 2022-09-10T11:47:14.000Z,
+    "closed_at": "2022-09-10T11:47:14Z",
     "comments_count": 0,
-    "created_at": 2022-09-10T11:47:13.000Z,
-    "discussion": undefined,
+    "created_at": "2022-09-10T11:47:13Z",
     "id": 243638,
     "max_lat": -36.8804862,
     "max_lon": 174.739748,
@@ -553,10 +551,9 @@ exports[`end to end tests > listChangesets 1`] = `
   },
   {
     "changes_count": 10,
-    "closed_at": 2022-09-10T11:30:13.000Z,
+    "closed_at": "2022-09-10T11:30:13Z",
     "comments_count": 0,
-    "created_at": 2022-09-10T11:30:12.000Z,
-    "discussion": undefined,
+    "created_at": "2022-09-10T11:30:12Z",
     "id": 243637,
     "max_lat": -36.8804809,
     "max_lon": 174.7397571,
@@ -576,10 +573,9 @@ exports[`end to end tests > listChangesets 1`] = `
   },
   {
     "changes_count": 10,
-    "closed_at": 2021-12-16T09:29:15.000Z,
+    "closed_at": "2021-12-16T09:29:15Z",
     "comments_count": 2,
-    "created_at": 2021-12-16T09:29:14.000Z,
-    "discussion": undefined,
+    "created_at": "2021-12-16T09:29:14Z",
     "id": 227200,
     "max_lat": -36.8801278,
     "max_lon": 174.7400986,
@@ -600,10 +596,9 @@ exports[`end to end tests > listChangesets 1`] = `
   },
   {
     "changes_count": 5,
-    "closed_at": 2021-12-16T08:43:07.000Z,
+    "closed_at": "2021-12-16T08:43:07Z",
     "comments_count": 0,
-    "created_at": 2021-12-16T08:43:06.000Z,
-    "discussion": undefined,
+    "created_at": "2021-12-16T08:43:06Z",
     "id": 227184,
     "max_lat": -36.8804809,
     "max_lon": 174.7397571,

diff --git a/src/api/_rawResponse.d.ts b/src/api/_rawResponse.d.ts
@@ -1,24 +1,5 @@
 import type { Feature, FeatureCollection, Point } from "geojson";
-import type {
-  Changeset,
-  ChangesetComment,
-  OsmFeatureType,
-  OsmNote,
-} from "../types";
-
-/** @internal */
-export type RawChangeset = Omit<
-  Changeset,
-  "discussion" | "created_at" | "closed_at"
-> & {
-  created_at: string;
-  closed_at?: string;
-  comments?: (Omit<ChangesetComment, "date" | "uid"> & {
-    /** ISO Date */
-    date: string;
-    uid: number;
-  })[];
-};
+import type { OsmFeatureType, OsmNote } from "../types";
 
 /** @internal */
 export type RawNotesSearch = FeatureCollection<

diff --git a/src/api/changesets/__tests__/uploadChangeset.test.ts b/src/api/changesets/__tests__/uploadChangeset.test.ts
@@ -236,7 +236,7 @@ describe("uploadChangeset", () => {
       { comment: "added a building" },
       { create: [], modify: [], delete: [] }
     );
-    expect(output).toBe(1);
+    expect(output).toStrictEqual({ 1: { diffResult: {} } });
 
     expect(osmFetch).toHaveBeenCalledTimes(3);
     expect(osmFetch).toHaveBeenNthCalledWith(
@@ -277,7 +277,56 @@ describe("uploadChangeset", () => {
       );
     }
 
-    expect(output).toBe(1);
+    expect(output).toStrictEqual({
+      // create nodes first.
+      1: {
+        diffResult: {
+          node: {
+            "-10": { newId: 2, newVersion: 1 },
+            "-11": { newId: 1, newVersion: 1 },
+            "-2": { newId: 5, newVersion: 1 },
+            "-7": { newId: 6, newVersion: 1 },
+            "-8": { newId: 4, newVersion: 1 },
+            "-9": { newId: 3, newVersion: 1 },
+          },
+        },
+      },
+      // create nodes then ways then relations next
+      2: {
+        diffResult: {
+          node: {
+            "-100": { newId: 10, newVersion: 1 },
+            "-4": { newId: 9, newVersion: 1 },
+            "-5": { newId: 8, newVersion: 1 },
+            "-6": { newId: 7, newVersion: 1 },
+          },
+          relation: { "-300000": { newId: 1, newVersion: 1 } },
+          way: { "-3": { newId: 1, newVersion: 1 } },
+        },
+      },
+      // modify and delete next (any order)
+      3: {
+        diffResult: {
+          node: {
+            1: { newId: 1, newVersion: 2 },
+            2: { newId: 2, newVersion: 3 },
+          },
+          relation: {
+            2: { newId: 2, newVersion: 22 },
+            3: { newId: 3, newVersion: 2 },
+            4: { newId: 4, newVersion: 2 },
+          },
+          way: { 2: { newId: 2, newVersion: 2 } },
+        },
+      },
+      // delete last
+      4: {
+        diffResult: {
+          relation: { 1: { newId: 1, newVersion: 11 } },
+          way: { 1: { newId: 1, newVersion: 3 } },
+        },
+      },
+    });
   });
 
   it("splits changesets into chunks and suports a custom tag function", async () => {
@@ -311,7 +360,9 @@ describe("uploadChangeset", () => {
       );
     }
 
-    expect(output).toBe(1);
+    // don't need to assert the output, since it's the same
+    // as the previous test case.
+    expect(Object.keys(output).map(Number)).toStrictEqual([1, 2, 3, 4]);
   });
 
   // end of tests

diff --git a/src/api/changesets/createChangesetComment.ts b/src/api/changesets/createChangesetComment.ts
@@ -1,15 +1,13 @@
 import type { Changeset } from "../../types";
 import { type FetchOptions, osmFetch } from "../_osmFetch";
-import type { RawChangeset } from "../_rawResponse";
-import { mapRawChangeset } from "./getChangesets";
 
 /** Add a comment to a changeset. The changeset must be closed. */
 export async function createChangesetComment(
   changesetId: number,
   commentText: string,
   options?: FetchOptions
 ): Promise<Changeset> {
-  const result = await osmFetch<{ changeset: RawChangeset }>(
+  const result = await osmFetch<{ changeset: Changeset }>(
     `/0.6/changeset/${changesetId}/comment.json`,
     undefined,
     {
@@ -22,5 +20,5 @@ export async function createChangesetComment(
       },
     }
   );
-  return mapRawChangeset(result.changeset);
+  return result.changeset;
 }
diff --git a/src/api/changesets/getChangesets.ts b/src/api/changesets/getChangesets.ts
@@ -1,22 +1,5 @@
 import type { BBox, Changeset } from "../../types";
 import { type FetchOptions, osmFetch } from "../_osmFetch";
-import type { RawChangeset } from "../_rawResponse";
-
-/** @internal */
-export const mapRawChangeset = ({
-  comments,
-  ...raw
-}: RawChangeset): Changeset => ({
-  ...raw,
-  created_at: new Date(raw.created_at),
-  closed_at: raw.closed_at ? new Date(raw.closed_at) : undefined!,
-
-  discussion: comments?.map((comment) => ({
-    ...comment,
-    date: new Date(comment.date),
-    uid: `${comment.uid}`,
-  })),
-});
 
 // does not extend BasicFilters for historical reasons
 export type ListChangesetOptions = {
@@ -57,7 +40,7 @@ export async function listChangesets(
 ): Promise<Changeset[]> {
   const { only, ...otherQueries } = query;
 
-  const raw = await osmFetch<{ changesets: RawChangeset[] }>(
+  const raw = await osmFetch<{ changesets: Changeset[] }>(
     "/0.6/changesets.json",
     {
       ...(only && { [only]: true }),
@@ -66,7 +49,7 @@ export async function listChangesets(
     options
   );
 
-  return raw.changesets.map(mapRawChangeset);
+  return raw.changesets;
 }
 
 /** get a single changeset */
@@ -76,11 +59,11 @@ export async function getChangeset(
   includeDiscussion = true,
   options?: FetchOptions
 ): Promise<Changeset> {
-  const raw = await osmFetch<{ changeset: RawChangeset }>(
+  const raw = await osmFetch<{ changeset: Changeset }>(
     `/0.6/changeset/${id}.json`,
     includeDiscussion ? { include_discussion: 1 } : {},
     options
   );
 
-  return mapRawChangeset(raw.changeset);
+  return raw.changeset;
 }