Peppol Business Message Envelope (SBDH)

Specification

OpenPeppol AISBL

Peppol Transport Infrastructure

ICT - Models

Peppol Business Message Envelope

(SBDH)

Version: 2.0.1

Status: In use

Peppol Business Message Envelope (SBDH) v2.0.1

Statement of originality

This deliverable contains original unpublished work except where clearly indicated otherwise.

Acknowledgement of previously published material and of the work of others has been made through

appropriate citation, quotation or both.

Statement of copyright

This deliverable is released under the terms of the Creative Commons Licence accessed through the

following link: http://creativecommons.org/licenses/by-nc-nd/4.0/.

You are free to:

Share — copy and redistribute the material in any medium or format.

The licensor cannot revoke these freedoms as long as you follow the license terms.

Peppol Business Message Envelope (SBDH) v2.0.1

Contributors

Martin Forsberg, ESV

Markus Gudmundsson, Unimaze Software

Jostein Frømyr, Difi/Edisys Consulting

Steinar Overbeck Cook

Oriol Bausà, Invinet

Sven Rasmussen, DIGST

Stefano Monti, EPOCA/IntercentER

Philip Helger, Bundesrechenzentrum/OpenPeppol Operating Office

Erlend Klakegg Bergheim, Difi

Bård Langøy, Pagero

Jerry Dimitriou, OpenPeppol Operating Office

Risto Collanus, Visma

Hans Berg, Tickstar

Version History

Version

Date

Change log

1.0.0

2014-01-15

Initial version

1.1

2018-08-31

Added the possibility to specify document type identifier scheme and process

identifier scheme

Added the possibility to specify additional attributes

1.1.1

2018-09-28

Fixed error in chapter 2.5 in the example of an additional attribute without a value

Added note on attribute case sensitivity in chapter 2.5

1.2

2019-02-01

Added section for non-XML payloads

1.2.1

2020-03-11

Added chapter 2.6 on the Internet Media Type

Remove the references to the Peppol Policy for use of Identifiers 3.x

Updated to the new branding

2.0

2023-03-13

Added chapter 2.5 on country code

Removed the reference to AS2

2.0.1

2023-08-17

Fixed lower bound cardinality of “Scope” element in chapter 2.8

1 Introduction

The Peppol Message Envelope is a customization of the UN/CEFACT Standard Business Document Header

(SBDH) [SBDH]. The customization represents a true subset of the standard XML Schemas and any instance

conformant to this specification is also conformant to the SBDH.

The Peppol Message Envelope makes it possible for Access points to:

Peppol Business Message Envelope (SBDH) v2.0.1

• Route messages without having to access to the business message/data

• Always use the same way of identifying sender/receiver, document type and process

• Overcome issues with namespace or versioning of the payload

• Provide additional attributes that help processing the payload

The Message Envelope can also carry some of the infrastructure elements when using protocols like AS4.

The creation of the Message Envelope is RECOMMENDED to be done already in the system issuing the

business document but it may also be created by a service provider who is preparing the document for

transportation to the receiver’s Access Point. This specification does not recommend any particular setup

with regard to this when the Message Envelope is not created in the issuing system.

1.1 Terminology

The keywords "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 [RFC2119].

1.2 Normative references

[RFC2119] “Key words for use in RFCs to Indicate Requirement Levels”,

https://www.ietf.org/rfc/rfc2119.txt

[Peppol_Policy4] “Peppol Policy for use of Identifiers v4.2.0”,

https://docs.peppol.eu/edelivery/policies/PEPPOL-EDN-Policy-for-use-of-identifiers-

4.2.0-2023-06-19.pdf

[SBDH] “Standard Business Document Header Technical Specification”,

https://www.gs1.org/standards/edi-xml-gdsn-gs1-uncefact-xml-profiles/sbdh-technical-

specifications/1-3

1.3 When to use the envelope

Unless other policies are decided for the Peppol infrastructure, the following principals describe when the

envelope is to be applied.

• Business Message Envelope MUST be applied for all messages exchanged with AS4

2 SBDH Usage

2.1 Party identifiers

