mark nottingham

How do we use SOAP Headers?

Tuesday, 27 April 2004

Web Services

Way back when in the XML Protocol Working Group, one of the concerns that came up was the processing model for SOAP headers. In particular, while SOAP 1.2 does a good job of specifying how that model operates, a key peice of information is missing; how to order the steps in processing a message.

In other words, if you get a SOAP message that has headers to, say, encrypt a message, and also to apply an XSLT stylesheet, you have no idea what order you’re supposed to do those things in. Oops.

This was a big concern, and we spent a fair amount of time arguing about it. As Jeff Mogul’s ever-so-useful paper (PDF; boy, am I citing this one a lot) about HTTP’s processing model shows, this is important to get right for most protocols.

I was thinking about this the other day, a bit puzzled that this wasn’t a more urgent problem; after all, we’ve had SOAP for a little while, and it doesn’t seem to be the end of the world. To help figure out why, I did a quick survey of defined headers and tried to classify them. Here are the results.

Header Classifications

I ended up with a fairly small set of classes, based on the headers that I saw; transformative - changes the message Infoset when applied by the processing model descriptive - describes the message content without being critical to its interpretation policy - affects behaviour of the targeted receiver, not tightly bound to message semantics metadata - message data/metadata piggybacking - (potentially) unrelated to the message body any - any or all of the above

And here are the headers;

WS-Addressing wsa:MessageID - metadata wsa:RelatesTo - metadata wsa:To - metadata wsa:Action - metadata wsa:From - metadata wsa:ReplyTo - policy wsa:FaultTo - policy wsa:Recipient - metadata [ReferenceProperties] - any

WS-ReliableMessaging wsrm:Sequence - metadata, policy wsrm:SequenceAcknowledgement - piggybacking wsrm:AckRequested - piggybacking

WS-Security [pdf] wsse:Security - transformative

WS-I Basic Profile wsi:Claim - metadata, descriptive

SOAP Resource Representation Header rep:Representation - metadata / policy

WS-Coordination wscoor:CoordinationContext - policy

WS-Eventing wse:SubscriptionEnd - piggybacking

What Does This Tell Us?

To be fair, I haven’t included a number of defined SOAP headers, because I’m not as familiar with other specs; if someone could take a stab at classifying them, I’d appreciate it. Also, I’m sure that I’ve misclassified some; opinions, rants and corrections appreciated.

Even with those caveats, though, a few interesting trends are readily apparent:

Transformative headers are few and far between, so we don’t yet have the problems that XMLP worried about. There is some need for this, though, because WS-Security defines both encryption and signing functions, and there could be ordering problems there. One eventual solution might come out of the W3C.

Piggybacking is fairly rampant, which is interesting; it’s either premature optimisation, or it really speaks to the need for a logically separate channel for control messages, rather than using headers attached to specific messages (Are those the BEEP folks I hear chuckling in the last row?). It is good to see that most are them are defined in such a way that they can be used as first-class messages as well.

Finally, header-based policy is also widespread; it would be a shame if a lot of that kind of functionality got locked into headers and then duplicated in other mechanisms.


3 Comments

Werner Vogels said:

Mark, great classification!

Why did you pick ‘policy’ for wscoor:CoordinationContext, instead of ‘metadata’? It appears to me that the coordination context does not change the behavior of the receiver, but allows it to operate ‘within context’. For example in an atomic transaction the context will carry the identification of the transaction, which doesn’t change the behavior of the receiver. One could maybe argue that the context affects the behavior of the coordinator (e.g. it runs a 3 phase commit instead of 2PC base on info in the context), but I think selecting the type of coordination service is similar to an action header.

BTW I think recognizing the relations between header fields will become very important when we want boxcarring to work in the future.

Wednesday, April 28 2004 at 11:12 AM

John Kemp said:

Hi Mark,

I think this is quite interesting work, and thus I’ve classified the Liberty ID-WSF SOAP Binding (see http://www.projectliberty.org/specs) headers in a similar fashion:

ServiceInstanceUpdate - policy/metadata Timeout - policy CredentialsContext - policy Correlation - metadata Provider - metadata ProcessingContext - policy Consent - metadata UsageDirective - policy

Given the general lack of transformative headers, one can certainly see why ordering problems have not been perceived as an issue. However, for example, if multiple policy-type headers were added by the requester, would it not be the case that if the processing order of those headers is left up to the receiver, results certainly may vary from the client’s expectation - ie. policies get applied in some order by the receiver, resulting in a different response than the requester might have expected?

Monday, May 3 2004 at 11:39 AM