This specification contains the definitions of the Message Header elements required in an ebXML Message. The purpose of the header elements is to contain the additional information required to enable electronic documents to be transported between two services. The key consideration when developing this specification was to provide data elements that enable software that is aware of this specification to:

• route messages to service handlers (these can be applications) that can process the message payload
• easily identify the content of the Message header and payload(s) within the message
• report errors found and understand errors received in the Message Header
• provide acknowledgements that messages have been received and placed in persistent storage
• provide reliable, at most once, delivery of a message.

Note that the reliable delivery of messages is described in a separate specification (under development).

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119].

This specification is the first publicly available version of the ebXML Message Header. The header elements that have been identified represent those that are considered by the members of the ebXML Transport, Routing and Packaging Working group, to be the minimum required that provide the functionality outlined in the abstract. They meet subset of the requirements described in the ebXML Overview and Requirements document [1].

One of the objectives of ebXML Transport, Routing and Packaging is to develop specifications that "enable existing 'messaging' solutions to 'bridge' to the ebXML solution".

Therefore later versions of this specification will contain additional or modified elements required to meet this need.

This version of the specification is not a standard of any kind. Developers and implementers must not rely on this specification and it should be used for prototype use only.

This specification will be one of a set of related specifications that will be delivered in phases. These specifications will cover:

• ebXML Messaging Overview - describes the relationship between the various ebXML specifications described below and how they are used in a compliant way with each other (under development)
• ebXML Message Header Specification - this specification
• ebXML Message Envelope Specification - how to wrap header's and bodies in a MIME wrapper [2]. This will be extended in the future to describe how to wrap headers and bodies in an XML envelope, although the XML Envelope may be developed as a separate specification. The specification also covers:

• ebXML Messaging over HTTP - how to send ebXML Messages using HTTP or HTTPS
• ebXML Messaging over SMTP - how to send ebXML Messages using SMTP
• supplements for other protocols will be contained in separate documents

• ebXML Reliable Messaging Specification - how to achieve robust reliable once-only delivery of message in a vendor neutral, transport independent way (under development)
• ebXML Messaging Security and Signature Specification - this will cover (under development):

• how to use S/MIME with ebXML Messages
• how to use PGP with ebXML Messages
• how to use IETF/W3C XML Digital Signatures with ebXML Messages

• ebXML Common Processes contains specifications of commonly used processes that are applicable to many situations (under development):

• ebXML Message Set Status Inquiry Specification - how to inquire on the current status of a message set
• ebXML Service Availability Specification - how to determine if a Service is up and running
• ebXML Messaging Discovery Specification - how to determine the parameters associated with a Service from the ebXML Messaging perspective.
• ebXML Publish & Subscribe Specification - how to do Publish and Subscribe securely using any of the above

• ebXML Messaging Audit Trail Specification - how to use ebXML to create audit trails of the messages exchanged during a message set (under development).

The remainder of this specification contains:

• Message Structure - A description of the structure of the message header and the data items contained within them
• Header Levels - An introduction to the concept of using the data items in the message header in different ways and combinations depending on the nature of the problem which this specification is being used to solve
• Template Document Exchanges - An introduction to the different sequences in which messages of different Message Types are exchanged
• Definitions - Descriptions of the terms used within this and other ebXML Transport Routing and Packaging Specifications.
• Schemas, DTD Definitions and Examples - XML Schema and DTD definitions for the message headers described within this specification. <EdNote>This does not yet exist.</EdNote>
• References - References to other documents and specifications that are related to this specification
• Acknowledgements - References to the other people and organizations that have contributed to this specification
• Authors' Address - How to contact the main authors of this specification

The structure of a message is illustrated by the diagram below. Change picture to add Message Manifest

A Message Consists of:

• an outer Transport Envelope, such as HTTP or SMTP, that wraps,
• a transport independent Message Envelope [2] that contains the two main parts of the Message itself by wrapping:

• a Header with one or more header parts inside, (the subject of this specification), and
• a Payload that contains the document(s) associated with the message.

The Header is a single XML document with a number of Header Parts within it where each Header Part is a separate XML element. In general, separate header parts are used where:

• different software is likely to be used to generate that header part,
• the structure of the header part might vary independently of the other header parts, or
• the data contained in the header part may need to be digitally signed separately from the other header parts.

Using this principle, the following main header parts have been identified:

• a Message Manifest contains a list of references to he other parts of the Message. This includes references to:

• the Header Parts inside the Header,
• the Message Payload Parts.

