Exchange Header Envelope (XHE) Version 1.0

Committee Specification Public Review Draft 01

23 April 2018

Specification URIs
This version:
http://docs.oasis-open.org/bdxr/xhe/v1.0/csprd01/xhe-v1.0-csprd01.xml (Authoritative)
http://docs.oasis-open.org/bdxr/xhe/v1.0/csprd01/xhe-v1.0-csprd01-oasis.html
http://docs.oasis-open.org/bdxr/xhe/v1.0/csprd01/xhe-v1.0-csprd01-oasis.pdf
Previous version:
N/A
Latest version:
http://docs.oasis-open.org/bdxr/xhe/v1.0/xhe-v1.0-oasis.html
http://docs.oasis-open.org/bdxr/xhe/v1.0/xhe-v1.0-oasis.pdf
Technical Committee:
OASIS Business Document Exchange (BDXR) TC
Chairs:
Anders Grangard (anders.grangard@GS1.ORG), GS1
Kenneth Bengtsson (kenneth@alfa1lab.com), Alfa1lab
Editor:
G. Ken Holman (gkholman@CraneSoftwrights.com), Crane Softwrights Ltd.
Additional artefacts:

The ZIP containing the complete files of this release is found in the directory:

The following directories have normative artefacts:

Related work:

This specification supersedes:

[BDE 1.1] Business Document Envelope Version 1.1 Edited by G. Ken Holman and Kenneth Bengtsson. 05 December 2016. OASIS Committee Specification 01. Latest version: http://docs.oasis-open.org/bdxr/bdx-bde/v1.1/bdx-bde-v1.1.html.

Declared XML Namespaces:
oasis-cefact-xhe-1.0-ExchangeHeaderEnvelope
oasis-cefact-xhe-1.0-AggregateComponents
oasis-cefact-xhe-1.0-BasicComponents
oasis-cefact-xhe-1.0-ExtensionComponents
oasis-cefact-xhe-1.0-QualifiedDataTypes
oasis-cefact-xhe-1.0-UnqualifiedDataTypes
Abstract:

This specification defines a business-oriented artefact either referencing (as a header) or containing (as an envelope) a payload of one or more business documents or other artefacts with supplemental semantic information about the collection of payloads as a whole. This is distinct from any transport-layer infrastructure header or envelope that may be required to propagate documents from one system to another. An exchange header envelope describes contextual information important to the sender and receiver about the payloads, without having to modify the payloads in any fashion.

Status:

This document has been prepared and submitted both to the OASIS Business Document Exchange (BDXR) TC and to the UN/CEFACT Methodology and Technology PDA. It is the intent of both groups to share any further proposed changes to both panels and to approve identical final versions. Final approval by one or both organizations may also require their mutual commitment to approve and maintain one and the same final specification.

This document was last approved by the OASIS Business Document Exchange (BDXR) TC on the above date. The level of approval is also listed above. Check the “Latest version” location noted above for possible later revisions of this document. Any other numbered Versions and other technical work produced by the Technical Committee (TC) are listed at https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=bdxr#technical.

TC members should send comments on this specification to the TC’s email list. Others should send comments to the TC’s public comment list, after subscribing to it by following the instructions at the “Send A Comment” button on the TC’s web page at https://www.oasis-open.org/committees/bdxr/.

For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the Technical Committee web page at https://www.oasis-open.org/committees/bdxr/ipr.php.

Citation format:

When referencing this specification the following citation format should be used:

[XHE-V1.0] Exchange Header Envelope (XHE) Version 1.0. Edited by G. Ken Holman. 23 April 2018. OASIS Committee Specification Public Review Draft 01. http://docs.oasis-open.org/bdxr/xhe/v1.0/csprd01/xhe-v1.0-csprd01-oasis.html. Latest version: http://docs.oasis-open.org/bdxr/xhe/v1.0/xhe-v1.0-oasis.html.


Notices

Copyright © OASIS Open 2018. All Rights Reserved.

All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the “OASIS IPR Policy”). The full Policy may be found at the OASIS website.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.

This document and the information contained herein is provided on an “AS IS” basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS AND ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Committee Specification or OASIS Standard notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification.

OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so.

OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS’ procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Committee Specification or OASIS Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.

The name “OASIS” is a trademark of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see https://www.oasis-open.org/policies-guidelines/trademark.php for guidance.


Table of Contents

1 Introduction
1.1 Conveying information about payloads
1.1.1 Overview
1.1.2 What is an Exchange Header Envelope?
1.1.3 How is it used in EDI and XML environments?
1.1.4 The Scope of the Exchange Header Envelope
1.1.5 Dual Semantic Identifiers
1.1.6 Stakeholders and Audience
1.2 Terminology
1.2.1 Key words
1.2.2 Terms and Definitions
1.2.3 Symbols and Abbreviations
1.2.4 Key concepts
1.3 Normative References
1.4 Informative References
2 Header and envelope information
2.1 XHE class diagram
2.2 Header envelope information
2.3 Header information
2.4 Party information
2.5 Party identification information
2.6 Business scope information
2.7 Business scope criterion information
2.8 External reference information
2.9 Payload information
2.9.1 Payload set information
2.9.2 Payload item information
2.10 Extension information
3 XHE digital signatures
3.1 Signing the exchange header envelope
4 Document model expression
5 XML syntax expression
5.1 Schema expression
5.2 XML namespaces
5.3 The schema subdirectories
5.4 The header envelope schema
5.5 Non-content data type common schemas
5.6 Content data type common schemas
5.6.1 Modifiable schema fragments
5.6.2 Extension content
5.6.3 Payload content
5.7 Unqualified data type attributes
6 Conformance

Appendixes

A Package structure (Non-Normative)
B Revision History (Non-Normative)
B.1 Major version XHE 1.0
C Demonstration XML environment (Non-Normative)
D Encrypting payloads to multiple recipients (Non-Normative)
E Acknowledgements (Non-Normative)
F Temporary Annex - Change Log (Non-Normative)

