Service Metadata Publishing (SMP) Version 1.0 s1
Service Metadata Publishing (SMP) Version 1.0
OASIS Standard
01 August 2017
Specification URIs
This version:
http://docs.oasis-open.org/bdxr/bdx-smp/v1.0/os/bdx-smp-v1.0-os.doc (Authoritative)
http://docs.oasis-open.org/bdxr/bdx-smp/v1.0/os/bdx-smp-v1.0-os.html
http://docs.oasis-open.org/bdxr/bdx-smp/v1.0/os/bdx-smp-v1.0-os.pdf
Previous version:
http://docs.oasis-open.org/bdxr/bdx-smp/v1.0/csprd02/bdx-smp-v1.0-csprd02.doc (Authoritative)
http://docs.oasis-open.org/bdxr/bdx-smp/v1.0/csprd02/bdx-smp-v1.0-csprd02.html
http://docs.oasis-open.org/bdxr/bdx-smp/v1.0/csprd02/bdx-smp-v1.0-csprd02.pdf
Latest version:
http://docs.oasis-open.org/bdxr/bdx-smp/v1.0/bdx-smp-v1.0.doc (Authoritative)
http://docs.oasis-open.org/bdxr/bdx-smp/v1.0/bdx-smp-v1.0.html
http://docs.oasis-open.org/bdxr/bdx-smp/v1.0/bdx-smp-v1.0.pdf
Technical Committee:
OASIS Business Document Exchange (BDXR) TC
Chair:
Kenneth Bengtsson (), Alfa1lab
Editors:
Jens Aabol (), Difi-Agency for Public Management and eGovernment
Kenneth Bengtsson (), Alfa1lab
Erlend Klakegg Bergheim (), Difi-Agency for Public Management and eGovernment
Sander Fieten () Individual
Sven Rasmussen (), Danish Agency for Digitisation, Ministry of Finance
Additional artifacts:
This prose specification is one component of a Work Product that also includes:
· XML schema: http://docs.oasis-open.org/bdxr/bdx-smp/v1.0/os/schemas/bdx-smp-201605.xsd
Related work:
This specification is related to:
· Business Document Metadata Service Location Version 1.0. Edited by Dale Moberg and Pim van der Eijk. Latest version: http://docs.oasis-open.org/bdxr/BDX-Location/v1.0/BDX-Location-v1.0.html.
Declared XML namespace:
· http://docs.oasis-open.org/bdxr/ns/SMP/2016/05
Abstract:
This document describes a protocol for publishing service metadata within a 4-corner network. In a 4-corner network, entities are exchanging business documents through intermediary gateway services (sometimes called Access Points). To successfully send a business document in a 4-corner network, an entity must be able to discover critical metadata about the recipient (endpoint) of the business document, such as types of documents the endpoint is capable of receiving and methods of transport supported. The recipient makes this metadata available to other entities in the network through a Service Metadata Publisher service. This specification describes the request/response exchanges between a Service Metadata Publisher and a client wishing to discover endpoint information. A client can either be an end-user business application or a gateway/access point in the 4-corner network. It also defines the request processing that must happen at the client.
Status:
This document was last revised or approved by the membership of OASIS 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/.
This OASIS Standard is provided under the Non-Assertion Mode of the OASIS IPR Policy, the mode chosen when the Technical Committee was established. 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 TC’s web page (https://www.oasis-open.org/committees/bdxr/ipr.php).
Note that any machine-readable content (Computer Language Definitions) declared Normative for this Work Product is provided in separate plain text files. In the event of a discrepancy between any such plain text file and display content in the Work Product's prose narrative document(s), the content in the separate plain text file prevails.
Citation format:
When referencing this specification the following citation format should be used:
[SMP-v1.0]
Service Metadata Publishing (SMP) Version 1.0. Edited by Jens Aabol, Kenneth Bengtsson, Erlend Klakegg Bergheim, Sander Fieten, and Sven Rasmussen. 01 August 2017. OASIS Standard. http://docs.oasis-open.org/bdxr/bdx-smp/v1.0/os/bdx-smp-v1.0-os.html. Latest version: http://docs.oasis-open.org/bdxr/bdx-smp/v1.0/bdx-smp-v1.0.html.
Notices
Copyright © OASIS Open 2017. 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 OR 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, to 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 for above guidance.
Table of Contents
1 Introduction 6
1.0 IPR Policy 6
1.1 Introduction 6
1.2 Goals and non-goals 6
1.3 Terminology 6
1.4 Normative References 6
1.5 Non-Normative References 7
2 SMP Protocol 8
2.1 The Service Discovery Process 8
2.1.1 Introduction 8
2.1.2 Discovering services associated with a Participant Identifier 8
2.1.3 Service Metadata Publisher Redirection 9
2.2 Interface model 9
2.3 Data model 10
2.3.1 Data model 10
2.3.2 On extension points 10
2.3.2.1 Use of extensions 10
2.3.2.2 Pseudo-schema for Extension 10
2.3.2.3 Description of the individual fields (elements and attributes) 11
2.3.3 ServiceGroup 11
2.3.3.1 ServiceGroup 11
2.3.3.2 Pseudo-schema for ServiceGroup 11
2.3.3.3 Description of the individual fields (elements and attributes) 12
2.3.3.4 Non-normative example of a ServiceGroup resource 12
2.3.4 ServiceMetadata 12
2.3.4.1 Redirection 12
2.3.4.2 Pseudo-schema for the “ServiceInformation” data type 13
2.3.4.3 Pseudo-schema for the “Redirect” data type 13
2.3.4.4 Description of the individual fields (elements and attributes) 14
2.3.5 SignedServiceMetadata 16
2.4 Identifiers 16
2.4.1 Introduction 16
2.4.2 Notational conventions 16
2.4.3 On the use of percent encoding in URLs 17
2.4.4 On Scheme Identifiers 17
2.4.5 Participant Identifiers 17
2.4.5.1 Participant Identifiers 17
2.4.5.2 XML format for Participant Identifiers 17
2.4.5.3 Using participant identifiers in URLs 18
2.4.6 Document Identifier 18
2.4.6.1 Introduction 18
2.4.6.2 XML Representation of Document Identifiers 19
2.4.6.3 URL representation of Document Identifiers 19
2.4.7 Process Identifiers 20
2.4.7.1 XML Representation of Process Identifiers 20
3 Service Metadata Publishing REST binding 22
3.1 Introduction 22
3.2 The use of HTTP 22
3.2.1 General use of HTTP 22
3.2.2 Caching of HTTP responses 22
3.3 The use of XML and encoding 23
3.4 Resources and identifiers 23
3.4.1 REST interface 23
3.4.2 Using identifiers in the REST Resource URLs 23
3.5 Referencing the SMP REST binding 23
3.6 Security 24
3.6.1 General 24
3.6.2 Message signature 24
3.6.2.1 Use of XML signatures 24
3.6.2.2 Verifying the signature 24
3.6.2.3 Verifying the signature of the destination SMP 24
3.7 Schema for the REST interface 24
4 Conformance 25
Appendix A. Acknowledgments (non-normative) 26
Appendix B. SMP Schema (non-normative) 27
Appendix C. Non-Normative Examples 31
C.1 ServiceGroup resource 31
C.2 SignedServiceMetadata resource 31
C.3 Redirect 33
C.4 Identifier 34
bdx-smp-v1.0-os 01 August 2017
Standards Track Work Product Copyright © OASIS Open 2017. All Rights Reserved. Page 2 of 34
1 Introduction
1.0 IPR Policy
This OASIS Standard is provided under the Non-Assertion Mode of the OASIS IPR Policy, the mode chosen when the Technical Committee was established.
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 TC’s web page (https://www.oasis-open.org/committees/bdxr/ipr.php).
1.1 Introduction
This document describes the protocol and its binding to a REST interface for Service Metadata Publication within a 4-corner network. It defines the messages exchanged between a Service Metadata Publisher and a client wishing to discover endpoint information. A client can either be an end-user business application or an Access Point in a 4-corner network.
It also specifies how these message exchanges should be implemented using a REST transport interface. The SMP protocol itself however is open for binding to other transport protocols like AS4. Such bindings can be specified in future specifications.
SMP is typically used to discover endpoint information and capabilities between entities exchanging business documents in a 4-cornered network. In some 4-cornered networks, such as is the case in the European eHealth domain, business information is being exchanged in different structured forms than as documents. The label “document” used in the data model of this specification may in such networks be interpreted as referring to any resource that is being exchanged in the network.
1.2 Goals and non-goals
The goal of this document is to define the protocol and its binding to a REST interface that Service Metadata Publishers (“SMP”) and clients must support. Decisions regarding physical data format and management interfaces are left to implementers of the SMP and client applications.
Service Metadata Publishers may be subject to additional constraints of agreements and governance frameworks within instances of the 4-corner infrastructure not covered in this specification, which only addresses the technical interface of such a service.
1.3 Terminology
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 [RFC2119].
1.4 Normative References
[RFC2119] “Key words for use in RFCs to Indicate Requirement Levels”, BCP 14, RFC 2119, March 1997. http://www.ietf.org/rfc/rfc2119.txt.
[XML 1.0] “Extensible Markup Language (XML) 1.0 (Fifth Edition)”, W3C Recommendations, 26 November 2008, http://www.w3.org/TR/xml/
[Unicode] “The Unicode Standard, Version 7.0.0”,(Mountain View, CA: The Unicode Consortium, 2014. ISBN 978-1-936213-09-2)
http://www.unicode.org/versions/Unicode7.0.0/
[HTTP 1.1] “Hypertext Transfer Protocol -- HTTP/1.1”, RFC 2616, June 1999, www.ietf.org/rfc/rfc2616.txt
[X509v3] ITU-T Recommendation X.509 version 3 (1997). "Information Technology - Open Systems Interconnection - The Directory Authentication Framework" ISO/IEC 9594-8:1997
[XML-DSIG1] XML Signature Syntax and Processing Version 1.1, D. Eastlake, J. Reagle, D. Solo, F. Hirsch, M. Nyström, T. Roessler, K. Yiu, Editors, W3C Recommendation, April 11, 2013, http://www.w3.org/TR/2013/REC-xmldsig-core1-20130411/. Latest version available at http://www.w3.org/TR/xmldsig-core1/.
[RFC7232] “Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests”, RFC 7232, June 2014, http://www.ietf.org/rfc/rfc7232.txt
1.5 Non-Normative References
[REST] “Architectural Styles and the Design of Network-based Software Architectures”, http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
[BDXL] “Business Document Metadata Service Location (BDXL) Version 1.0“, Committee Specification, 10 June 2014, http://docs.oasis-open.org/bdxr/BDX-Location/v1.0/cs01/BDX-Location-v1.0-cs01.html
[ebCorePartyId] “OASIS ebCore Party Id Type Technical Specification Version 1.0. OASIS Committee Specification”, September 2010, https://docs.oasis-open.org/ebcore/PartyIdType/v1.0/PartyIdType-1.0.odt
[RFC3986] Berners-Lee, T., Fielding, R., Masinter, L., “Uniform Resource Identifier (URI): Generic Syntax”, RFC 3968, January 2005, http://tools.ietf.org/rfc/rfc3986
2 SMP Protocol
2.1 The Service Discovery Process
2.1.1 Introduction
In a 4-cornered architecture the discovery process is a two-step process that starts with the lookup of the SMP that holds the service meta-data information about a participant identifier in the network. Each Participant Identifier is registered with one and only one Service Metadata Publisher. This lookup is performed by the client using the Business Document Metadata Service Location protocol [BDXL].
After retrieving the location of the SMP the client can then retrieve the metadata associated with the Participant Identifier. This metadata includes the information necessary to transmit the message to the recipient endpoint.