The required Receiver party identifier in the Message Envelope header is the one that corresponds to a

Peppol Participant registered in the SML/SMP. Also, the Sender party identifier is required. The structure of

the identifier MUST follow the “Peppol Policy for use of Identifiers v4.x” [Peppol_Policy4].

In cases where the sender is not registered in SML/SMP the identifier of the sender MUST be used as if the

sender would be registered.

Non-normative example:

</Sender>

</Receiver>

Peppol Business Message Envelope (SBDH) v2.0.1

2.2 XML considerations

Since the envelope and included business document becomes one single XML instance, both the envelope

and the business document MUST have the same character encoding. The included business document

MUST be well-formed. The Message Envelope MUST NOT contain another Message Envelope.

2.3 Non-XML Payloads

Several processes that are supported in Peppol require the transportation of binary data and non-XML text

as payload. In order for Peppol to support the transmission of non-XML payloads, an XML wrapper has

been defined that MUST be used for wrapping these payloads.

The XML wrapper defined in this document MUST NOT be used to wrap another XML wrapper neither as

binary nor as text payload.

The following picture depicts the XML schema of the XML wrapper (see chapter 3.2 for the full XML

schema):

Peppol Business Message Envelope (SBDH) v2.0.1

2.3.1 Binary Payloads

In order to support the transmission of binary payloads they should be transformed and packaged as

follows:

1. The binary payload must be Base64-encoded

2. The encoded payload MUST be included inside the XML element BinaryContent. The XML

namespace URI for this element MUST be http://peppol.eu/xsd/ticc/envelope/1.0.

3. The attribute mimeType MUST be set to the respective payload MIME type.

4. For text-based payloads, the optional encoding attribute MUST be used if the source encoding is

different than the encoding of the surrounding XML document. At least the “UTF-8” encoding

MUST be supported.

Non-normative example:

<?xml version="1.0" encoding="iso-8859-1"?>

<StandardBusinessDocument

xmlns="http://www.unece.org/cefact/namespaces/StandardBusinessDocumentHeader">

...

</StandardBusinessDocumentHeader>

<BinaryContent xmlns="http://peppol.eu/xsd/ticc/envelope/1.0"

mimeType="application/vnd.etsi.asic-e+zip"

encoding="UTF-8">

ABCD45678922 ...

</BinaryContent>

</StandardBusinessDocument>

2.3.2 Non-XML Text Payloads

For text data, there is no need of a container, as it can be placed directly as payload inside a TextContent

XML element. The XML namespace URI for this element must be

http://peppol.eu/xsd/ticc/envelope/1.0. The attribute mimeType MUST be set to the respective

payload MIME type.

Note:

• If the text payload contains XML special characters (e.g. ‘<’ or ‘>’), they MUST be escaped using

XML encoding or alternatively the data needs to be wrapped inside a CDATA element so the XML

remains well formed.

• If a text payload is embedded inside the TextContent element, it MUST use the same character

encoding as the surrounding XML, otherwise the BinaryContent data element SHOULD be used.

Non-normative example:

<?xml version="1.0" encoding="iso-8859-1"?>

<StandardBusinessDocument

xmlns="http://www.unece.org/cefact/namespaces/StandardBusinessDocumentHeader">

...

</StandardBusinessDocumentHeader>

<TextContent xmlns="http://peppol.eu/xsd/ticc/envelope/1.0"

100

mimeType="Application/EDIFACT">

101

UNB+UNOA:2+9930711378399:14+7798032711116:14+160927:2252+EW861380947'UNH+186453437+CONTRL

102

:D:96A:UN:EAN002'UCI+F6GVY+7658032710006:14+9930711378111:14+8'UCM+3HHL0+ORDERS:D:96A:UN:

103

EAN008+7'UNT+4+186453437'UNZ+1+EW861380947'

104

</TextContent>

105

</StandardBusinessDocument>

106

2.4 Peppol Process ID and Document Type ID

107

The values of Process ID and Document Type ID are necessary in the SML/SMP discovery process to retrieve

108

the relevant service metadata. Both values should be mapped to the element located at:

109

Peppol Business Message Envelope (SBDH) v2.0.1