1 Introduction

1.1 Conveying information about payloads

1.1.1 Overview

File or document headers have long been used to describe the information about a set of payloads in an entity that is kept separate and arm’s-length from the payloads themselves.

The metaphor of a paper envelope in which one places business documents for transport or management is apt to describe the role of an exchange header envelope in a container relationship to its payloads. Concepts of routing, authentication, non-repudiation and concealment all apply in both the metaphor and the electronic equivalent.

1.1.2 What is an Exchange Header Envelope?

The Exchange Header Envelope (XHE) specifies an XML vocabulary [XML] expressing in machine-processable syntax the semantics of describing either a header to or an envelope of a set of payloads of content with information about that content. This vocabulary is modeled using the UN/CEFACT Core Component Technical Specification Version 2.01 [CCTS 2.01].

XHE, a specification developed jointly by UN/CEFACT and OASIS, is the successor to the UN/CEFACT Standard Business Document Header (SBDH) version 1.3 [SBDH] and the OASIS Business Document Envelope (BDE) version 1.1 [BDE].

Note regarding publications

The UN/CEFACT Exchange Header Envelope and the OASIS Exchange Header Envelope are the same specification developed in collaboration and published as standards by the two organizations following the practices of each.

This specification enumerates the information components of a payload header envelope and formally describes the semantics of each component.

This specification mandates a suite of XML schemas [XSD1][XSD2] and additional limitations describing the document constraints against which a conforming instance SHALL validate without error.

Normative markings

All clauses not marked as “informative” and also not a subclause of a clause marked as “informative” are to be considered normative. All notes and examples are informative.

The XHE is designed to be either a header as an integral part of a business document (e.g. either XML instance document or EDI interchange), an object associated with the business document itself, or as an envelope functioning as wrapper that contains one or more business documents.

1.1.3 How is it used in EDI and XML environments?

There exist several business document exchange architectures and approaches, some using EDI formats and approaches, some using XML document types, and yet others use different document formats or non-standardized approaches. The XHE is designed to work with any document format and business process, whether standardized or not, and as such supports both the EDI, the XML and any other e-business community. Including a XHE in each instance of the business document reduces the effort needed to route and process documents and permits trading partner organizations to use different implementation approaches.

When implementing EDI, the provision of an additional business document header may not always be necessary, since EDI interchanges already contain functionality for some of the information in the XHE. An example is the EDIFACT UNB interchange header, the UNH message header, and the ‘function’ part of the BGM. The XHE specification allows for this existing approach and provides an option to express additional functionality, such as service and correlation information.

1.1.4 The Scope of the Exchange Header Envelope

Many users, implementers and supporting industry standard bodies are in agreement on the need for an Exchange Header Envelope. In their business-to-business activities, the XHE facilitates several different business needs:

  • The routing of business documents from one point to another. This refers not only to the transfer of information from an external originator to receiver, but also from one intermediate application to another. Information in the XHE can help ensure that a document gets to the correct recipient.

  • Ensuring integrity and confidentiality of business documents when routed over multiple hops, intermediaries, routers or access points, such as in 4-corner networks and architectures.

  • Simplifying the bundling of several business documents or support documents into one package for simplified exchange.

  • Facilitating the exchange of location pointers and access credentials to externally located business documents, not suitable for sending through an e-business network. This is necessary when the sending party needs to keep the business document confidential until a specified date (such as in tendering processes), and when sending very large files.

  • The simplified processing of documents. Processing refers to taking action on data, for example transforming it from one format into another. Information in the XHE can reduce the effort required to determine the correct processing actions.

  • Associating a data message with its originator is important from a business and legal perspective. It is especially important when using intermediaries for data transfer, as information from the transport protocol, may be lost after the initial transmission. Because information in the XHE is retained, it can help ensure that a document’s originator is correctly identified.

In addition to header functions provided by the XHE for routing and/or processing of business documents, there is the need for a completely separate technical communications transport layer. This deals with communications protocols and physical addresses which are outside the scope of this technical specification. Transport specifications including EDIINT-AS2 and ebXML Message Service (ebMS) are among a number of possible transport options that address technical communications needs by defining a separate technical header. The transport layer is completely outside the scope as it is a different layer of the stack.

1.1.5 Dual Semantic Identifiers

This specification accommodates both CEFACT and OASIS naming conventions of all semantic identifiers by documenting the two values for every business information entity. In each table row in Section 2, “Header and envelope information” the semantic identifiers are provided in two sub-rows, the upper one carrying the OASIS semantic identifier and the lower one carrying the CEFACT semantic identifier.

1.1.6 Stakeholders and Audience

All organizations that manage infrastructure operations and business processes for various functional areas (e.g. ordering, invoicing, planning, or financial), all service provider organizations and associations, as well as e-business networks and infrastructures, which create, route and process business documents can benefit from the use of the Exchange Header Envelope.

1.2 Terminology

1.2.1 Key words

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

1.2.2 Terms and Definitions

schema, noun

An expression of constraints placed on XML content.

value constraints, noun

An expression of constraints placed on the values of attributes and textual content.

1.2.3 Symbols and Abbreviations

ABIE, noun

Aggregate Business Information Entity

BBIE, noun

Basic Business Information Entity

ASBIE, noun

Association Business Information Entity

RFC, noun

Request for comment

XSD, noun

XML Schema Definition

XSLT, noun

Extensible Stylesheet Language Transformations

1.2.4 Key concepts

validation, verb

The act of testing an XML document against a set of structural constraints (as expressed in a schema) or value constrains (as expressed in an arbitrary XML processing language, for example, XSLT).

1.3 Normative References

[CCTS 2.01] UN/CEFACT Core Components Technical Specification, Version 2.0115 November 2003 http://www.unece.org/fileadmin/DAM/cefact/codesfortrade/CCTS/CCTS_V2-01_Final.pdf

