[JuroUhlar]

Note

Schema review prototype, do not merge. This is to test the schema Event split (EventDevice | EventEdge) as part of reviewing koala#18895.

INTER-2457 | stacked on #493 | port of closed spike #465 | koala#18895

Why

Python, PHP, Go, Java and .NET can't take the EventDevice | EventEdge union without a breaking change. This PR flattens Event back into one object for them, so their generated code stays the same, while Node and the docs keep the union.

Things to note

• The flatten has to run before liftOneOfSharedProperties / resolveAllOf. Each variant defines source as $ref: EventSource plus a sibling const. If source gets rewritten into allOf: [$ref, const] first, resolveAllOf inlines it as type: string, enum, which breaks the SDKs. A guard test pins this down.
• Compared with the published schemas, the flat and normalized Event differ only in description: flat SDKs get their own text saying which properties each source can have, and that a missing source means device. Properties, order, $refs, x-platforms and required all match.
• Things left out of the spike: its liftOneOf change (it also inlined EventSource for Node and the docs), its EventBase schema edits (the schema now comes from INTER-2457: [schema review prototype] Sync v4 Event union from koala#18895 #493), and removing removeEdgeTransformer (/edge stays out of the SDK schemas).

Change outline

Which schema each SDK gets:

  fingerprint-server-api-v4.yaml             Node, docs     Event = EventDevice | EventEdge   (same as #493's build)
+ fingerprint-server-api-v4-flat.yaml        Python, PHP    Event flat, source optional
  fingerprint-server-api-v4-normalized.yaml  Go, Java, .NET Event flat, source optional (+ start/end split, as before)

Transformer order for the flat and normalized outputs (transformSchema.ts):

  resolveRef → resolveExternalValue → remove triggered_by
+ flattenNamedSchemaOneOf('Event', optional: [source])     # flat / normalized only
  liftOneOfSharedProperties → resolveAllOf
  … SDK transformers (BotInfo inline → remove unused)
+ normalized only: flat pipeline + split start/end

The flattened Event:

flattenNamedSchemaOneOf('Event')
  replaceOneOf(EventDevice, EventEdge)
    union of properties, in EventDevice order
    keep x-platforms from EventDevice when EventEdge has none     # replaceOneOf.ts change
    required = in every variant → [event_id, timestamp, source]
  on $ref properties: drop merged enum/const                      # source → plain $ref EventSource
  set the flat-specific description
  remove source from required                                     # → [event_id, timestamp]

source stays optional in flat SDKs because the published Event has it optional, and making it required would break them. Customers also load stored webhooks and events through these models, and payloads stored before source existed don't have it. The union variants require source only because a discriminator should be required, and a flat Event has no discriminator. Requiring it is left for the next major SDK version, which would switch to the union and treat a missing source as device.

Files:

utils/
├── replaceOneOf.ts                                   # keep earlier variant's x-platforms
├── mocks/publishedEvent.yaml                         # main's Event, the guard test baseline
└── transformers/
    ├── flattenNamedSchemaOneOfTransformer.ts (+spec) # new
    └── transformSchema.ts (+spec)                    # new flat pipeline, flatten-first order, guard test
vite.config.ts                                        # new v4-flat output
.github/workflows/sync-server-side-sdks-schema.yml    # Python, PHP read v4-flat

[changeset-bot]

⚠️ No Changeset found

Latest commit: 78d51f2

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

Schema Diff vs Published Schemas

• Generated at: 2026-10-15T20:22:38.181Z
• Published source: https://fingerprintjs.github.io/openapi/schemas
• Compared schemas: 9
• Changed schemas: 4 (1 new)

Detailed changed-lines patches were omitted because the complete report exceeds GitHub’s comment size limit.

fingerprint-server-api-v4-flat.yaml 🆕 NEW

Summary: +7 added, -0 removed, ~0 modified

Added elements (7)

• /components
• /info
• /openapi
• /paths
• /security
• /servers
• /tags

Removed elements (0)

None

Modified elements (0)

None

fingerprint-server-api-v4-normalized.yaml

Published URL: https://fingerprintjs.github.io/openapi/schemas/fingerprint-server-api-v4-normalized.yaml
Summary: +0 added, -0 removed, ~1 modified

Added elements (0)

None

Removed elements (0)

None

Modified elements (1)

• /components/schemas/Event/description

fingerprint-server-api-v4-with-examples.yaml

Published URL: https://fingerprintjs.github.io/openapi/schemas/fingerprint-server-api-v4-with-examples.yaml
Summary: +4 added, -5 removed, ~2 modified

Added elements (4)

• /components/schemas/Event/discriminator
• /components/schemas/Event/oneOf
• /components/schemas/EventDevice
• /components/schemas/EventEdge

Removed elements (5)

• /components/schemas/EdgeResponse
• /components/schemas/Event/additionalProperties
• /components/schemas/Event/properties
• /components/schemas/Event/required/0
• /components/schemas/Event/required/1

Modified elements (2)

• /components/schemas/Event/description
• /paths/~1edge/post/responses/200/content/application~1json/schema/$ref

fingerprint-server-api-v4.yaml

Published URL: https://fingerprintjs.github.io/openapi/schemas/fingerprint-server-api-v4.yaml
Summary: +4 added, -3 removed, ~1 modified

Added elements (4)

• /components/schemas/Event/discriminator
• /components/schemas/Event/oneOf
• /components/schemas/EventDevice
• /components/schemas/EventEdge

Removed elements (3)

• /components/schemas/Event/properties
• /components/schemas/Event/required/0
• /components/schemas/Event/required/1

Modified elements (1)

• /components/schemas/Event/description

[github-actions]

🚀 Following releases will be created using changesets from this PR:

openapi@3.10.0

Minor Changes

• events: Model Event as a union of EventDevice and EventEdge, discriminated by source, in the docs and the Node SDK schema. Other SDK schemas keep a single flat Event with optional source. (00cc797)

Patch Changes

• Set the Server API v3 deprecation date to October 31, 2026 and the end-of-life date to October 31, 2027 in the endpoint descriptions (9790b00)