StandardBusinessDocument/StandardBusinessDocumentHeader/BusinessScope/Scope/Inst

110

anceIdentifier

111

The respective identifier schemes are to be located in the following element (new in v1.1):

112

StandardBusinessDocument/StandardBusinessDocumentHeader/BusinessScope/Scope/Iden

113

tifier

114

For backwards compatibility reasons (from version 1.1 to 1.0) – if the identifier schemes are missing – the

115

default process scheme identifier cenbii-procid-ubl and the default document type identifier scheme

116

busdox-docid-qns MUST be used.

117

The qualifier located at

118

/StandardBusinessDocument/StandardBusinessDocumentHeader/BusinessScope/Scope/Typ

119

e is used to distinguish the meaning of the values by using codes: DOCUMENTID (for a document type

120

identifier) and PROCESSID (for process identifiers).

121

Non-normative example without identifier schemes:

122

<Scope>

123

<Type>DOCUMENTID</Type>

124

<InstanceIdentifier>urn:oasis:names:specification:ubl:schema:xsd:Invoice-

125

2::Invoice##urn:www.cenbii.eu:transaction:biitrns010:ver2.0:extended:urn:www.peppol.eu:bis:peppol4a:

126

ver2.0::2.1</InstanceIdentifier>

127

</Scope>

128

<Scope>

129

<Type>PROCESSID</Type>

130

<InstanceIdentifier>urn:www.cenbii.eu:profile:bii04:ver1.0</InstanceIdentifier>

131

</Scope>

132

Non-normative example including identifier schemes (possible since v1.1 of this specification):

133

<Scope>

134

<Type>DOCUMENTID</Type>

135

<InstanceIdentifier>urn:oasis:names:specification:ubl:schema:xsd:Invoice-

136

2::Invoice##urn:www.cenbii.eu:transaction:biitrns010:ver2.0:extended:urn:www.peppol.eu:bis:peppol4a:

137

ver2.0::2.1</InstanceIdentifier>

138

<Identifier>busdox-docid-qns</Identifier>

139

</Scope>

140

<Scope>

141

<Type>PROCESSID</Type>

142

<InstanceIdentifier>urn:www.cenbii.eu:profile:bii04:ver1.0</InstanceIdentifier>

143

<Identifier>cenbii-procid-ubl</Identifier>

144

</Scope>

145

2.5 Country codes of the End Users

146

To satisfy the reporting requirements for traffic statistics, the country code of the business level sender

147

MUST be provided. The business-level sender is the C1 node in the 4-corner model. The information

148

provided in the envelope complements the identifier information on the messaging level.

149

The country code MUST be provided in every instance of the envelope. The value of the country code

150

MUST be provided according to ISO-3166-1 in the Alpha-2 notation (e.g. “BE” representing Belgium). Other

151

notations MUST NOT be used. The value MUST follow this case-sensitive regular expression:

152

[A-Z0-9][A-Z0-9]

153

Kosovo is a special case: It can be represented using either the code XK

or the code 1A

154

The country code of C1 MUST be known by the creator of the envelope.

155

XK is a "user assigned" ISO 3166 code not designated by the standard, but used by the European Commission,

Switzerland, the Deutsche Bundesbank and other organisations.

1A is used by the Publications Office of the EU and part of the Peppol PoAC code lists

Peppol Business Message Envelope (SBDH) v2.0.1

The qualifier located at

156

/StandardBusinessDocument/StandardBusinessDocumentHeader/BusinessScope/Scope/Typ

157

e is used to distinguish the meaning of values by using codes: COUNTRY_C1 MUST be used for C1 country

158

code. The country code value itself is mapped to the element located at:

159

StandardBusinessDocument/StandardBusinessDocumentHeader/BusinessScope/Scope/Inst

160

anceIdentifier

161

Non-normative example for an exchange of a business document from a business level sender in Belgium:

162

<Scope>

163

<Type>COUNTRY_C1</Type>

164

165

</Scope>

166

2.6 Additional attributes

167

Additional attributes MAY be provided that can be used to support the processing of the payload. These

168