[RFC 2119] Bradner, S., Key words for use in RFCs to Indicate Requirement Levels, BCP 14, RFC 2119, March 1997, <http://www.rfc-editor.org/info/rfc2119>.

[XML] Extensible Markup Language (XML) 1.0 (Fifth Edition), T. Bray, J. Paoli, C. M. Sperberg-McQueen, E. Maler, F. Yergeau, Editors, W3C Recommendation, 26 November 2008, http://www.w3.org/TR/2008/REC-xml-20081126/. Latest version available at http://www.w3.org/TR/xml.

[xmldsig] XML-Signature Syntax and Processing Version 1.1, D. E. Eastlake, J. Reagle, D. Solo, F. Hirsch, M. Nyström, T. Roessler, K. Yiu, Editors, W3C Recommendation, 11 April 2013, http://www.w3.org/TR/2013/REC-xmldsig-core1-20130411/. Latest version available at http://www.w3.org/TR/xmldsig-core1.

[XSD1] XML Schema Part 1: Structures Second Edition, H. S. Thompson, D. Beech, M. Maloney, N. Mendelsohn, Editors, W3C Recommendation, 28 October 2004, http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/. Latest version available at http://www.w3.org/TR/xmlschema-1.

[XSD2] XML Schema Part 2: Datatypes Second Edition, P. V. Biron, A. Malhotra, Editors, W3C Recommendation, 28 October 2004, http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/. Latest version available at http://www.w3.org/TR/xmlschema-2.

1.4 Informative References

[BDE] Business Document Envelope Version 1.1 Edited by G. Ken Holman and Kenneth Bengtsson. 05 December 2016. OASIS Committee Specification 01. Latest version: http://docs.oasis-open.org/bdxr/bdx-bde/v1.1/bdx-bde-v1.1.html.

[CMS] Cryptographic Message Syntax (CMS), R. Housley, September 2009, https://tools.ietf.org/html/rfc5652.

[genericode] Code List Representation (Genericode) Version 1.0. Edited by Anthony B. Coates. 28 December 2007. Committee Specification 01. http://docs.oasis-open.org/codelist/genericode/. Latest version: http://docs.oasis-open.org/codelist/genericode/doc/oasis-code-list-representation-genericode.html.

[PGP] OpenPGP Message Format, J. Callas, L. Donnerhacke, H. Finney, D. Shaw, R. Thayer, November 2007, https://tools.ietf.org/html/rfc4880.

[XAdES] XML Advanced Electronic Signatures. ETSI TS 101 903 V1.4.1, June 2009 http://uri.etsi.org/01903/v1.4.1/ts_101903v010401p.pdf

[XMLEnc] XML Encryption Syntax and Processing, Donald Eastlake, Joseph Reagle, 10 December 2002, http://www.w3.org/TR/2002/REC-xmlenc-core-20021210/.

2 Header and envelope information

2.1 XHE class diagram

The information derived for XHE has been distilled into a suite of CCTS Aggregate Business Information Entities (ABIEs), each comprised of a set of Basic Business Information Entities (BBIEs) and/or Association Business Information Entities (ASBIEs).

The relationships between these business information entities are depicted in this class diagram:

Figure 1. Exchange Header Envelope class diagram

Exchange Header Envelope class diagram

2.2 Header envelope information

Metadata information about the header envelope itself, independent of the information it contains, includes the following:

Semantic identifierCard.Definition
XHE. DetailsN/AThe Exchange Header Envelope
XHE_ Envelope. Details
XHE. XHE Version Identifier. Identifier1The version of the specific envelope model in use.
XHE_ Envelope. Version. Identifier
XHE. Customization Identifier. Identifier0..1The identification of a customization or use of the envelope model.
XHE_ Envelope. Customization. Identifier
XHE. Profile Identifier. Identifier0..1The identification of a specific profile found within the customization.
XHE_ Envelope. Profile. Identifier
XHE. Profile Execution Identifier. Identifier0..1The identification of a particular instance of using the given profile.
XHE_ Envelope. Profile Execution. Identifier
XHE. Header1Information relevant to the handling of the envelope.
XHE_ Envelope. Metadata. XHE_ Document
XHE. Payloads0..1The set of payloads
XHE_ Envelope. Included. XHE_ Payload

Note

The set of payloads can be omitted to allow the XHE either to be embedded in a document that contains the actual payloads (as in the Standard Business Document) or in a standalone document entirely separate from the payloads (as in the standalone Standard Business Document Header). When present, the set of payloads is wrapped by the XHE document itself (as in the Business Document Envelope).

The information for a header envelope begins with an additional optional extensions item that is neither a BBIE nor an ASBIE and so is not modeled using CCTS. Rather, this extensions item is a schema artefact. This extensions item has the cardinality 0..1. See Section 5.6.2, “Extension content” for more information.

The information for a header envelope ends with an additional optional and repeatable number of digital signatures that are neither a BBIE nor an ASBIE and so are not modeled using CCTS. Rather, these signatures are a schema artefact published by the W3C. See Section 3.1, “Signing the exchange header envelope” for more information.

2.3 Header information

Metadata information about the header envelope itself, independent of the information it contains or references, includes the following:

Semantic identifierCard.Definition
Header. Identifier1Unique ID of the envelope for tracking purposes.
XHE_ Document. Identification. Identifier
Header. UUID0..1An additional identifier of the envelope.
XHE_ Document. UUID. Identifier
Header. Creation Date Time. Date Time1Date and time when the envelope was created.
XHE_ Document. Creation. Date Time
Header. Business Scope 0..1Documentation of the scope of business or other contextual details useful to understand the purpose of the envelope and its contents. For examples: Europe vs Asia, Direct-to-Consumer vs Replenishment, or Prepaid vs Credit.
XHE_ Document. Scope. XHE_ Context
Header. From_ Party. Party 0..1Information about the party that originated the envelope.
XHE_ Document. Sender. XHE_ Party
Header. To_ Party. Party1..nInformation about the parties to receive the envelope.
XHE_ Document. Recipient. XHE_ Party