• a Message Header header part, that contains the additional data that needs to be associated with the Documents in a Message so that they can be sent to and successfully processed by a Party. This data is typically set by the application that determines that a message needs to be sent. The data remains the same no matter what method or protocol is used to transport the message
• an Error Message header part that contains information about errors contained in an earlier message. <EdNote>It is not clear whether this should be: a) in the Message Header or in the Message Payload, or b) be used just to highlight errors in the Message Header, or errors in any XML document.</EdNote>

The Message Header and Message Manifest header parts are the only header parts that are present in every Message. Any additional header parts are optional.

The following provides explanations as to why these header parts have been defined separately.

Message Manifest is held separately since the software that assembles the message from its constituent parts is likely to be separate from the software that creates the other parts

Message Header is held separately since the information it contains will frequently be specified by the business (or other) application that is generating the message. It is also held separately header part so that it may be digitally signed and its signature preserved, no matter where the message is routed or sent..

Descriptions of each Header Part and their element content follow.

The following is an overview of each of the elements in a ebXML Message Header.

• Normal
• Acknowledgement
• Error

1. Service Type Identifies the business service interface that should act on the payload in the message. It is a string.

Service Types shall be unique within the domain in which they are being used. URN's may be considered suitable for this purpose.

<EdNote> Need to coordinate with the Business Process Group to align with naming and semantics of their business model. </EdNote>

2. Intent Intent specifies the reason or intention for sending a message.

Intent shall be unique within a Service Type. It is a string.

<EdNote> Need to coordinate with the Business Process Group to align with naming and semantics of their business model. </EdNote>

3. Message Set Data Message Set Data contains information that describes a set of related Messages. All the data in this element is identical in all the messages in a Message Set. If a digital signature on a message signs the Message Set Data and some other data on the message, it is possible to prove that messages are related. In this way an audit trail of the messages in a Message Set can be provided.
1. Message Set Id This is a globally unique identifier for the Message Set. It is a string. <EdNote> Guidelines on how to specify globally unique identifiers will be provided.</EdNote>
4. Message Data Message Data contains information that describes an individual Message.
1. Message Identifier This is a globally unique identifier for an individual Message. It is a string. <EdNote> Guidelines on how to specify globally unique identifiers will be provided.</EdNote>
2. Message Creation Timestamp This is the time that the Message Header was created. It shall conform to ISO 8601.
3. Ref To Message Identifier If a message is created as the result of processing a previous message, then Ref To Message Identifier contains the Message Identifier of the message that was processed. Otherwise, the value is set to "Not Applicable".
5. Transport Service Level Agreement Id Identifies the transport level Service Level Agreement to be used when sending and receiving this message. Defaults to an ebXML standard Service Level Agreement for a Transport Protocol. It is a string.
6. From Identifies the Party sending the message.
1. Party Id The identifier of the sending Party.
1. Address Context The context used to resolve the sending Party Address. It is an optional string. It is omitted if Address, on it's own is globally unique.
2. Address The address of the sending Party. It is a string. <ED NOTE> Need to describe how address and address context are used in an explanatory note in the data dictionary. </ED NOTE>
7. To Identifies the Party receiving the message.
1. Party Id The identifier of the receiving Party.
1. Address Context The context used to resolve the receiving Party Address (Also see From)
2. Address The address of the receiving Party. (Also see From)
8. Reliable Messaging Info
1. Guaranteed Delivery Indicates the degree of reliability of delivery. Valid values:

• Unspecified (default)
• AtMostOnce

This shall be the first header part in the ebXML Header. It identifies the various header parts and payloads contained in the ebXML message envelope. The purpose of the Message Manifest is to make it easier to directly extract a particular document (or part of a document) associated with the Message.

• the other header parts that are present in the Message Header
• payload(s) contained within the Payload part of the message, or
• URLs to data associated with the message that are held elsewhere

1. Document Reference Contains a reference to a part of a message. This value shall occur one or more times.
1. Document Identifier An identifier for document. It is a string.

If the referenced document is within the Message then the Document Identifier shall be unique within the Message Id. It may also be globally unique.

2. Document Label A textual description of the header part or payload referenced by the Document Identifier. It is an optional string. The purpose of the Document Label is to assist in the locating a document that is used for a particular purpose.

Contains descriptions of and references to one or more locations in a message where errors have been detected.

The part of the specification describes valid sequences for exchanging messages. It consists of two parts:

• a section that describes the various Message Types (see the description of the Message Header), and
• a section that describes how those message types may be used together in Template Document Exchanges to support different types of interactions.

A Message Type contains information that can be used by the recipient of a message to determine how it should be handled and therefore what types of messages should be sent in return.