additional attributes are represented as key-value-pairs.

169

Each additional attribute is represented as a

170

/StandardBusinessDocument/StandardBusinessDocumentHeader/BusinessScope/Scope

171

element.

172

The attribute key must be contained in the child element Type. All attribute keys listed in chapter 2.6.1 are

173

reserved and cannot be used as an additional attribute key. The attribute key MUST be unique within an

174

SBDH. The attribute key MUST be handled case sensitive.

175

The attribute value must be contained in the child element InstanceIdentifier. The attribute value

176

MAY be omitted.

177

Non-normative example with two additional attributes:

178

179

180

<Scope>

181

<Type>TECHNICAL_VALIDATION_URL</Type>

182

<InstanceIdentifier>http://peppol.example.org/as4</InstanceIdentifier>

183

</Scope>

184

<Scope>

185

<Type>TECHNICAL_VALIDATION_REQUIRED</Type>

186

187

</Scope>

188

</BusinessScope>

189

Non-normative example with one additional attribute that has no value:

190

191

192

<Scope>

193

<Type>IndicatorAttribute</Type>

194

195

</Scope>

196

</BusinessScope>

197

2.6.1 Reserved attributes

198

The following additional attribute keys are reserved for internal use in the Peppol network and MUST NOT

199

be used for other purposes than the intended ones.

200

Attribute key

Description

COUNTRY_C1

Country code of original sender of the document (C1) (see

chapter 2.5). Reserved since v2.0 of this specification.

COUNTRY_C4

Reserved for potential future use.

Peppol Business Message Envelope (SBDH) v2.0.1

DOCUMENTID

Specifies the Peppol Document Type Identifier value (see

chapter 2.3)

PROCESSID

Specifies the Peppol Process Identifier value (see chapter 2.3)

TECHNICAL_VALIDATION_URL

Reserved for potential future use.

TECHNICAL_VALIDATION_REQUIRED

Reserved for potential future use.

2.7 Internet Media Type

201

The MIME type or Content-Type for Peppol Message Envelope documents MUST be either

202