2.4 Party information

The information about a party includes the following:

Semantic identifierCard.Definition
Party. Party Identification1..nUnambiguous identifications of a party.
XHE_ Party. Specified. XHE_ Identity

2.5 Party identification information

The information about a party’s identification includes the following:

Semantic identifierCard.Definition
Party Identification. Identifier1An unambiguous identification of a party.
XHE_ Party. Specified. XHE_ Identity

2.6 Business scope information

Documentation of the scope of business or other contextual details useful to understand the purpose of the envelope and its contents includes the following:

Semantic identifierCard.Definition
Business Scope. Business Scope Criterion0..nInternal specification of the scope and/or context of business.
XHE_ Context. Specified. XHE_ Parameter
Business Scope. External Reference0..nExternal documentation of the scope and/or context of business.
XHE_ Context. Scope. XHE_ Reference

2.7 Business scope criterion information

Documentation of one criterion of the scope of business or other contextual detail useful to understand the purpose of the envelope and its contents includes the following:

Semantic identifierCard.Definition
Business Scope Criterion. Business Scope Criterion Type. Code1Identifies the property of the scope by a code.
XHE_ Parameter. Type. Code
Business Scope Criterion. Business Scope Criterion Value. Text1Specifies the value of the given property.
XHE_ Parameter. Value. Text

2.8 External reference information

A reference to a business case, document or other issues which are relevant to the handling of the envelope includes the following:

Semantic identifierCard.Definition
External Reference. Identifier1Identifies the referenced object by some identifier or URI.
XHE_ Reference. Identification. Identifier
External Reference. Availability Start Date Time. Date Time0..1The start date and time when the information is available
XHE_ Reference. Start_ Availability. Date Time
External Reference. Availability End Date Time. Date Time0..1The end date and time when the information is available
XHE_ Reference. End_ Availability. Date Time
External Reference. Login. Text0..1Text describing any login details to access the information.
XHE_ Reference. Login. Text
External Reference. Password. Text0..1A password needed to access the information.
XHE_ Reference. Password. Text

2.9 Payload information

2.9.1 Payload set information

Information about the complete set of payloads includes the following:

Semantic identifierCard.Definition
Payloads. Payload1..nThe actual payload instance, such as a single invoice, conveyed within the envelope.
XHE_ Payload. Included. XHE_ Payload Instance

2.9.2 Payload item information

Information about an individual payload within the set of payloads includes the following:

Semantic identifierCard.Definition
Payload. Identifier0..1A unique identification of this payload instance contained within the envelope.
XHE_ Payload Instance. Identification. Identifier
Payload. Description. Text0..nText description of the payload instance.
XHE_ Payload Instance. Description. Text
Payload. Document Type Code. Code0..1Identifies the abstract archetype of the payload instance.
XHE_ Payload Instance. Document_ Type. Code
Payload. Content Type Code. Code0..1Identifies the file format or octet representation of the payload instance.
XHE_ Payload Instance. Content_ Type. Code
Payload. Customization Identifier. Identifier0..1Identifies the customization that applies to the payload instance.
XHE_ Payload Instance. Customization. Identifier
Payload. Profile Identifier. Identifier0..1Identifies the profile that the payload instance is part of.
XHE_ Payload Instance. Profile. Identifier
Payload. Profile Execution Identifier. Identifier0..1Identifies the particular instance of an executing profile that the payload instance is part of.
XHE_ Payload Instance. Profile Execution. Identifier
Payload. Handling Service Identifier. Identifier0..1Identifies the service that should process the payload instance.
XHE_ Payload Instance. Handling Service. Identifier
Payload. Validation Type. Code0..1The validation type of the payload, used for the task of verifying that the grammar of a payload is valid.
XHE_ Payload Instance. Validation_ Type. Code
Payload. Validation Version Identifier. Identifier0..1Descriptor containing version information of the validation type.
XHE_ Payload Instance. Validation Version. Identifier
Payload. Instance Encryption Indicator. Indicator1Indicator to state whether the payload instance is encrypted or not.
XHE_ Payload Instance. Encrypted. Indicator
Payload. Instance Encryption Method. Text0..1Method used to encrypt the payload instance.
XHE_ Payload Instance. Encryption Method. Text
Payload. Instance Hash Value. Text0..1SHA-256 hash total of the unencrypted payload instance.
XHE_ Payload Instance. Encryption Hash Value. Text
Payload. Instance Decryption Information_ External Reference. External Reference0..1Decryption information that is available external to the envelope.
XHE_ Payload Instance. Decryption. XHE_ Reference
Payload. Instance Decryption Key_ External Reference. External Reference0..1Decryption key data that is available external to the envelope.
XHE_ Payload Instance. Decryption Key. XHE_ Reference
Payload. Relevant_ External Reference. External Reference0..nA reference to a business case, document or other issues which are relevant to the handling of the payload.
XHE_ Payload Instance. Relevant. XHE_ Reference
Payload. Payload_ External Reference. External Reference0..1The reference to the payload when it is not included within the envelope.
XHE_ Payload Instance. Payload. XHE_ Reference

The information for an individual payload ends with an additional optional payload content item that is neither a BBIE nor an ASBIE and so is not modeled using CCTS. Rather, this content item is a schema artefact. This content item has the cardinality 0..1. This content item can have as its child either text only (no elements) or a single element, but not a combination of both nor more than one element. See Section 5.6.3, “Payload content” for more information.

2.10 Extension information

Through the use of extension metadata and content, additional user-defined information that is not modelled by the CCTS classes can be added to the envelope instance.

The extension point is an optional construct as the initial child of the document element. The extension point, when it exists, SHALL contain one or more user-defined extensions,. Each extension contains optional extension metadata identifying properties of the extension as well as the extension content.

