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:
content-type, in any case, and a header with no values, are ignored.- A header named exactly
traceparentbecomes the extensiontraceparentwhen the envelope'sheadersdid not carry one. A case variant such asTraceparentdoes not: it is foreign. - A header whose key the event already holds, with the same single value, only mirrors the envelope
and is not listed.
MessageIdmirrorsID, andce-subject,ce-dataschema,ce-datacontenttypeand an extension's name mirror theirs. - Any other header is added to
Foreign.Headersunder its name, unless the bag already holds that value. - 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.Headersunder its own key, and the key is inForeign.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.