application/xml or text/xml (they can be used interchangeably

203

2.8 Message Envelope Schema

204

205

See https://tools.ietf.org/html/rfc7303#section-9.2

Peppol Business Message Envelope (SBDH) v2.0.1

Element/Attribute

Annotation

StandardBusinessDocument

Type StandardBusinessDocument

xs:sequence

Occurrence 1 .. 1

StandardBusinessDocumentHeader

Occurrence 1 .. 1

Type StandardBusinessDocumentHeader

xs:sequence

Occurrence 1 .. 1

HeaderVersion

Occurrence 1 .. 1

Type xs:string

Fixed 1.0

Description Always value 1.0

Sender

Occurrence 1 .. 1

Type Partner

xs:sequence

Occurrence 1 .. 1

Identifier

Occurrence 1 .. 1

Type PartnerIdentification

Description Use the format XXXX:AAAAAAAA where XXXX is

the type of identifer (such as 0088 for GS1 GLN)

and AAAAAAAA the actual identifier.

Authority

Type xs:string

Use required

Description Use fixed value "iso6523-actorid-upis"

Receiver

Occurrence 1 .. 1

Type Partner

xs:sequence

Occurrence 1 .. 1

Identifier

Occurrence 1 .. 1

Type PartnerIdentification

Description Use the format XXXX:AAAAAAAA where XXXX is

the type of identifer (such as 0088 for GS1 GLN)

and AAAAAAAA the actual identifier.

Authority

Type xs:string

Use required

Description Use fixed value "iso6523-actorid-upis"

DocumentIdentification

Occurrence 1 .. 1

Type DocumentIdentification

xs:sequence

Occurrence 1 .. 1

Standard

Occurrence 1 .. 1

Type xs:string

Description The standard of the enveloped business

message, normally described by use of the XML

namespace of the business message root

element (such as urn:oasis:names:specification:

ubl:schema:xsd:Order-2)

TypeVersion

Occurrence 1 .. 1

Type xs:string

Description The version number of the enveloped business

message (such as the value "2.1" for OASIS UBL

2.1 or "2.0" for OASIS UBL 2.0)

InstanceIdentifier

Occurrence 1 .. 1

Type xs:string

Description An informative unique ID created by the issuer of

the envelope. The InstanceIdentifier MUST be

unique for each Business Message Envelope

being created. This ID is not the same as the ID of

the business message (such as the Invoice

Number). It is not the same as a transmission

Message ID generated by the application sending

the message (as defined in AS4).

The InstanceIdentifier MUST be globally unique

and it is RECOMMENDED to use UUID (such as

118e3040-51d2-11e3-8f96-0800200c9a66)

Type

Occurrence 1 .. 1

Type xs:string

Description Message type - mandatory in SBDH. XML local

element name of the root-element in the business

message.

Peppol Business Message Envelope (SBDH) v2.0.1

Element/Attribute

Annotation

CreationDateAndTime

Occurrence 1 .. 1

Type xs:dateTime

Description The date and time for when this envelope was

created. It is NOT necessarily the same as the

issue date of the business document (such as the

invoice) being enveloped. It is NOT necessarily

the date time for transmission.

The format of the value of this MUST include

timezone information.

Use this format for UTC: 2014-01-17T09:30:00Z

(Where the "Z" indicates UTC)

Or specify offset from UTC by adding the time

difference: 2014-01-17T09:30:00+02:00 (Where

+02:00 indicates 2 hours positive offset to UTC)

BusinessScope

Occurrence 1 .. 1

Type BusinessScope

Description Elements used to identify the ProcessID and

DocumentID.

xs:sequence

Occurrence 1 .. 1

Scope

Occurrence 3 .. unbounded

Type Scope

Description Repeat for each mandatory qualifier. See chapters

2.4 and 2.5

xs:sequence

Occurrence 1 .. 1

ScopeAttributes

Occurrence 1 .. 1

xs:sequence

Occurrence 1 .. 1

Type

Occurrence 1 .. 1

Type xs:string

Description Qualifier of how to understand the

InstanceIdentifier element. Codes.

InstanceIdentifier

Occurrence 1 .. 1

Type xs:string

Description The values matching the

type qualified by the ScopeAttributes/

Type element.

Identifier

Occurrence 0 .. 1

Type xs:string

Description Identification scheme used for the Document type

identifier/Process identifier. See chapter 2.4

xs:any

Occurrence 1 .. 1

Description Business message goes here!

206

3 Appendix

207

Peppol Business Message Envelope (SBDH) v2.0.1

3.1 Example instance document (non-normative)

208

<?xml version="1.0" encoding="UTF-8"?>

209

<StandardBusinessDocument xmlns:xs="http://www.w3.org/2001/XMLSchema"

210

xmlns="http://www.unece.org/cefact/namespaces/StandardBusinessDocumentHeader">

211

212

213

214

215

</Sender>

216

217

218

</Receiver>

219

220

<Standard>urn:oasis:names:specification:ubl:schema:xsd:Invoice-2</Standard>

221

222

223

<Type>Invoice</Type>

224

225

</DocumentIdentification>

226

227

<Scope>

228

<Type>DOCUMENTID</Type>

229

<InstanceIdentifier>urn:oasis:names:specification:ubl:schema:xsd:Invoice-

230

2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1</I

231

nstanceIdentifier>

232

<Identifier>busdox-docid-qns</Identifier>

233

</Scope>

234

<Scope>

235

<Type>PROCESSID</Type>

236

<InstanceIdentifier>urn:fdc:peppol.eu:2017:poacc:billing:01:1.0</InstanceIdentifier>

237

<Identifier>cenbii-procid-ubl</Identifier>

238

</Scope>

239

<Scope>

240

<Type>COUNTRY_C1</Type>

241

242

</Scope>

243

</BusinessScope>

244

</StandardBusinessDocumentHeader>

245

<Invoice xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2"

246

xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"

247

xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">

248

249

</Invoice>

250

</StandardBusinessDocument>

251

3.2 Message Envelope Extension XML Schema

252

The normative version of the Message Envelope Extension XML Schema can be found at

253

https://docs.peppol.eu/edelivery/

254