Name

(Unqualified Data Type)

Description

Crd

Rationale

XHEExtensions

A container for all extensions present in the document.0..1This is the single point of access to all extensions as the first child of the main document.

XHEExtension

A single extension for private use.1..nThere may be many extensions added to a single document.

ExtensionID

(Identifier)
An identifier for the Extension assigned by the creator of the extension.0..1This identifies the extension amongst other extensions within the document.

ExtensionName

(Name)
A name for the Extension assigned by the creator of the extension.0..1This identifies the extension in natural language within the document.

ExtensionAgencyID

(Identifier)
An agency that maintains one or more Extensions.0..1This identifies who created the extension.

ExtensionAgencyName

(Name)
The name of the agency that maintains the Extension.0..1This identifies who created the extension.

ExtensionAgencyURI

(Identifier)
A URI for the Agency that maintains the Extension.0..1This identifies who created the extension.

ExtensionVersionID

(Identifier)
The version of the Extension.0..1This distinguishes one version of the extension from another.

ExtensionURI

(Identifier)
A URI for the Extension.0..1This identifies the extension amongst other extensions outside of any document.

ExtensionReasonCode

(Code)
A code for the reason the Extension is being included.0..1This gives the author the opportunity to give rationale by way of a code.

ExtensionReason

(Text)
A description of the reason for the Extension.0..1This gives the author the opportunity to give rationale by way of a text description.

ExtensionContent

The definition of the extension content.1This is the parent element of the extension content.

There are no restrictions on the extension content. See Section 5.6.2, “Extension content” for more information.

3 XHE digital signatures

3.1 Signing the exchange header envelope

Using the IETF/W3C XML Digital Signature specification [xmldsig] one can add multiple “non-final” signatures or a single “final” signature to the exchange header envelope as the last children of the document element, that is, after the last BIE of the document element. A non-final signature digitally signs all content other than any of the other sibling signature elements that may exist in the document. A final signature digitally signs all content including the other sibling signature elements that may exist in the document.

The schema fragment for Section 5.6.2, “Extension content” included in this distribution provides for using digital signature extensions supporting XML Advanced Electronic Signatures [XAdES] (ETSI TS 101 903), when the electronic signing of an exchange header envelope is necessary to satisfy legal and technical requirements. The schema fragment can be modified to accommodate such future extension requirements without impacting on the conformance clauses of this specification.

4 Document model expression

The document model is expressed in four ways, found in four files of the model subdirectory:

5 XML syntax expression

5.1 Schema expression

The structural document constraints of the header envelope are expressed normatively as a set of W3C XSD XML Schemas [XSD1][XSD2].

5.2 XML namespaces

The following XML namespace URI strings are specified in the XSD schemas to be used in the XML syntax expressions:

oasis-cefact-xhe-1.0-ExchangeHeaderEnvelope
oasis-cefact-xhe-1.0-AggregateComponents
oasis-cefact-xhe-1.0-BasicComponents
oasis-cefact-xhe-1.0-ExtensionComponents
oasis-cefact-xhe-1.0-QualifiedDataTypes
oasis-cefact-xhe-1.0-UnqualifiedDataTypes

5.3 The schema subdirectories

The schemas are delivered in two subdirectories:

  • xsd

    • CCTS documentation is included as XSD annotations

  • xsdrt

    • runtime version such that CCTS documentation is not included as XSD annotations

    • without the annotations a W3C schema processor has less work to prepare for validating documents

In both subdirectories there is a single subdirectory of common files:

  • common

    • included schema fragments by any document fragment

5.4 The header envelope schema

The following is the only Document ABIE schema:

  • xsd/XHE-1.0.xsd

    • the base header envelope schema fragment that incorporates other schema fragments

The following is the runtime version of the schema that has documentary annotations removed:

  • xsdrt/XHE-1.0.xsd

    • the base header envelope schema fragment that incorporates other schema fragments

5.5 Non-content data type common schemas

The following are read-only schema fragments in the common subdirectory:

5.6 Content data type common schemas

5.6.1 Modifiable schema fragments

There are two content data type schema fragments in the common subdirectory, one for each of the extension content and the payload content. These are the only schemas intended to be edited by users should they wish to validate the content of their extensions or payloads. No changes are necessary to the schemas if it is not important to validate these portions of the document.

Should users wish to impose constraints on the extension or the payload contents, the only edits necessary of the content schema are for the importation of the schemas to be engaged for validation purposes. No edits are necessary for the content element, though one may wish to do so to exclude content other than that for which schemas are provided.

5.6.2 Extension content

The extension content schema fragment describes constraints on content placed in extensions.

The extension content element’s name is <{extensions prefix}:ExtensionContent>, for example, <ext:ExtensionContent>. It is the last child element of <{extensions prefix}:XHEExtension>.

Any given extension content may have zero or one apex (or top-most) element in the XML element tree. The absence of content is provided for situations where a processing application chooses to remove foreign unrecognized-namespace elements from the XML element tree.

The distributed version of this file imports the version of XAdES schemas that are current at the time of publication. XAdES constructs are used within W3C XML Digital Signatures. These import directives can be replaced with the importation of future versions of XAdES schemas as needed.

5.6.3 Payload content

The payload content schema fragment describes constraints on content placed in payloads.

The payload content element’s name is <{aggregate prefix}:PayloadContent>, for example, <eac:PayloadContent>. It is the last child element of <{aggregate prefix}:Payload>.

Any given payload content element may have as its child exactly one apex (or top-most) element in the XML element tree, or it may consist solely of text that would typically represent encrypted content or non-XML content. Special care needs to be taken that all non-XML payload content is encoded according to XML text encoding rules, such as the escaping of special markup characters, so as to permit an XML processing application to correctly interpret the non-XML content.