A message may be one of the following types:

• Normal Message
• Acknowledgement Message
• Error Message

Each of these is described below in more detail.

Normal Messages are sent to request that another party or server carry out a service or process of some kind. In more detail the messages that may result from processing a Normal Message are indicated in the diagram below.

Examples of Normal Messages include:

• requesting the processing of a new purchase order
• providing a purchase order response
• requesting that a previous purchase order is changed
• requesting a refund of a payment as a result of a problem
• requesting the review of a legal document
• the results of a review of a legal document
• requesting information on the services a business provides.

An Error Message is a Message that reports on a problem in an earlier Message that prevents the earlier Message from being processed in a normal way. Examples of an Error Message include:

• an Error Message reporting that an XML document was invalid or did not conform to its XML schema
• an Error Message reporting a Transient Error that the Server processing a Message is busy and therefore the original Message should be resent at a later point in time
• an Error Message that reports on an error in the underlying transport protocol.

Error Messages contain an Error Message Header Part that indicates the nature of the error that has been found.

More details on the message that may be generated as a result of processing an Error Message are indicated by the diagram below.

It is possible that an Error may be found in an Error Message which, in turn, also contains errors. This can result in an infinite loop. To avoid this, Error Messages are not sent, for errors found in Error Messages that are reporting errors in another earlier Error Message.

It is split into two sections:

• Documents, Parties, Messages and Document Exchanges, and
• Services and Message Sets

Words or phrases that are defined elsewhere are highlighted in italics.

This section describes how Parties, such as buyers and suppliers, customers and merchants, can transmit Documents contained in Messages in order to request execution of Services.

All the Documents and other data in a Message are contained within an outermost Message Envelope.

A Message can optionally include Digital Signatures so that:

• the identity of the Party sending the Message can be authenticated
• any changes to the message and the documents they contain can be detected.

Services are requested by sending one or more Documents in a Request Message to a Party who then:

• processes the Request Message by carrying out a Service and
• optionally generates a Response Message to indicate the result.

At a minimum a Document Exchange consists of a Request Message and an optional Response Message although there might be additional Exchange Messages between the Request Message and the Response Message.

Error Messages are used to report permanent or transient problems or errors in a Message.

More detail is provided below.

A Document is any data that can be represented in a digital form.

Examples of Documents include:

• a set of XML Elements
• an XML Document
• an HTML Document
• a word processing file
• an Adobe Acrobat PDF file
• a binary file
• part of larger document.

A Party is a company, organization or individual or other entity that can generate, receive or relay Documents. Parties are identifies by a Party Address.

Examples of a Party include:

• a Merchant
• a Customer
• a Lawyer
• a Bank
• a government department or agency
• an intermediary or agent
• a software agent

A Party is also used to refer to systems or servers that are carrying out Services or processes on behalf of a Party.

The address of a party is in two parts:

• an optional Address Context, and
• the Address itself.

In combination, Address Context and Address must be globally unique.

The Address Context specifies the domain of the address, or the authority that allocated the Address to the Party. It is optional since the Address, on its own, may be globally unique. Examples of Address Context include:

• Duns - indicating the Address is a Dun & Bradsteet (DUNS) allocated number
• Telephone - indicate that the Address is an international Telephone number

Address identifies the individual Party within the Address Context. Examples of Address include:

• the Actual Duns number of the party
• a telephone number
• a URN - since URNs are globally unique, no Address Context is needed.

A Message is data that is sent from one Party to another.

All the data in a Message is contained within a Message Envelope.

A Message consists of a Message Header and a Message Body

Examples of a Message include:

• a Purchase Order that is sent by a buyer to a supplier
• an Invoice that is sent by the supplier back to the buyer
• a request to make a payment of $50 sent to a Credit Card acquirer
• the authorization received from a Credit Card acquirer as a result of making a payment
• Status indicating the success or failure of a Service

The Message Manifest contains references to the other documents, apart from the Message Routing Information document, that are contained within the same Message Envelope.

The purpose of the Message Manifest is to facilitate locating and validating that all required Documents contained within the Message Envelope are present.

Examples of the types of documents that might be referenced by a Message Manifest include:

• a Purchase Order
• a Purchase Order and a picture of the requested goods
• a Purchase Order and a digital signature

A Message Envelope is the outermost container for a Message. It can be such things as:

• an XML Document, or
• a multi-part MIME message

An Exchange Message is a Message that is sent between one Party and another after the sending of the initial Request Message and before the sending of the final Response Message.

Examples of Exchange Messages include:

• intermediate messages that are part of a Payment Protocol
• a counter offer to an offer made as part of a negotiation.

An Error Message is a Message that reports on a problem in an earlier Message that prevents the earlier Message from being processed in a normal way.

Examples of an Error Message include:

• an Error Message reporting that an XML document was invalid or did not conform to its XML schema
• an Error Message reporting a Transient Error that the Server processing a Message is busy and therefore the original Message should be resent at a later point in time
• an Error Message that reports on an error in the underlying transport protocol.

A Document Exchange is a generic term for either a:

• a One-Way Document Exchange,
• a Simple Document Exchange, or
• a Multiple Round Trip Document Exchange.

A One-Way Document Exchange consist of:

• a One-Way Message sent from one Party to a second Party, followed by
• an optional Acknowledgement Message sent by the second party back to the first party, followed by
• an optional Error Message if an error was detected in the One-Way Message

Examples of a One-Way Document Exchange include:

• a supplier sending catalog updates to their buyers
• a supplier offering goods for sale by auction

A Simple Document Exchange consists of:

• a Request Message sent from one Party to a second Party, followed by
• an optional Acknowledgement Message sent by the second party back to the first party, followed by

• an optional Error Message if an error was detected in the Request Message, or
• an optional Checked OK Message, if no errors were detected that is sent by the second party back to the first party followed by

• a Response Message that is returned as a result of processing the Request Message.

Examples of instances of a Simple Document Exchange include:

• a Purchase Order sent by a buyer to a seller and the acknowledgement from the seller of its receipt
• a Purchase Order sent by a buyer to a seller and the Invoice that is sent back as a result of fulfilling the order
• sending a document for review by a lawyer followed by the legal opinion that is sent back as a result

A Multiple Round Trip Document Exchange consists of:

• a Request Message sent from one Party to a second Party, followed by
• a series of Exchange Messages that are exchanged between the two Parties until finally
• the either the first or the second Party generates and sends a Response Message back to the other Party.

Examples of Multiple Round Trip Document Exchanges include:

• the exchange of messages required to make a payment using payment method protocols such as [SET] or [Mondex]
• the exchange of messages required to negotiate an agreement on terms and conditions.

A Service is a process that can be carried out by a Party as a result of receiving a Request Message or One-Way Message that requests the execution of that Service.

A Service can consist of either:

• a Document Exchange, or
• a set of Sub-Services

Examples of a Service include:

• a Purchasing Service that enables a customer to purchase goods on-line
• an Order Processing Service that processes an Order and generates a response as a result
• a Payment Service that accepts a payment and provides a receipt
• a Fulfillment Service that fulfills an order at the request of a Merchant.

A Sub-Service is a Service that is executed at the request of and as part of another Service.

Examples of Sub-Services include:

• a payment service that occurs as part of a purchase
• a tax calculation service that calculates the tax due as part of an order processing service.

A Service Choreography is a description of the dependencies that control the sequence and choices that determine which Sub-Services are executed when carrying out a Transaction.

The Sub-Services in a Service will have dependencies between them. Dependencies can be:

• Serial. One Sub-Service must start only after the completion of another Sub-Service
• Alternative. One Sub-Service may be executed as an alternative to another
• Iterative Loop. A Sub-Service may be repeated a variable number of times
• Conditional. The execution of a Sub-Service is conditional on the state of another Service. This may be used in conjunction with Serial, Alternative and Iterative Loop dependencies.
• Parallel. A Sub-Service may execute in parallel with another Service
• Concurrent. A Sub-Service must execute at the same time as another Sub-Service.

An example of a simple Sub-Service Choreography is a Purchase Service that consists of three Sub-Services:

• an Offer Service that conveys an Offer for sale of goods. This Sub-Service has no dependencies and therefore starts first
• a Payment Service that carries out the Payment which has a Serial dependency on the Offer Service
• a Delivery Service that delivers the Digital Goods, that has a Serial Dependency on the Payment Service

A Transaction is an instance of the execution of a Service.

Examples of a Transaction include:

• a Purchase Transaction that buys a Company Report for $20. It consists of three Sub-Service instances:
• an Offer Service instance to buy the Company Report for $20
• a Payment Service instance that accepts a Payment for $20 using a credit card, and finally
• a Delivery Service instance that delivers the Company Report as an HTML web page.
• a Buying Service that consists of the following Sub-Services:

• three Price Negotiation Service instances that negotiate the price of a Photocopier
• a Purchase Order Service instance that places the order for the Photocopier.

Contact information for the Author's of this specification follow.