Digital

Page tree

European Commission Digital

Services

eDelivery BDXL 1.6



Status

eDelivery Specification

Publication date

 

Obsoletes

PR - BDXL - 1.5

Obsoleted by

eDelivery BDXL 1.7



Table of Contents



1. Description

eDelivery uses this eDelivery profile of the OASIS Business Document Metadata Service Location Version 1.0 specification [BDX-Location-v1.0], usually referred to as the "BDX Location" or BDXL specification, as its technical specification for Service Location. BDX Location specifies a method to query DNS resource records to retrieve a URL for metadata services. The result of a query is a full URI, which can use HTTPS and supports server (and optionally client) authentication.

The eDelivery BDX Location profile is intended to be used in conjunction with the eDelivery SMP profile [eDelivery-SMP]. The retrieved URL is a URL for an SMP XML document that can be obtained using the SMP HTTP binding. This process is visualized in the following diagram:

Together, eDelivery BDXL and eDelivery SMP MAY be used as a discovery infrastructure for the eDelivery AS4 Dynamic Sender Profile Enhancement, defined in section 4.4 of the eDelivery AS4 specification [eDelivery-AS4].

2. Base Specification

This specification is based on the following OASIS specification:

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].

3. Implementation Guidelines

3.1. General Guidelines

Client and server components implementing this specification MUST conform to the OASIS Business Document Metadata Service Location Version 1.0 specification.

Server deployments of eDelivery BDX Location MUST use the "Service Provider Domains" option, defined in section 2.3.2 of [BDX-Location-v1.0].  The value of the provider domain name MAY differ for different sectors or communities and MUST also encode the communication environment, to separate "production" from other (e.g. "test" or "acceptance") environments.

3.2. Constructing the DNS query

To retrieve U-NAPTR resource records, the DNS query string MUST be created as follows: 

  1. The party identifier is encoded in a canonical form. Sections 4.1 and 4.2 provide examples of two such forms. A canonical form MAY be a complete standalone identifier or an identifier that can only be interpreted in combination with a separate catalog or scheme value.
  2. The canonical party identifier is processed using the SHA256 algorithm.
  3. The digest obtained in (2) is BASE32 encoded.
  4. Any trailing '=' padding characters added in (3) in the encoded digest are removed.
  5. If the BDXL service provider provides resource records for separate environments, a label identifying the applicable environment MUST be used in combination with value obtained in (4) for all environments other than production. For example, the service provider may provide resource records for the environments “acceptance” and “production”. In this case, a label MUST be added to records that are to be looked up in the “acceptance” environment.
  6. The values obtained in (4) and (5) are used as parameters in a service provider-specific formatting function that produces the final query domain string. Details of the formatting function are left to the service provider. If the canonical form needs to be combined with a separate catalog or scheme parameter, that parameter is another input to this formatting function. Furthermore, the service provider MAY also include other parameters (such as parameters to group the records for business domains, or for use with particular services) in the format.

Note that the query string does not include a B- prefix, unlike the convention specified in [SML]. Also note that labels in Domain Name System (DNS) names are case insensitive [RFC4343].

The service provider could adopt a simple concatenation of the values. For the “bdxl.example.com” domain and the “acceptance” environment, this would result in a query domain that has the suffix .acceptance.bdxl.example.com whereas for the production environment, the resulting domain suffix would have the value .bdxl.example.com. However, the service provider MAY also use different formatting conventions.

3.3. U-NAPTR Resource Records

BDX Location servers MUST set the service field of U-NAPTR records that link to metadata services based on the OASIS SMP to the value "meta:smp".  BDX Location clients that retrieve SMP-based metadata MUST restrict record searches to U-NAPTR records of this type. Note that the service field is case-insensitive, according to [RFC4848].

If the metadata service supports access using secure HTTP, URI values stored in BDXL U-NAPTR records MUST use the secure HTTP URL scheme ("https"). URI values MAY include path, query or fragment parts, in addition to the "authority" part. Note that scheme and host name are case insensitive. All other URI components MUST be treated as case sensitive.

3.4. Use with eDelivery SMP

When used in combination with [eDelivery-SMP] to locate SMP servers that expect to be accessed using the OASIS SMP HTTP binding, the URI returned by the BDXL server MUST NOT include the URI suffixes defined by the SMP HTTP binding. These suffixes MUST instead be appended by the SMP client to the URI returned by the BDXL server before the SMP server is queried.

Note that SMP uses the term Participant as a synonym of Party.

4. Examples

This section provides non-normative examples showing the use of eDelivery BDXL with ebCore and PEPPOL party identifiers and a sample BDXL U-NAPTR record.

