Writing and Reading Causation ID and Correlation ID

The docs suggest that the causation ID and the correlation ID exist:

Every stream in the event store has metadata associated with it. The Event Store itself supports some values being set in the metadata and you can write your own additional data into stream metadata if you wish (such as how often to snapshot for your own code). All names starting with $ are however a reserved space for internal settings.

I haven’t seen a reference to how and where they are written.

How do I find out how to format an HTTP Post so that causation ID and/or correlation ID are written. Also, how are these data read?

As an aside, it seems like the docs are written for an audience that is starting with some pre-knowledge of the product.




You write those values into the metadata.


“$correlationId”: “eventId”,
“$causationId”: “eventId”


The data can be represented by the following jschema (note that eventId must be a UUID).

      "eventId"    : "string",
      "eventType"  : "string",
      "data"       : "object",
      "metadata"   : "object"

Thanks Chris. I’m still struggling with some ambiguities here… probably because I’ve been told different things by different people on different media tonight.

These are facts that I’ve been given:

Event Metadata

  • An event has applicative data

  • An event has metadata

  • The metadata is written at the same level of containership as the applicative data, but the metadata is distinguished from the business data with a ‘$’ prefix in the key name.

  • The metadata is written at a peer level of containership, with the applicative data contained in a field named ‘data’, and the metadata in a field named ‘metadata’.

The last two are contradictory (which suggests that either both answers are correct or that ambiguity is not an uncommon user experience).

The whole schema as represented by a JSchema thing, I remember seeing it in the docs. If I took it to heart, it would be telling me that I need to be adding a field called ‘eventId’ rather that using the ES-EventId header - unless this is exactly what I should be doing, which means that this is yet more ambiguity.

Still not clear on the details.



Events have data and metadata.

metadata can be your custom things or there are somethings that are
internally understood (those things start with $ like everything else

When posting over http you must use the events+json media type (no
other way to define metadata in other media types). As this media type
includes multiple events you put the id on the event in the media
type. Posting as application/json as example specifies that the body
is the event (hence the usage of header for the id)

See Events media type under
for an example.

Does this help?



Right - you definitely don’t define data and metadata by adding a “$” prefix to those fields at the same level as data. They are two separate properties on the root event object, and most often your custom metadata fields will have no $ prefix.

The $causationid and $correlationid don’t seem to be well documented, but there is discussion of them on this list, etc. There are some mixed messages, as you’ve pointed out that $fields are internal and not meant to be written to, wherein this case it seems they are meant to be written to, but still used internally?

An example of the JSON and an example CURL would be extremely helpful.

I’m not disposed of pre-existing knowledge of the workings and their development over time. The specifics of what is needed is still unclear.



      "eventId" : "your guid",
      "eventType" : "your type",
      "data" : { "whatever" : "foo"},
      "metadata" : {"$causationId" : "id", "$correlationId" : "id"}

post as application/vnd.eventstore.events+json

You can also used multiple. Please excuse any typing errors on iPad.



FYI, I opened a discussion here:

Thanks, Greg.

So in this case it would seem that there is no use of the ES-EventId and ES-EventType headers on the post. Is that the idea?

So, ES-EventId and ES-EventType are not used when using the application/vnd.eventstore.events+json media type? Is that the idea?



Yes as its included in the media type. It also supports multiple events in one post so they don’t make sense at that point (only for a single event)

It also supports multiple events in one post so they don’t make sense at that point (only for a single event)

Oh, right! I wasn’t thinking about it in-detail when you’d mentioned that. Makes total sense.

Will make some tweaks to JSON formatting in our client library and start taking advantage of the custom media type.