From 19e962f802e29518d1de8799d004c98b96c5c702 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johan=20Bergstr=C3=B6m?= Date: Mon, 10 Nov 2025 14:08:52 +0000 Subject: [PATCH 01/10] chore: improve Event property - correctly expand `anyOf` for events - add a maxItems to auctions array - CategoryDisjunctions incorrectly refers to `minimum` instead of `minLength` --- topsort-api-v2.yml | 45 +++++++++++++++++---------------------------- 1 file changed, 17 insertions(+), 28 deletions(-) diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml index 0053874..d0d2b85 100644 --- a/topsort-api-v2.yml +++ b/topsort-api-v2.yml @@ -631,7 +631,7 @@ components: items: type: string description: A category ID. - minimum: 1 + minLength: 1 minItems: 1 Device: type: string @@ -833,6 +833,8 @@ components: oneOf: - $ref: "#/components/schemas/SponsoredListingsAuction" - $ref: "#/components/schemas/BannersAuction" + minItems: 1 + maxItems: 5 RankingRequest: type: object description: | @@ -1911,45 +1913,28 @@ components: EventsRequest: type: object additionalProperties: false - properties: - impressions: + minProperties: 1 + anyOf: + - title: Impressions type: array - items: - $ref: "#/components/schemas/Impression" + $ref: "#/components/schemas/Impression" minItems: 0 maxItems: 50 - clicks: + - title: Clicks type: array - items: - $ref: "#/components/schemas/Click" + $ref: "#/components/schemas/Click" minItems: 0 maxItems: 50 - purchases: + - title: Purchases type: array - items: - $ref: "#/components/schemas/Purchase" + $ref: "#/components/schemas/Purchase" minItems: 0 maxItems: 50 - pageviews: + - title: Page views type: array - items: - $ref: "#/components/schemas/Pageview" + $ref: "#/components/schemas/Pageview" minItems: 0 maxItems: 50 - minProperties: 1 - anyOf: - - properties: - impressions: - minItems: 1 - - properties: - clicks: - minItems: 1 - - properties: - purchases: - minItems: 1 - - properties: - pageviews: - minItems: 1 examples: - impressions: - id: eb874c98-bf4d-40a9-ae6d-fcf4cecb535c @@ -2010,6 +1995,7 @@ components: deviceType: mobile channel: onsite Impression: + title: Impression type: object description: > An impression means a promotable has become visible to the consumer. For promoted entities, @@ -2069,6 +2055,7 @@ components: examples: - onsite Click: + title: Click description: > A click is sent to Topsort when the consumer has clicked on a promotable. For promoted entities, include the `resolvedBidId` field from the `/v2/auctions` response. For unpromoted @@ -2134,6 +2121,7 @@ components: examples: - onsite Purchase: + title: Purchase description: > A purchase is sent to Topsort once a marketplace customer places an order. These events are used to measure the effectiveness of an ad campaign. @@ -2218,6 +2206,7 @@ components: examples: - eb874c98-bf4d-40a9-ae6d-fcf4cecb535c Pageview: + title: Pageview type: object description: > A page view represents the navigation of the user throughout the page. They are considered From d1e24e27ca33777bae74a209d8624eace2741ef5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johan=20Bergstr=C3=B6m?= Date: Mon, 10 Nov 2025 14:11:40 +0000 Subject: [PATCH 02/10] fix: lint --- topsort-api-v2.yml | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml index d0d2b85..4d2796f 100644 --- a/topsort-api-v2.yml +++ b/topsort-api-v2.yml @@ -1915,23 +1915,19 @@ components: additionalProperties: false minProperties: 1 anyOf: - - title: Impressions - type: array + - type: array $ref: "#/components/schemas/Impression" minItems: 0 maxItems: 50 - - title: Clicks - type: array + - type: array $ref: "#/components/schemas/Click" minItems: 0 maxItems: 50 - - title: Purchases - type: array + - type: array $ref: "#/components/schemas/Purchase" minItems: 0 maxItems: 50 - - title: Page views - type: array + - type: array $ref: "#/components/schemas/Pageview" minItems: 0 maxItems: 50 From 3e30ef13a2446dafb588d07fbb84b3240c168ebe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johan=20Bergstr=C3=B6m?= Date: Mon, 10 Nov 2025 14:13:48 +0000 Subject: [PATCH 03/10] chore: update vacuum --- .github/workflows/lint-tools.yml | 2 +- topsort-api-v2.yml | 40 +++++++++++++++++++------------- 2 files changed, 25 insertions(+), 17 deletions(-) diff --git a/.github/workflows/lint-tools.yml b/.github/workflows/lint-tools.yml index 43f0d34..24dbe65 100644 --- a/.github/workflows/lint-tools.yml +++ b/.github/workflows/lint-tools.yml @@ -33,7 +33,7 @@ jobs: - uses: actions/checkout@v4 - name: Install Vacuum env: - version: 0.17.8 + version: 0.20.2 run: curl -Ls "https://github.com/daveshanley/vacuum/releases/download/v${{ env.version }}/vacuum_${{ env.version }}_linux_x86_64.tar.gz" | sudo tar -x -z -C /usr/local/bin diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml index 4d2796f..7389e62 100644 --- a/topsort-api-v2.yml +++ b/topsort-api-v2.yml @@ -1915,22 +1915,30 @@ components: additionalProperties: false minProperties: 1 anyOf: - - type: array - $ref: "#/components/schemas/Impression" - minItems: 0 - maxItems: 50 - - type: array - $ref: "#/components/schemas/Click" - minItems: 0 - maxItems: 50 - - type: array - $ref: "#/components/schemas/Purchase" - minItems: 0 - maxItems: 50 - - type: array - $ref: "#/components/schemas/Pageview" - minItems: 0 - maxItems: 50 + - title: Impressions + type: array + properties: + $ref: "#/components/schemas/Impression" + minItems: 0 + maxItems: 50 + - title: Clicks + type: array + properties: + $ref: "#/components/schemas/Click" + minItems: 0 + maxItems: 50 + - title: Purchases + type: array + properties: + $ref: "#/components/schemas/Purchase" + minItems: 0 + maxItems: 50 + - title: Page views + type: array + properties: + $ref: "#/components/schemas/Pageview" + minItems: 0 + maxItems: 50 examples: - impressions: - id: eb874c98-bf4d-40a9-ae6d-fcf4cecb535c From d3892ff2bd105472dbbbc91b6a2ef56e914a65cd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johan=20Bergstr=C3=B6m?= Date: Mon, 10 Nov 2025 14:15:03 +0000 Subject: [PATCH 04/10] fix: use of wrong property --- topsort-api-v2.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml index 7389e62..98d62c6 100644 --- a/topsort-api-v2.yml +++ b/topsort-api-v2.yml @@ -1917,25 +1917,25 @@ components: anyOf: - title: Impressions type: array - properties: + items: $ref: "#/components/schemas/Impression" minItems: 0 maxItems: 50 - title: Clicks type: array - properties: + items: $ref: "#/components/schemas/Click" minItems: 0 maxItems: 50 - title: Purchases type: array - properties: + items: $ref: "#/components/schemas/Purchase" minItems: 0 maxItems: 50 - title: Page views type: array - properties: + items: $ref: "#/components/schemas/Pageview" minItems: 0 maxItems: 50 From 5648db2f4418dddf6107e47f28ee3196328f0e8f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johan=20Bergstr=C3=B6m?= Date: Mon, 10 Nov 2025 15:54:34 +0000 Subject: [PATCH 05/10] fix: move out arrays to independent schemas --- topsort-api-v2.yml | 72 +++++++++++++++++++++++++++++----------------- 1 file changed, 45 insertions(+), 27 deletions(-) diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml index 98d62c6..f0d6379 100644 --- a/topsort-api-v2.yml +++ b/topsort-api-v2.yml @@ -830,7 +830,7 @@ components: id: c_yogurt AuctionRequest: description: Describes the intent of running a single auction. - oneOf: + anyOf: - $ref: "#/components/schemas/SponsoredListingsAuction" - $ref: "#/components/schemas/BannersAuction" minItems: 1 @@ -1912,33 +1912,11 @@ components: - vendor EventsRequest: type: object - additionalProperties: false - minProperties: 1 anyOf: - - title: Impressions - type: array - items: - $ref: "#/components/schemas/Impression" - minItems: 0 - maxItems: 50 - - title: Clicks - type: array - items: - $ref: "#/components/schemas/Click" - minItems: 0 - maxItems: 50 - - title: Purchases - type: array - items: - $ref: "#/components/schemas/Purchase" - minItems: 0 - maxItems: 50 - - title: Page views - type: array - items: - $ref: "#/components/schemas/Pageview" - minItems: 0 - maxItems: 50 + - $ref: "#/components/schemas/ImpressionsArray" + - $ref: "#/components/schemas/ClicksArray" + - $ref: "#/components/schemas/PurchasesArray" + - $ref: "#/components/schemas/PageviewsArray" examples: - impressions: - id: eb874c98-bf4d-40a9-ae6d-fcf4cecb535c @@ -2058,6 +2036,16 @@ components: - instore examples: - onsite + ImpressionsArray: + title: Impressions + description: An array of impression events + properties: + impressions: + type: array + minItems: 0 + maxItems: 50 + items: + $ref: "#/components/schemas/Impression" Click: title: Click description: > @@ -2124,6 +2112,16 @@ components: - instore examples: - onsite + ClicksArray: + title: Clicks + description: An array of click events + properties: + clicks: + type: array + minItems: 0 + maxItems: 50 + items: + $ref: "#/components/schemas/Click" Purchase: title: Purchase description: > @@ -2200,6 +2198,16 @@ components: minLength: 1 examples: - v_8fj2D + PurchasesArray: + title: Purchases + description: An array of purchase events + properties: + clicks: + type: array + minItems: 0 + maxItems: 50 + items: + $ref: "#/components/schemas/Purchase" EventIdentifier: type: string description: > @@ -2250,6 +2258,16 @@ components: - instore examples: - onsite + PageviewsArray: + title: Page views + description: An array of page view events + properties: + clicks: + type: array + minItems: 0 + maxItems: 50 + items: + $ref: "#/components/schemas/Pageview" securitySchemes: HTTPBearer: description: A valid API key generated in Topsort's UI. From b9ad8fea15870f0ce63b0663a448b00a8d03aa0b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johan=20Bergstr=C3=B6m?= Date: Mon, 10 Nov 2025 15:59:38 +0000 Subject: [PATCH 06/10] fix: copy paste attribute names --- topsort-api-v2.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml index f0d6379..e48ecd7 100644 --- a/topsort-api-v2.yml +++ b/topsort-api-v2.yml @@ -2202,7 +2202,7 @@ components: title: Purchases description: An array of purchase events properties: - clicks: + purchases: type: array minItems: 0 maxItems: 50 @@ -2262,7 +2262,7 @@ components: title: Page views description: An array of page view events properties: - clicks: + pageviews: type: array minItems: 0 maxItems: 50 From 63eda484490000aab91b7e7d02b0d7e24d5e5b1a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johan=20Bergstr=C3=B6m?= Date: Mon, 10 Nov 2025 16:24:34 +0000 Subject: [PATCH 07/10] fix: use oneOf/discriminator for auctions --- topsort-api-v2.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml index e48ecd7..7a3556f 100644 --- a/topsort-api-v2.yml +++ b/topsort-api-v2.yml @@ -830,9 +830,11 @@ components: id: c_yogurt AuctionRequest: description: Describes the intent of running a single auction. - anyOf: + oneOf: - $ref: "#/components/schemas/SponsoredListingsAuction" - $ref: "#/components/schemas/BannersAuction" + discriminator: + propertyName: "type" minItems: 1 maxItems: 5 RankingRequest: From 41a1f7d2202d8732e992870b7c20b1aec3012616 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johan=20Bergstr=C3=B6m?= Date: Mon, 10 Nov 2025 16:26:00 +0000 Subject: [PATCH 08/10] fix: pageview -> page view --- topsort-api-v2.yml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml index 7a3556f..56ff278 100644 --- a/topsort-api-v2.yml +++ b/topsort-api-v2.yml @@ -302,7 +302,7 @@ paths: - **Purchases** — a user created an order. - - **Pageviews** — a user visited a page. + - **Page views** — a user visited a page. Interactions require either a `resolvedBidId`, for sponsored events coming from the `/v2/auctions` response, @@ -1918,7 +1918,7 @@ components: - $ref: "#/components/schemas/ImpressionsArray" - $ref: "#/components/schemas/ClicksArray" - $ref: "#/components/schemas/PurchasesArray" - - $ref: "#/components/schemas/PageviewsArray" + - $ref: "#/components/schemas/PageViewsArray" examples: - impressions: - id: eb874c98-bf4d-40a9-ae6d-fcf4cecb535c @@ -2219,8 +2219,8 @@ components: minLength: 1 examples: - eb874c98-bf4d-40a9-ae6d-fcf4cecb535c - Pageview: - title: Pageview + PageView: + title: Page View type: object description: > A page view represents the navigation of the user throughout the page. They are considered @@ -2260,7 +2260,7 @@ components: - instore examples: - onsite - PageviewsArray: + PageViewsArray: title: Page views description: An array of page view events properties: @@ -2269,7 +2269,7 @@ components: minItems: 0 maxItems: 50 items: - $ref: "#/components/schemas/Pageview" + $ref: "#/components/schemas/PageView" securitySchemes: HTTPBearer: description: A valid API key generated in Topsort's UI. From eb43afc48c3159350b53ecfd11cf331ef8722804 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johan=20Bergstr=C3=B6m?= Date: Mon, 10 Nov 2025 16:48:23 +0000 Subject: [PATCH 09/10] chore: switch from anyOf to decorated properties --- topsort-api-v2.yml | 49 ++++++++++++++++++++++++++++++++-------------- 1 file changed, 34 insertions(+), 15 deletions(-) diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml index 56ff278..ce92534 100644 --- a/topsort-api-v2.yml +++ b/topsort-api-v2.yml @@ -1914,11 +1914,40 @@ components: - vendor EventsRequest: type: object - anyOf: - - $ref: "#/components/schemas/ImpressionsArray" - - $ref: "#/components/schemas/ClicksArray" - - $ref: "#/components/schemas/PurchasesArray" - - $ref: "#/components/schemas/PageViewsArray" + additionalProperties: false + properties: + impressions: + title: Impressions + description: An array of impression events + type: array + minItems: 0 + maxItems: 50 + items: + $ref: "#/components/schemas/Impression" + clicks: + title: Clicks + description: An array of click events + type: array + minItems: 0 + maxItems: 50 + items: + $ref: "#/components/schemas/Click" + purchases: + title: Purchases + description: An array of purchase events + type: array + minItems: 0 + maxItems: 50 + items: + $ref: "#/components/schemas/Purchase" + pageviews: + title: Page views + description: An array of page views + type: array + minItems: 0 + maxItems: 50 + items: + $ref: "#/components/schemas/PageView" examples: - impressions: - id: eb874c98-bf4d-40a9-ae6d-fcf4cecb535c @@ -2038,16 +2067,6 @@ components: - instore examples: - onsite - ImpressionsArray: - title: Impressions - description: An array of impression events - properties: - impressions: - type: array - minItems: 0 - maxItems: 50 - items: - $ref: "#/components/schemas/Impression" Click: title: Click description: > From 5f586bbcde666591648b256f230a4ded8782950f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johan=20Bergstr=C3=B6m?= Date: Mon, 10 Nov 2025 17:30:47 +0000 Subject: [PATCH 10/10] chore: remove unused schemas --- topsort-api-v2.yml | 30 ------------------------------ 1 file changed, 30 deletions(-) diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml index ce92534..3e2bc93 100644 --- a/topsort-api-v2.yml +++ b/topsort-api-v2.yml @@ -2133,16 +2133,6 @@ components: - instore examples: - onsite - ClicksArray: - title: Clicks - description: An array of click events - properties: - clicks: - type: array - minItems: 0 - maxItems: 50 - items: - $ref: "#/components/schemas/Click" Purchase: title: Purchase description: > @@ -2219,16 +2209,6 @@ components: minLength: 1 examples: - v_8fj2D - PurchasesArray: - title: Purchases - description: An array of purchase events - properties: - purchases: - type: array - minItems: 0 - maxItems: 50 - items: - $ref: "#/components/schemas/Purchase" EventIdentifier: type: string description: > @@ -2279,16 +2259,6 @@ components: - instore examples: - onsite - PageViewsArray: - title: Page views - description: An array of page view events - properties: - pageviews: - type: array - minItems: 0 - maxItems: 50 - items: - $ref: "#/components/schemas/PageView" securitySchemes: HTTPBearer: description: A valid API key generated in Topsort's UI.