4.1. Use with ebCore Party Identifiers

The eDelivery ebCore Party Identifier profile [eDelivery-EBCORE] uses and profiles the canonical party identifier defined in section 2.7 of [PARTYIDTYPE], which follows the pattern: urn:oasis:tc:ebcore:partyid-type:<<catalog-identifier>>:<<scheme-incatalog>>:<<scheme specific identifier>>. This identifier format therefore incorporates the catalog identifier and scheme identifier, in addition to the party-specific identifier.

For example, the GS1 Global Location Number (GLN) scheme [GLN] is registered in the ISO 6523 catalog under the "0088" code.

  • The canonical eDelivery ebCore Party Identifier for a company with GLN 4035811991021 therefore has the value urn:oasis:names:tc:ebcore:partyid-type:iso6523:0088:4035811991021.
  • Application of SHA256 and BASE32 encoding, followed by removal of padding characters yields the following value: I3QYB36CTAYRFGTHBYCQZDTOJFHGAZJEGLFOOE7727EGVDWRK5QQ.

For the production and acceptance environments of the bdxl.example.com service provider introduced as example in section 3.2, this will result in the following names

Note that these values are hypothetical examples only. For a specification of the domain name values to use with a specific BDXL service provider, consult the documentation of that service provider.

4.2. Use with PEPPOL Identifiers

The PEPPOL network also uses the ISO 6523 scheme catalog and identifies parties using schemes in this catalog and a scheme specific identifier. The value iso6523-actorid-upis is used to indicate the use of the ISO 6523 scheme catalog. This is combined with a party identifier value that is a combination of the ISO 6523 scheme code and the scheme specific identifier, concatenated using a single colon. The sample GLN number in section 4.1 therefore corresponds to the party identifier value 0088:4035811991021.

Application of SHA256 and BASE32 encoding, followed by removal of padding characters yields the following value: LZMEDSMZXYD37YC74TZVPYCMUANFCMN667JHGBFQDDRVMSE6NYTA. Again using the bdxl.example.com service provider introduced as example in section 3.2, this value can be combined with a suffix that includes the catalog identifier, an indicator of the environment and service provider specific labels:

Note that these values are hypothetical examples only. For a specification of the domain name values to use with a specific BDXL service provider, consult the documentation of that service provider.

4.3. Sample U-NAPTR Record

The following non-normative example provides a BDXL U-NAPTR record served by BDXL service provider bdxl.example.com for a party with ebCore Party Identifier urn:oasis:names:tc:ebcore:partyid-type:iso6523:0088:4035811991021 for use in production.


Sample U-NAPTR record
I3QYB36CTAYRFGTHBYCQZDTOJFHGAZJEGLFOOE7727EGVDWRK5QQ.bdxl.example.com.
;;       order pref flags service    regexp                                           replacement
IN NAPTR 100   10   "U"   "meta:smp" "!.*!https://www.anotherexample.com/smp/prod!"  ""

The returned URL does not contain the Party Identifier, as it is a URL for an SMP resource for which the client is expected to use the SMP REST binding. That binding defines how the party and document identifier are to be encoded and appended to the URL.

5. Conformance

An implementation conforms to this version of the eDelivery BDXL Profile if it:

  • Is a conformant OASIS BDXL 1.0 implementation, where conformance is defined in section 4 of [BDX-Location-v1.0].
  • Conforms to all normative statements in section 3 of this specification.

6. Ownership

The BDX Location technical specification is Copyright © OASIS Open 2017. All Rights Reserved.

The BDX Location technical specification is created by the OASIS BDXR Technical Committee which operates under the Non-Assertion Mode of the OASIS IPR Policy. OASIS is not aware of any statements or declarations regarding IPR related to the work of this technical committee.

OASIS BDX Location is similar to the PEPPOL SML [SML], but is based on a type of DNS resource records called URI-enabled Naming Authority Pointer records [RFC4848]. U-NAPTR supports discovery of full URLs, which are not limited to an "authority" part but may also include path, query or fragment parts.

This specification was originally created in the former EU e-SENS project. The e-SENS project completed in March 2017. The EU e-SENS project formally transferred ownership of its specifications to the European Commission, which accepted it for further maintenance in the context of the CEF Programme and then of the Digital Europe Programme. Information on governance and procedures for eDelivery is available from Governance and Procedures.

7. References

[BDX-Location-v1.0] Business Document Metadata Service Location Version 1.0. OASIS Standard, 01 August 2017. http://docs.oasis-open.org/bdxr/BDX-Location/v1.0/  

[eDelivery-AS4] https://ec.europa.eu/digital-building-blocks/sites/display/DIGITAL/eDelivery+AS4

