Skip to content

MassTransit wire mapping

Warning

MassTransit 9 is commercially licensed. MassTransit 9 and later is under the MassTransit Commercial Software License Agreement (massient.com/license), a paid subscription with no exemption for testing. This format was captured from MassTransit 8, which is Apache-2.0, and the module's own .NET test programs stay on 8.x (envelope-masstransit#1). The Go module itself does not depend on MassTransit.

MassTransit() writes one JSON object as the body, with the content type application/vnd.masstransit+json in Wire.ContentType. It writes no transport headers: Wire.Headers is nil.

What it writes

An event with every attribute, as Encode renders it (formatted here; the body is one line):

{
  "messageId": "7f2c1a9e-0000-4000-8000-000000000001",
  "sourceAddress": "Shop.Sales",
  "messageType": ["urn:message:Shop.Messages.PlaceOrder"],
  "message": {"Order": "4172"},
  "sentTime": "2026-10-24T08:27:24.1234567Z",
  "headers": {
    "ce-datacontenttype": "application/json",
    "ce-subject": "order-4172",
    "tenant": "continuity"
  }
}
Event Envelope member Notes
ID messageId Must be a UUID: eight, four, four, four and twelve hex digits with dashes, in either case. No braces. Otherwise Encode returns ErrUnrepresentable.
Source sourceAddress Written as it is. It is a Uri in .NET, so a relative source such as /orders arrives there as file:///orders.
Type messageType, one entry "urn:message:" before the type, which masstransit.MessageTypePrefix holds. For a .NET consumer of Contracts.OrderCreated, the type is Contracts:OrderCreated.
Data message Spliced in byte for byte, so whitespace survives. An event without data is written as {}.
Time sentTime In UTC, with seven fractional digits, always: 2006-01-02T15:04:05.0000000Z. Truncated to 100 ns. Omitted when Time is zero.
Subject headers["ce-subject"] Omitted when empty.
DataSchema headers["ce-dataschema"] Omitted when empty.
DataContentType headers["ce-datacontenttype"] Omitted when empty.
each Extensions entry headers[name] The name is the extension's, in lower case, as a JSON string.
SpecVersion none Not written. It is filled in as 1.0 when read.

headers is always written, as {} when there is nothing to put in it. The header names are the constants masstransit.HeaderSubject, HeaderDataSchema and HeaderDataContentType.

What it reads

Envelope member Event Notes
messageId ID A string. Not a UUID is ErrUnrepresentable: the ID is never re-minted or blanked, because a new one would defeat deduplication. Absent or null leaves it empty, which Validate refuses as ErrMissingAttribute.
sourceAddress Source A string. Absent or null leaves it empty, which Validate refuses.
messageType[0] Type With urn:message: trimmed. Not an array of strings is ErrInvalidEnvelope.
messageType[1:] Foreign See below.
message Data The JSON as it arrived, whitespace included. Absent or null leaves Data empty.
sentTime Time Parsed as RFC 3339. Not a time is ErrInvalidTime. Absent leaves Time zero.
headers["ce-subject"] Subject A string.
headers["ce-dataschema"] DataSchema A string.
headers["ce-datacontenttype"] DataContentType A string. A message MassTransit itself sent has none, so DataContentType is empty.
headers[name], a string and name a valid extension name Extensions[name] See Carry headers.

SpecVersion is always set to 1.0. After assembling the event, Decode runs Validate, so the usual refusals apply to what was read, such as an extension with an empty value or a control character in an attribute.

The first problem found is the error returned, in a fixed order, and the event is returned with it, holding whatever could be read.

What becomes Foreign

The event has no place for these, so they are Foreign.Headers, and Foreign.Conflicts where noted.

Source Key in Foreign.Headers Value
any envelope member other than the six above, when not null the member's name: requestId, correlationId, conversationId, initiatorId, destinationAddress, responseAddress, faultAddress, expirationTime, host A string member's value, or any other member's JSON text
messageType after the first messageType Each remaining entry, with its urn:message: prefix
an envelope header that is not an attribute or an extension, such as Tenant or MT-Activity-Id the header's name The string; a header that is not a string keeps its JSON text, so 2 is "2"
a transport header the envelope did not mirror the header's name Its values

Envelope members whose value is null are not listed. The host object is kept as its JSON text.

A null inside headers is not treated the same way in v0.1.0, the released version. "priority": null is read as an extension with an empty value, which Validate refuses as ErrMissingAttribute, and "Tenant": null is a foreign header holding one empty string. From the next release it is absent too, neither an extension nor a foreign header (envelope-masstransit!9).

Transport headers

Wire.Headers is read after the body. In order:

  1. content-type, in any case, and a header with no values, are ignored.
  2. A header named exactly traceparent becomes the extension traceparent when the envelope's headers did not carry one. A case variant such as Traceparent does not: it is foreign.
  3. A header whose key the event already holds, with the same single value, only mirrors the envelope and is not listed. MessageId mirrors ID, and ce-subject, ce-dataschema, ce-datacontenttype and an extension's name mirror theirs.
  4. Any other header is added to Foreign.Headers under its name, unless the bag already holds that value.
  5. A header the event holds under a different value is a conflict: the envelope's value stays in the event, the transport's goes in Foreign.Headers under its own key, and the key is in Foreign.Conflicts, sorted.

From a real producer

testdata/full.txt in the module is a message MassTransit 8.5.10 sent itself, with a message ID, a correlation ID, a Tenant header and a traceparent set inside an activity. It reads as:

Event or Foreign Value
ID 7f2c1a9e-0000-4000-8000-000000000002
Type Capture:OrderCreated
Extensions traceparent only
Foreign.Headers keys MT-Activity-Id, Tenant, conversationId, correlationId, destinationAddress, host
Foreign.Conflicts none: the transport's MessageId, Tenant and traceparent only mirrored the envelope

plain.txt, a bare Publish, has foreign keys conversationId, destinationAddress and host. Both are checked in the module's tests.