The schema declarations are unable to trigger a constraint error in the situation where the payload content has a combination of both text and a single element. Detecting such a condition is the responsibility of the processing agent.

The schema declarations are unable to trigger a constraint error in the situation where the payload content is empty. Detecting such a condition is the responsibility of the processing agent.

5.7 Unqualified data type attributes

In the Exchange Header Envelope model each BBIE is indicated to have a particular component name (specifying the element name) and to be of a particular unqualified data type (specifying the base type value constraints and the attributes). Writers of extensions using CCTS and their own BBIEs need to know the available unqualified data types for their extended business objects.

Based on the 10 approved core component types described in section 8.1 of [CCTS 2.01], there are 20 available unqualified data types for BBIE values. Each data type has a constraint on its content (the component) and a possibly-empty selection of available possibly-mandatory attributes (the supplementary components).

Note

Not all of the unqualified data types listed in this table are used in the standardized components of the header envelope. All defined types are enumerated here for completeness in the event that a CCTS-based extension is created by a community of users that relies on one of the unqualified data types not used by the standardized components of the header envelope.

Data TypeBase type (XSD)Supplementary component (attribute)CardinalityType (XSD)Definition
Amountxsd:decimalA number of monetary units specified using a given unit of currency.
currencyIDrequiredxsd:normalizedStringThe currency of the amount.
currencyCodeListVersionIDoptionalxsd:normalizedStringThe VersionID of the UN/ECE Rec9 code list.

Binary Object

Graphic

Picture

Sound

Video

xsd:base64BinaryA set of finite-length sequences of binary octets.
mimeCoderequiredxsd:normalizedStringThe mime type of the binary object.
characterSetCodeoptionalxsd:normalizedStringThe character set of the binary object if the mime type is text.
encodingCodeoptionalxsd:normalizedStringSpecifies the decoding algorithm of the binary object.
filenameoptionalxsd:stringThe filename of the binary object.
formatoptionalxsd:stringThe format of the binary content.
urioptionalxsd:anyURIThe Uniform Resource Identifier that identifies where the binary object is located.
Codexsd:normalizedStringA character string (letters, figures, or symbols) that for brevity and/or language independence may be used to represent or replace a definitive value or text of an attribute, together with relevant supplementary information.
languageIDoptionalxsd:languageThe identifier of the language used in the code name.
listAgencyIDoptionalxsd:normalizedStringAn agency that maintains one or more lists of codes.
listAgencyNameoptionalxsd:stringThe name of the agency that maintains the list of codes.
listIDoptionalxsd:normalizedStringThe identification of a list of codes.
listNameoptionalxsd:stringThe name of a list of codes.
listSchemeURIoptionalxsd:anyURIThe Uniform Resource Identifier that identifies where the code list scheme is located.
listURIoptionalxsd:anyURIThe Uniform Resource Identifier that identifies where the code list is located.
listVersionIDoptionalxsd:normalizedStringThe version of the list of codes.
nameoptionalxsd:stringThe textual equivalent of the code content component.
DateTimexsd:dateTimeAn instance of time according the Gregorian calendar.
Datexsd:dateOne calendar day according the Gregorian calendar.
Timexsd:timeAn instance of time that occurs every day.
Identifierxsd:normalizedStringA character string to identify and uniquely distinguish one instance of an object in an identification scheme from all other objects in the same scheme, together with relevant supplementary information.
schemeAgencyIDoptionalxsd:normalizedStringThe identification of the agency that maintains the identification scheme.
schemeAgencyNameoptionalxsd:stringThe name of the agency that maintains the identification scheme.
schemeDataURIoptionalxsd:anyURIThe Uniform Resource Identifier that identifies where the identification scheme data is located.
schemeIDoptionalxsd:normalizedStringThe identification of the identification scheme.
schemeNameoptionalxsd:stringThe name of the identification scheme.
schemeURIoptionalxsd:anyURIThe Uniform Resource Identifier that identifies where the identification scheme is located.
schemeVersionIDoptionalxsd:normalizedStringThe version of the identification scheme.
Indicatorxsd:booleanA list of two mutually exclusive Boolean values that express the only possible states of a property.
Measurexsd:decimalA numeric value determined by measuring an object using a specified unit of measure.
unitCoderequiredxsd:normalizedStringThe type of unit of measure.
unitCodeListVersionIDoptionalxsd:normalizedStringThe version of the measure unit code list.

Numeric

Value

Percent

Rate

xsd:decimalNumeric information that is assigned or is determined by calculation, counting, or sequencing. It does not require a unit of quantity or unit of measure.
formatoptionalxsd:stringWhether the number is an integer, decimal, real number or percentage.
Quantityxsd:decimalA counted number of non-monetary units, possibly including a fractional part.
unitCodeoptionalxsd:normalizedStringThe unit of the quantity
unitCodeListAgencyIDoptionalxsd:normalizedStringThe identification of the agency that maintains the quantity unit code list
unitCodeListAgencyNameoptionalxsd:stringThe name of the agency which maintains the quantity unit code list.
unitCodeListIDoptionalxsd:normalizedStringThe quantity unit code list.

Text

Name

xsd:stringA character string (i.e. a finite set of characters), generally in the form of words of a language.
languageIDoptionalxsd:languageThe identifier of the language used in the content component.
languageLocaleIDoptionalxsd:normalizedStringThe identification of the locale of the language.

6 Conformance

A Exchange Header Envelope instance exhibits conformance when complying with all of the following criteria:

  1. The instance SHALL NOT violate any document constraints expressed by the schema in Section 5.4, “The header envelope schema”

  2. Any XML element that is not extension content SHALL NOT be empty.

  3. The <{aggregate prefix}:Payload element SHALL have one or the other of the <{aggregate prefix}:PayloadContent> element child or the <{aggregate prefix}:PayloadExternalReference> element child (that is, it SHALL NOT have both).

  4. The <{aggregate prefix}:PayloadContent> element SHALL NOT have a combination of text and an element (that is, it SHALL either be a non-empty string of text or be a single element).