[eDelivery-SMP] https://ec.europa.eu/digital-building-blocks/sites/display/DIGITAL/eDelivery+SMP

[eDelivery-EBCORE] https://ec.europa.eu/digital-building-blocks/sites/display/DIGITAL/eDelivery+ebCore+Party+Id

[GLN] Global Location Number https://www.gs1.org/gln

[PARTYIDTYPE] OASIS ebCore Party ID Type Technical Specification. September 2010. http://docs.oasis-open.org/ebcore/PartyIdType/v1.0/PartyIdType-1.0.pdf.

[RFC2119] A. Ramos. Key words for use in RFCs to Indicate Requirement Levels. IETF RFC 2119. January 1998. http://www.ietf.org/rfc/rfc2119.txt

[RFC4343] Domain Name System (DNS) Case Insensitivity Clarification. IETF RFC 4343. https://tools.ietf.org/html/rfc4343.

[RFC4848] Domain-Based Application Service Location Using URIs and the Dynamic Delegation Discovery Service (DDDS). IETF RFC 4848. https://tools.ietf.org/html/rfc4848. 

[SML] Service Metadata Locator. https://peppol.eu/downloads/the-peppol-edelivery-network-specifications/

[SMP-v1.0] Service Metadata Publishing (SMP) Version 1.0. OASIS Standard, 01 August 2017. http://docs.oasis-open.org/bdxr/bdx-smp/v1.0/.

8. Contributors

The eDelivery team is in charge of maintaining the current version of the eDelivery BDX Location specification. Information on governance and procedures for eDelivery is available from Governance and Procedures.

Details about contributors of previous versions can be consulted on the e-SENS website.

9. History

Ver.

Date

Changes made

Modified By

1.5

 

Minor update as part of the migration of the specification to CEF Digital, not requiring external review.

Layout changed to match CEF Digital template

Content copied from e-SENS architecture, with the following editorial changes and bibliographic updates:

  • Set the version number to 1.5.
  • Switched from e-SENS specification metadata to the CEF eDelivery specification metadata: Publication Date, Obsoletes, Obsoleted by,
  • Removed the Standardization and Sustainability Assessment section, the bibliographic reference to the e-SENS assessment and a reference to that.
  • Removed the empty Link to Test Assertions section.
  • Removed the link to list of known solutions.
  • Updated the Contributor section, historical contribution information is left to the last referenced e-SENS project version.
  • Updated the Ownership section to include the handover of the ownership of content from the e-SENS project to CEF Digital.
  • Started with a clean history table (the e-SENS history is still available in the 1.4 version).
  • Updated the BDXL and SMP bibliographic references to reflect their current OASIS Standard status and to use their recommended citation formats.
  • Removed the SML content, as it was only of historical interest but confused users. This specification is a BDXL profile.
  • Updated the diagram to use the diagram from OASIS SMP.
  • Updated the description of the formation of the DNS query string. This is now consistent with SML 3.1.
  • Added a reference to GS1 GLN.
  • Renamed the section "Specifications" to "Base Specification".
  • Changed "PR" to "e-SENS".

Gianmarco Piva,

Pim van der Eijk

1.6
 

Changes:

  • Version number bumped to 1.6.
  • Update to allow the URL to include a path, as requested by TOOP. Added note that this is not backward compatible with SML.
  • Added a U-NAPTR example.
  • Modified the first step in section 2 to accommodate identifier systems other than ebCore Party Id.
  • Changed PR-SMP bibliographic reference to e-SENS-SMP and updated its version number to 1.10.
  • Changed PR-EBCORE bibliographic reference to e-SENS-EBCORE.
  • Various minor editorial.

Updated after CEF team meeting 15.12.2017:

  • Moved reference to SML to History section.
  • Removed discussion on SML compatibility, as there is no requirement to support (temporary) co-existence of SML and BDXL.
  • Adjusted so that plain HTTP URIs are supported (if the metadata server does not support HTTPS)
  • Added subsections in section 3 for readability.
  • Added note that SMP uses Participant as a synonym of Party.
  • Added note that DNS names and the service field are case insensitive. Explained case sensitivity of URIs.
  • Separate the specification of the domain name from the use of ebCore Party Identifiers.
  • Also added a PEPPOL example.
  • Added Conformance section.
  • RFC 2119 reference.
  • Minor editorial improvements.

Updated after CEF team meeting 25.12.2017

  • Changed status to eDelivery Community Draft

Updated on 30.05.2018

  • Changed status to eDelivery Community Specification
Pim van der Eijk

Details about previous versions of the specifications can be consulted on the e-SENS website.