Write official PostHog event spec

[mariusandra]

There are about 101 ways to send events to PostHog, and various libraries implement different ways. Some send a random context object. Some put $set in properties, some in the event body. Some send timestamps. Some also sent_at fields. Some set a random message_id, some a messageId, some send nothing. And so on.

Instead of this flexible "legacy" situation, I propose we formalise and document the golden standard "Posthog Event Schema version 2". This way we'll have something to aim towards when cleaning up all the libraries. We'd have to make everything still backwards compatible, but at least we'll have the right way.

[mariusandra]

More cases:

• the posthog-ruby library puts the distinct_id inside properties, and sends a null distinct_id in the event body: https://github.com/PostHog/posthog-ruby/blob/master/lib/posthog/field_parser.rb#L66-L68

• the posthog-js library sends a distinct_id in both the event body and properties: https://github.com/PostHog/posthog-js/blob/master/src/posthog-core.js#L838-L857

• Why is $set on the top level of a user, but $increment inside properties?

[soccerboymalloy-patriot]

This would be really helpful for my team! Is this being considered for prioritization?

We're developing an application where we'd like to publish events from our backend, but it's written in C# which means we have to manually create API requests. The only formal documentation I can find is this page, which leaves a lot out.

Some put $set in properties, some in the event body. Some send timestamps. Some also sent_at fields. Some set a random message_id, some a messageId, some send nothing. And so on.

I've been scratching my head over some of these exact fields. I started looking through some of your API code for answers, but logic like this, while helpful to see what I can do, doesn't help me feel comfortable about what I should do.

In addition, it's not clear to me what the recommended approach is do simple things like update person properties. Do I make an identify call? I only see an example of that being done via a batch call - can I do a one off identify call by calling the capture endpoint and specifying "type": "screen" and "event": "$identify" (not that I know what "type" even does/means)? Or should I just use the person PATCH endpoint?

I agree that the flexibility and options with the current approach is more scary than helpful for my team. We're going to be doing a lot of trial and error and crossing our fingers to get things working.

[posthog-bot]

This issue hasn't seen activity in two years! If you want to keep it open, post a comment or remove the stale label – otherwise this will be closed in two weeks.

[posthog-bot]

This issue was closed due to lack of activity. Feel free to reopen if it's still relevant.