Appendix A Package structure (Non-Normative)

This Committee Specification Public Review Draft 01 is published as a zip archive in the http://docs.oasis-open.org/bdxr/xhe/v1.0/csprd01/ directory. Unzipping this archive creates a directory tree containing a number of files and subdirectories. Note that while the two XML files comprise the revisable version of this specification, this revisable XML may not be directly viewable in all currently available web browsers.

The base directory has the following files:

  • xhe-v1.0-csprd01.xml

    • The revisable form of the document.

  • xhe-v1.0-csprd01.html

    • An HTML rendering of the document.

  • xhe-v1.0-csprd01.pdf

    • A PDF rendering of the document.

These are the informative subdirectories in the package:

  • art

    • Diagrams and illustrations used in this specification.

  • db

    • DocBook stylesheets for viewing in HTML the XML of this work product.

  • val

The normative subdirectories in the package are listed in normative clauses.

Appendix B Revision History (Non-Normative)

B.1 Major version XHE 1.0

XHE version 1.0 Committee Specification 01 establishes the namespaces to be used for all subsequent minor revisions of the Exchange Header Envelope.

Appendix C Demonstration XML environment (Non-Normative)

A working example of using the schemas with an XML instance is demonstrated in the val/ directory.

The following support files are in this directory:

  • test.bat

    • Windows invocation of the testing of the sample files

  • test.sh

    • shell invocation of the testing of the sample files

  • validate.bat

    • Windows invocation of the two-pass validation of a single file

  • validate.sh

    • shell invocation of the two-pass validation of a single file

  • w3cschema.bat

    • Windows invocation of the schema validation of a single file

  • w3cschema.sh

    • shell invocation of the schema validation of a single file

  • xslt.bat

    • Windows invocation of XSLT transformation on a single file

  • xslt.sh

    • shell invocation of XSLT transformation on a single file

This directory has a number of simple test files:

  • simpleExample.xml

    • a simple envelope with three payload instances, the second of which is simple text (note the escaped special characters) and the other two of which are XML

    <?xml version="1.0" encoding="UTF-8"?>
    <XHE xmlns="oasis-cefact-xhe-1.0-ExchangeHeaderEnvelope"
         xmlns:xhb="oasis-cefact-xhe-1.0-BasicComponents"
         xmlns:xha="oasis-cefact-xhe-1.0-AggregateComponents"
         xmlns:ext="oasis-cefact-xhe-1.0-ExtensionComponents">
      <xhb:XHEVersionID>1.0</xhb:XHEVersionID>
      <xha:Header>
        <xhb:ID>123</xhb:ID>
        <xhb:CreationDateTime>2015-02-08T20:34:00-04:00</xhb:CreationDateTime>
        <xha:BusinessScope>
          <xha:BusinessScopeCriterion>
            <xhb:BusinessScopeCriterionTypeCode
                                        >test</xhb:BusinessScopeCriterionTypeCode>
            <xhb:BusinessScopeCriterionValue>123</xhb:BusinessScopeCriterionValue>
          </xha:BusinessScopeCriterion>
          <xha:ExternalReference>
            <xhb:ID>http://www.company.com</xhb:ID>
          </xha:ExternalReference>
        </xha:BusinessScope>
        <xha:FromParty>
          <xha:PartyIdentification>
            <xhb:ID>A</xhb:ID>
          </xha:PartyIdentification>
        </xha:FromParty>
        <xha:ToParty>
          <xha:PartyIdentification>
            <xhb:ID>B</xhb:ID>
          </xha:PartyIdentification>
        </xha:ToParty>
      </xha:Header>
      <xha:Payloads>
        <xha:Payload>
          <xhb:InstanceEncryptionIndicator>false</xhb:InstanceEncryptionIndicator>
          <xha:PayloadContent>
            <myDocumentHere>
              <myElement>My Content</myElement>
              <myElement>My Content</myElement>
              <myElement>My Content</myElement>
            </myDocumentHere>
          </xha:PayloadContent>
        </xha:Payload>
        <xha:Payload>
          <xhb:ContentTypeCode>text/plain</xhb:ContentTypeCode>
          <xhb:InstanceEncryptionIndicator>false</xhb:InstanceEncryptionIndicator>
          <xha:PayloadContent>
    Non-XML payload here, with sensitive characters 
    escaped such as &amp;, &lt; and ]]&gt;.
    
    Any text, provided it has been escaped, can be included in a payload.
          </xha:PayloadContent>
        </xha:Payload>
        <xha:Payload>
          <xhb:InstanceEncryptionIndicator>false</xhb:InstanceEncryptionIndicator>
          <xha:PayloadContent>
            <myOtherDocumentHere>
              <myOtherElement>My Content</myOtherElement>
              <myOtherElement>My Content</myOtherElement>
              <myOtherElement>My Content</myOtherElement>
            </myOtherDocumentHere>
          </xha:PayloadContent>
        </xha:Payload>
      </xha:Payloads>
    </XHE>

  • simpleExampleFailSyntax.xml

    • an envelope document with an XML well-formedness error (the end tag for the creation date and time is missing the closing right-angle bracket)

  • simpleExampleFailModel.xml

    • an envelope document with an XML validity error (a misspelled element for the creation date and time)

  • simpleExampleExtension.xml

    • a simple envelope with a user-defined extension adding information to the envelope

  • simpleExampleTyped.xml

    • a simple envelope with a user-defined extension adding information to the envelope

To invoke the schemas with the demonstration instances, navigate to the directory and invoke the test script:

  • in Windows:

    test.bat

  • in shell:

    sh test.sh

The result on the screen should appear as follows:

val $ sh test.sh 

############################################################
Validating simpleExample.xml
############################################################
============== Phase 1: XSD schema validation ==============
No schema validation errors.
============ Phase 2: XSLT code list validation ============
No code list validation errors.

############################################################
Validating simpleExampleTyped.xml
############################################################
============== Phase 1: XSD schema validation ==============
No schema validation errors.
============ Phase 2: XSLT code list validation ============
No code list validation errors.

############################################################
Validating simpleExampleFailSyntax.xml
############################################################
============== Phase 1: XSD schema validation ==============
org.xml.sax.SAXParseException; systemId: file:///Users/admin/t/
artefacts-xhe-v1.0-csd01wd04-test/val/simpleExampleFailSyntax.xml; 
lineNumber: 10; columnNumber: 5; The end-tag for element type 
"xhb:CreationDateTime" must end with a '>' delimiter.
	at org.apache.xerces.parsers.AbstractSAXParser.parse(Unknown Source)
	at org.apache.xerces.jaxp.SAXParserImpl$JAXPSAXParser.parse(Unknown Source)
	at org.apache.xerces.jaxp.SAXParserImpl.parse(Unknown Source)
	at javax.xml.parsers.SAXParser.parse(SAXParser.java:274)
	at com.nwalsh.parsers.XJParser.xsdParse(Unknown Source)
	at com.nwalsh.parsers.XJParser.parse(Unknown Source)
	at com.nwalsh.parsers.XJParse.run(Unknown Source)
	at com.nwalsh.parsers.XJParse.main(Unknown Source)
Exception in thread "main" java.lang.NullPointerException
	at com.nwalsh.parsers.XJParser.printParseStats(Unknown Source)
	at com.nwalsh.parsers.XJParse.run(Unknown Source)
	at com.nwalsh.parsers.XJParse.main(Unknown Source)
Attempting well-formed, namespace-aware parse
Fatal error:file:///Users/admin/t/artefacts-xhe-v1.0-csd01wd04-test/
val/simpleExampleFailSyntax.xml:10:5:The end-tag for element type 
"xhb:CreationDateTime" must end with a '>' delimiter.

############################################################
Validating simpleExampleFailModel.xml
############################################################
============== Phase 1: XSD schema validation ==============
Attempting well-formed, namespace-aware parse
Error:file:///Users/admin/t/artefacts-xhe-v1.0-csd01wd04-test/val/
simpleExampleFailModel.xml:9:29:cvc-complex-type.2.4.a: Invalid content 
was found starting with element 'xhb:CreationDateTimeXX'. One of 
'{"oasis-cefact-xhe-1.0-BasicComponents":CreationDateTime}' is expected.
Parse succeeded (0.7) with 1 error and no warnings.

############################################################
Validating simpleExampleExtension.xml
############################################################
============== Phase 1: XSD schema validation ==============
No schema validation errors.
============ Phase 2: XSLT code list validation ============
No code list validation errors.

val $ 

The test script invokes the validation script using the following::

  • in Windows:

    validate.bat schema-file instance-file

  • in shell:

    sh validate.sh schema-file instance-file

The validation script invokes the schema script using the following:

  • in Windows:

    w3cschema.bat schema-file instance-file

  • in shell:

    sh w3cschema.sh schema-file instance-file

The validation script invokes the XSLT script using the following:

  • in Windows:

    xslt.bat instance-file stylesheet-file output-file

  • in shell:

    sh xslt.sh instance-file stylesheet-file output-file

The empty stylesheet XHE-DefaultDTQ-1.0.xsl is a placebo that would be replaced with an XSLT stylesheet imposing value validation constraint checking on a given instance of an exchange header envelope. An example of such data type qualification checking would be for code list enumerations.

Components of two freely available software distributions were used to create the tools in the val directory. Sources are given below so that these components can be updated as later releases become available.

Appendix D Encrypting payloads to multiple recipients (Non-Normative)

The XHE supports sending business documents to multiple recipients using a single envelope, which is obtained by adding multiple instances of the ToParty element to the XHE envelope.

When encrypting payloads of envelopes with multiple recipients, users SHOULD make use of encryption technologies that support multiple recipients so that an encrypted payload to multiple recipients can be contained in a single instance of an XHE envelope’s PayloadContent. Examples of encryption technologies supporting multiple recipients are [CMS], [PGP] and [XMLEnc].

The workings of individual encryption technologies and methodologies are beyond the scope of this specification.

Appendix E Acknowledgements (Non-Normative)

The following individuals have participated in the creation of this specification and are gratefully acknowledged:

Kenneth Bengtsson (co-chair)
Michel Bormans
Gait Boxman
Anders Grangard (co-chair)
G. Ken Holman (editor)

Appendix F Temporary Annex - Change Log (Non-Normative)

Note

This temporary appendix will be removed in the final version of the committee specification.

RevisionDateEditorChanges made
csprd0123 April 2018GKHSchemas updated to include both semantic identifiers
csprd0106 April 2018GKHInclude both semantic identifiers for every BIE
csprd0102 March 2018GKHOASIS cover page repairs
csprd0126 February 2018GKHOASIS cover page changes, namespace changes to prevent violating guidelines
csprd0122 February 2018GKHPrepared second edition of public review revision dated February 28, 2018 based on feedback in editing group
csprd0120 February 2018GKHPrepared first public review revision dated February 22, 2018
csd01wd0708 February 2018GKHComments from February 8 teleconference; putative first public review content; added UUID; documented namespace URI strings in the body of the document
csd01wd0606 February 2018GKHComments from February 1 teleconference; repaired bibliographic references; added class diagram, added introductory text
csd01wd0515 December 2017GKHComments from December 14 teleconference
csd01wd0419 November 2017GKHFirst draft of possibly the complete content
csd01wd0309 November 2017GKHUpdates after teleconference of 2017-11-07
csd01wd0206 November 2017GKHUpdates after teleconference of 2017-11-02
xhe-v1.0-csprd01
Standards Track Work Product

Copyright © OASIS Open 2018. All rights reserved.
23 April 2018