Specification
OpenPeppol AISBL

Peppol Transport Infrastructure
ICT - Models

Peppol Directory

Version: 1.1.1
Status: In use

Editors:
Philip Helger, OpenPeppol Operating Office
Ger Clancy, IBM

Peppol Implementation Specification
Peppol Directory v1.1.1

Revision History
Version Date
2015-08-03

Description of changes

Approvedby

Updated details on the PD-SML connection

PH

Editorial changes in 5.2.2, 6.1.1
Changed link in chapter 7
2015-09-10

Moved chapter 4.1.5 to become 4.1.1

PH

Fixed example requests in the PD Indexer section
Fixed HTTP return codes in Indexer section
Added chapter 4.1.7 on internal processing
2016-01-20

Updated to Peppol DirectoryPH

Adopted to separate SMP interface
Adopted to new XSD
2016-04-22

Introduction less technicalPH

Logical separation between Publisher and Indexer lessimportant
2016-11-28

Updated to MC decisions

PH

Stripped down Business Card data
1.0

1.1

2016-12-05

Updated contributor listPH2017-04-03

Updated REST API description slightlyPH

2018-07-17

Updated REST API to match implementation

PH

Chapter 5.2: fixed example; added note on encoding
Added chapter “Usage outside of Peppol”
The BC data model now has a multilingual entity name
Minor editorial corrections and clarifications added
1.1.1

2020-10-15

Updated to the new Peppol brandingPH

Changed the spelling from “PEPPOL” to “Peppol”
Added new Introduction chapter including References

2/23

Peppol Implementation Specification
Peppol Directory v1.1.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 madethrough appropriate citation, quotation or both.

Statement of copyrightThis deliverable is released under the terms of the Creative Commons Licence accessed through thefollowing 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.

3/23

1

Contributors

2
3

Organisations

4IBM, http://www.ibm.com

5

ESV, The Swedish National Financial Management Authority, http://www.esv.se

6
7

Persons

8

Ger Clancy, IBM

9Martin Forsberg, ESV

10Georg Birgisson, Midran Ltd.

BRZ (Bundesrechenzentrum)1, Austria, http://www.brz.gv.at/

Philip Helger, OpenPeppol Operating Office (editor)

1

English: Austrian Federal Computing CentrePeppol Implementation Specification
Peppol Directory v1.1.1
11

1 Introduction

12
13
14
15
16

1.1 Audience
This document describes a Peppol policy and guidelines for use of identifiers within the Peppol
network. The intended audience for this document are organizations wishing to be Peppol enabled
for exchanging electronic documents, and/or their ICT-suppliers. More specifically it is addressed
towards the following roles:

17

ICT Architects

18

ICT Developers

19

Business Experts

20
21
22
23

1.2 Terminology

24
25
26
27

1.3 References

28
29[RFC2119]"Key words for use in RFCs to Indicate Requirement Levels",
http://www.ietf.org/rfc/rfc2119.txt

30
31
32

[PFUOI4]“Peppol Policy for use of Identifiers 4.1.0”,
https://docs.peppol.eu/edelivery/policies/PEPPOL-EDN-Policy-for-use-of-identifiers4.1.0-2020-03-11.pdf

33
34
35
36
37
38
39

2 Introduction to Peppol Directory (non-normative)

40
41
42
43
44
45

An additional singleton service is added to the Peppol infrastructure: the so-called PD Server. It is
filled with electronic Business Cards of the Peppol participants on a voluntary basis meaning that
SMP providers can (but are not forced to) publish their client’s metadata in the PD. The data is stored
in correlation with the SMP entry of the respective participant (aka service group). Details aredescribed in chapter 5.2. SMP providers MUST provide the technical interface and MAY publish
client’s metadata.

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

[PEPPOLSMP] “Peppol Service Metadata Publishing (SMP) 1.2.0”,
https://docs.peppol.eu/edelivery/smp/PEPPOL-EDN-Service-Metadata-Publishing1.2.0-2021-02-24.pdf

The goal of this document is to describe the architecture and interfaces of the Peppol Directory (PD;formerly known as Peppol Yellow Pages) project. The goal of the PD project is to create a publicly
available, searchable list of all Peppol participants with their respective metadata like company
name, country code, etc. (for details see chapter 5.1). The PD is not meant to replace existing Peppol
components but to be an aggregator for data that is contained in existing Peppol SMPs
[PEPPOLSMP].

2/23

Peppol Implementation Specification
Peppol Directory v1.1.1
46
47
48

This document describes the architecture of the PD server, the interfaces to and from it as well as thedata format for the Business Cards (see chapter 5) within the SMP. This document concludes with ahigh-level technical description on how the PD Server is implemented.

49
50
51
52
53

3 Why Peppol Directory? (non-normative)

54
55
56
57
58
59

Trying to solve the problem of finding each other, Peppol Directory (PD) is introduced, a central
service to query based on given metadata. Querying may be part of a manual or automated process
before performing lookup in SML (Service Metadata Locator) and SMP (Service Metadata Publisher).
PD contains indexed Peppol Directory Business Cards (BC) containing metadata related to a given
PPID. The lack of a Peppol Directory is a constraint to wider scale adoption of Peppol by small andmedium sized enterprises.

60
61
62
63

3.1 Use Cases

64
65
66
67

3.1.1 New Peppol BIS support - Matching
An organization that has recently become a Peppol participant, wishing to exchange a particular
Peppol BIS, as a Customer or a Supplier, will want to find who of their trading partners are capable ofexchanging the same BIS documents in the opposing role.

68
69
70

As example an organization that is starting to send invoices may want to know which of theircustomers can receive them and an organization that is starting to receive invoices will want to know
which of their suppliers can send them.

71
72
73
74

3.1.2 Monitoring new Peppol users - Alerting
An organization that is using Peppol to exchange one or more Peppol BIS may want to monitor whenmore of their trading partners become Peppol participants and consequently to automate theirtrading relations with them by using Peppol.

75
76
77
78

3.2 Planned key functions of Peppol Directory

Due to variations between countries and markets, there are no shared models on how to know the
Peppol Participant ID (PPID) of the sender, further enforced by the lack of open national businessregistries. Knowing each other in domains of limited size, for example e-CODEX project in e-Justice, iseasy, however in domains like Peppol having potentially millions of organizations it is impossible.

The Peppol Directory is intended to support business cases that are concerned with finding Peppol
participants registered on the Peppol network, in order to start exchanging business documents withthem. Some of the possible business cases are identified below.

The following key functions are planned for the Peppol Directory and will be implemented throughdifferent releases of the Directory. These features are intended to support the business use cases
described in the previous chapter.

3/23

Peppol Implementation Specification
Peppol Directory v1.1.1
79
80
81
82
83

3.2.1 Free text search
A free text search allows the Directory user to enter a text string into an online form and get a list of
result for all listings in the Directory where that string appears. As an example, if the user enters theword "Acme" he will get a list of all participants whose name contains the word “Acme” as well as
participants where the word “Acme” appears in other elements of the Business Card.

84
85

The user can browse the list to find the Peppol participant he is looking for and then click on his
choice to see the full details.

86
87
88
89
90
91
92
93

3.2.2 Identifier search
The Directory supports the use of qualified identifiers for the search. The objective is to enable single
match searches where the user submits a query on whether there exists a user, with a particular
identifier and BIS capabilities. This enables searching by VAT, legal identifiers and other parametersthat are commonly known but may differ from the Peppol end point identifiers. As an example, auser may want to find the end point identifier for a customer who has a particular VAT identifier. By
restricting the search to a particular capability, he can use the query to monitor when that customer
starts to support the given documents.

94
95
96
97

3.2.3 API connection
The Peppol Directory will also enable Directory users to let their systems connect automaticallyinstead of manually browsing through a web interface. This supports automated searches that can be
integrated into the sending process.

98
99

A drawback to be considered is that the publication of the Business Cards in the Peppol Directory
happens on a voluntary basis.

100
101
102

3.3 Considerations

103
104
105
106
107
108
109

3.3.1 Searching for senders
The current architecture of the Peppol network does not require Peppol Participants who are only
sending documents to be registered in the SMP's and consequently they are not in the SML. This
limits the capability of the Peppol Directory to include these Peppol participants in search results.
This relates to other issues that are currently being addressed in other Peppol initiatives. A potentialchange in the Peppol policy that requires registration of senders would benefit the Peppol Directory
without requiring additional changes to the PD.

110
111

Alternatively sending only participants may be registered to an SMP with an empty service groupwhich allows them to publish Business Cards for the Peppol Directory as well.

112
113
114
115

3.4 Usage outside of Peppol

The following considerations influencing the development of the Peppol Directory have been
identified but require additional analysis.

This specification and the software components were originally created for the usage within Peppol.
As other projects also showed interest in reusing these artefacts it can be clearly stated, that thecomponents described herein can be reused in different scenarios unrelated to Peppol. E.g. the

4/23

Peppol Implementation Specification
Peppol Directory v1.1.1
116
117

TOOP project (www.toop.eu) uses Peppol Directory as “TOOP Directory” inside their dynamic
discovery component to find multiple receivers using the REST query API.

118
119
120
121
122

4 PD Server architecture (non-normative)
This section describes the overall architecture of the PD Server. It logically consists of two majorparts: a PD Indexer which is responsible for creating, updating, deleting and indexing the Business
Card data and the PD Publisher which is the public web frontend to the PD for both humans andmachines.

123
124

Figure 1: PD big picture without SML

125
126
127
128
129
130

The above big picture outlines the information flow. If a participant’s business card is added to,
updated to or deleted from an SMP, the SMP SHOULD trigger an update to the PD Indexer (see arrowfrom SMP to the PD Indexer in the figure) even if the Business Card contained in the SMP is empty. If
data is to be added or updated on the PD, the PD Indexer will retrieve the complete Business Cardfrom the respective SMP and index it for searchability (see arrow from PD Indexer to Business card in
the figure).

5/23

Peppol Implementation Specification
Peppol Directory v1.1.1
131
132
133
134
135
136

If a user wants to know whether a certain company is registered in the Peppol network he opens the
web site of the PD Publisher, types the search term (e.g. the company name) and a list of potential
hits (including the Peppol participant identifier and the supported Peppol document types) shows up.
In addition to the human interface, a REST interface for automatic searching is offered. The PD
Publisher retrieves all relevant information directly from the PD Indexer so that no interaction withthe concerned SMPs is necessary.

137
138
139
140

An extension to the PD Indexer is the direct connection to the SML to retrieve a list of all registered
Peppol participants. In this case the PD Indexer will query the SML regularly (e.g. once a week) for acomplete participant list and queries the respective SMPs independent of the SMP provided update
status.

141
142

Figure 2: PD big picture with SML

143
144
145

As shown in the previous figure the overall architecture is only extended to interconnect with the
SML and no other changes are necessary. The SML already offers an interface to retrieve a list of all
registered Peppol participants and is therefore prepared to be interconnected with the PD.

146
147
148
149

Early benchmarks on the SML test machine (being slower than the production machine) showed thata list with 100.000 entries can be created in 16 seconds and 150.000 entries took 34 seconds. By
middle of 2018 approx. 112.000 entries were in the production database, by October 2020 thenumber increased to approx. 248.000 entries.

6/23

Peppol Implementation Specification
Peppol Directory v1.1.1
150

5 Business card (normative)

151
152
153
154
155

5.1 Data format

156
157
158
159

Existing formats like vCard, xCard or the UBL 2.1 Party type were not considered because they are
either not XML or too complex to interpret fully. Instead a new minimal XML-based format is createdbecause Peppol participant identifiers are used very differently it was decided to use a very flexible
scheme that can represent multiple business entities at once.

160

The format defines a single business card consisting of the following fields:

161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186

This section describes the layout of the business card data that is stored in an SMP. Because thescope of a single Peppol participant within an SMP can be very broad, the data format must be
capable of handling information for more than one business entity in a structured way. Sometimes a
Peppol participant may even link to different entities in different countries.

•

•

•

Peppol participant ID
o Description: Peppol participant identifier corresponding to a service group hosted on
the same SMP. The constraints for participant identifiers are described in [PFUOI4].
o Multiplicity: 1..1 (mandatory)
Peppol document type ID
o Descriptions: all Peppol document type identifiers as indicated by the default SMP
service group query. The constraints for document type identifiers are described in[PFUOI4].
o Multiplicity: 0..n (optional but potentially many)
Business entity
o Description: a business entity that can be reached via the provided Peppol
participant ID (see details below)
o Multiplicity: 0..n (optional but potentially many)

Each Business Entity consists of the following fields:•••

Entity nameo Description: the company name or the name of the governmental entity. The nameMUST NOT be empty and MAY include an optional language per entity name. If thelanguage is used it MUST be in ISO 639-1 format (e.g. “de” for German).
o Multiplicity: 1..n (mandatory but potentially many)
Country codeo Description: the country code to which the entity belongs. The format MUST be ISO
3166-2 (e.g. “AT” for Austria)
o Multiplicity: 1..1 (mandatory)
Geographic informationo Description: describes the location or region of the entity that is usually used to
identify the entity. This may be an address, a state name etc.

7/23

Peppol Implementation Specification
Peppol Directory v1.1.1
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210

•

•

o Multiplicity: 0..1 (optional)
Identifiero Description: additional (non-Peppol) identifiers of the entity that are not part of the
Peppol participant identifier. It consists of a type and a value. This can e.g. be anational VAT identification number; a national company register number etc. The
following identifier types (case insensitive) must at least be supported by the
Directory:▪ “vat” – VAT identification number including the national prefix▪ “orgnr” – the national organisation number▪ “gln” – Global Location Number (GLN)▪ “duns” – DUNS numbero Multiplicity: 0..n (optional but potentially many)
Registration dateo Description: the date when the participant joined the Peppol networko Multiplicity: 0..1 (optional)

The link to the XML Schemas describing the layout of the Business Card can be found in chapter 8 ofthis document. To support future updates of this Business Card scheme the XML root element(BusinessCard) has an XML namespace URI that allows for easy versioning of the contained data:•••

Version 1 of the XML schema for the business card uses the XML namespace URI
http://www.peppol.eu/schema/pd/businesscard/20160112/
Version 2 of the XML schema uses the XML namespace URI:
http://www.peppol.eu/schema/pd/businesscard/20161123/
Version 3 of the XML schema uses the XML namespace URI:
http://www.peppol.eu/schema/pd/businesscard/20180621/

211

A non-normative example Business Card with a single entity looks like this:

212
213
214
215
216
217
218
219
220
221
222
223

<BusinessCard
xmlns="http://www.peppol.eu/schema/pd/businesscard/20161123/"><ParticipantIdentifier
scheme="iso6523-actorid-upis">0088:example</ParticipantIdentifier><BusinessEntity registrationDate="2010-07-06"><Name>ACME Inc.</Name><CountryCode>AT</CountryCode><GeographicalInformation>ACME street 123</GeographicalInformation><Identifier scheme="VAT">ATU12345678</Identifier><Identifier scheme="OrgNr">hjdh7as9ds</Identifier></BusinessEntity></BusinessCard>

8/23

Peppol Implementation Specification
Peppol Directory v1.1.1
224
225
226

5.2 SMP impacts

227
228
229
230
231
232

5.2.1 Storage (non-normative)
This section describes how and where Business Cards are to be stored in an SMP (see [PEPPOLSMP]).
The SMP differentiates between Service Groups and Service Registrations. A Service Group isbasically the Peppol participant identifier whereas a Service Registration is the combination of aparticipant identifier, a document type identifier, a process identifier, a transport protocol and an AP
endpoint URL (plus some additional information).

233
234
235

Each Business Card MUST be stored in relation to a single SMP Service Group. There are nopredefined rules how this is to be achieved as the data storage mechanisms of an SMP server arequite different in practice. The only binding rules are:This chapter describes the constraints for storing Business Cards in an SMP and how to access theBusiness Cards from the outside world.2

236
237
238
239

1. An SMP MUST NOT provide Business Cards for service groups not owned by this SMP.
2. Each service group MUST have zero or one associated Business Card.
3. The link between the Service Group and the Business Card MUST be the Peppol participant
ID.

240
241
242
243
244
245
246
247
248

Originally it was considered to store the Business Card information in the Extension element of an
SMP Service Group. The positive aspects of this solution are that the data model of existing SMPs
does not need to be altered and that no new APIs for the SMP need to be provided. The negative
aspects of this solution are that the network traffic for non-PD queries would heavily increase andthe general performance of SMPs might be downgraded and that non-relevant information would be
returned in regular Service Group queries. An additional problem with this solution is that the Peppol
SMP specification is lacking support for multiple extensions in a single service group which in turnwould require an additional non-standard “extension container” to maintain extensibility. OASISBDXR SMP adds supported for multiple extensions.

249
250
251
252

5.2.2 Public REST interface
To retrieve the Business Cards from an SMP server a new REST interface is introduced. This interface
MUST be provided by all Peppol SMP servers. REST was chosen because the existing SMP interfaces
are already REST based and therefore no new technology is introduced.

253
254

5.2.2.1 Retrieve Business Card interface
REST request: GET /businesscard/{participantID}

255
256

Note: {participantID} is the placeholder for the effective Peppol participant identifier in the
URL encoded form

2

phoss SMP and IBM SMP have already implemented support for the BusinessCard API in their solutions.

9/23

Peppol Implementation Specification
Peppol Directory v1.1.1
257
258

REST response: the XML representation of the Business Card (according to an XSD specified inchapter 8) preferably in UTF-8 encoding using MIME type application/xml.

259

REST response code:

260
261
262
263
264
265

●
●
●

HTTP 200 (OK) – everything was ok. A response body MUST be send back.
HTTP 404 (Not found) – no Business Card was found for the provided participant ID.
HTTP 500 (Internal server error) – something internally went wrong. Response body SHOULD
contain the details in plain text.
Non-normative example to query the business card for Peppol participant 9915:test on the SMP
server running at http://smp.example.org:266

http://smp.example.org/businesscard/iso6523-actorid-upis%3A%3A9915%3Atest

267

The response may look like the example provided in section 5.1.

268
269

Note: using Peppol participant identifiers directly in URLs may impose problems. It must be ensured
that appropriate URL escaping is performed (e.g. : replaced with %3A).

270
271

Note: this interface must also work with the computed “B-….edelivery.tech.ec.europa.eu” URLs.

272
273
274

Note: as a future extension, the response of the SMP may be signed with the respective SMP
certificate.

275
276
277
278
279

6 PD Indexer (normative)

280
281

All REST interface URLs contain a version number so that it will be easy to provide updated interfaces
in the future without breaking the existing ones.

282
283
284

6.1 Authentication and authorization

285
286
287
288
289

For security reasons, only legitimate SMPs are allowed to request modifications in the PD Indexer. To
ensure this all HTTP calls to the PD Indexer interface must provide a client X.509 certificate. This is
the same technology that is already used in the SMP to SML communication and should therefore be
implementable in a quick and easy way. Requests to the PD Indexer without a client certificate will
result in an error.

This chapter describes the technical details of the PD Indexer. It describes the data elements thatmust be passed to the PD Indexer so that Business Cards can be created, updated, deleted or
retrieved. This is a REST interface, because the SMP server (that will trigger this interface) is also a
REST server and therefore the technology is well known and supported.

Note: this section is only applicable, it the PD Indexer runs on a server that offers secure HTTP
connections (https via TLS).

10/23

Peppol Implementation Specification
Peppol Directory v1.1.1
290
291

The provided client certificate must be the SMP certificate as used for the communication with the
SML.

292
293
294
295
296

6.2 Adding a participant
For adding a participant, only the participant identifier must be passed to the PD Indexer. The
Business Card is read directly from the respective SMP (determined via DNS lookup) and is notpassed in this call. This allows the PD Indexer to build a queue of items to be updated in an optimized
way, and also avoids overwriting data of participants that are owned by different SMPs.

297
298

Figure 3: Add participant workflow

299

REST request: PUT /indexer/1.0/

300

Request body: {participantID}

301

Note: {participantID} is the placeholder for the effective Peppol participant identifier

302

Example request:

303
304

•
•

URL: PUT /indexer/1.0/
Body: iso6523-actorid-upis::0088:gln1234

305

The participant identifier MUST NOT be URL encoded.

306

REST response code:

307
308
309
310

●
●
●

HTTP 204 (OK, No content) – everything was ok. No response body is send back.
HTTP 403 (Forbidden) – no client certificate or an invalid client certificate provided
HTTP 500 (Internal server error) – something internally went wrong. Response body SHOULD
contain the details in plain text.

11/23

Peppol Implementation Specification
Peppol Directory v1.1.1
311
312
313
314
315
316
317

Note: This requires the DNS entry of the added Peppol participant already being available publicly toresolve the owning SMP. Therefore an SMP MUST call the PD after the registration at the SML. The
PD Indexer will handle added participants gracefully if the respective DNS entry is not yet present
and will retry at a later point in time. If a new participant DNS entry is not present within aconfigurable duration related to the original indexing request, this particular request is discarded
and therefore no indexing takes place. If previous indexed information of that participant ispresent (if it is an updating call) they are left unchanged.

318
319
320

6.3 Modifying an existing participant
If the Business Card of an existing participant is modified the PD Indexer must be informed about thechange. The API and the constraints are identical to “Adding a participant” (see chapter 6.2).

321
322

Figure 4: Modify participant workflow

323
324

Note: there is no possibility to identify whether the participant was added or updated by the
response. To check for existence, use the GET operation defined below.

325
326
327
328
329

6.4 Deletion of a participant
When a service group in the SMP is about to be deleted (either because the participant leaves the
Peppol network or because an SMP migration takes place), the PD Indexer must be notified. To
delete participant information in the PD Indexer it is suitable to provide only the respective Peppol
identifier.

12/23

Peppol Implementation Specification
Peppol Directory v1.1.1

330
331

Figure 5: Delete participant workflow

332

REST request: DELETE /indexer/1.0/{participantID}

333
334

Note: {participantID} is the placeholder for the effective Peppol participant identifier in URL encoded
form

335

Example request:

336•

DELETE /indexer/1.0/iso6523-actorid-upis%3A%3A0088%3Agln1234

337
338

Note: using Peppol participant identifiers directly in URLs may impose problems. It must be ensured
that appropriate URL escaping is performed (e.g. : replaced with %3A).

339

REST response code:

340
341
342
343

●
●
●

HTTP 204 (OK, No content) – everything was ok. No response body is send back.
HTTP 403 (Forbidden) – no client certificate or an invalid client certificate provided
HTTP 500 (Internal server error) – something internally went wrong. Response body SHOULD
contain the details in plain text.

344
345

Note: if a participant is moved (migrated) from one SMP to another it must first be deleted by the old
SMP and then re-created by the new SMP.

346
347
348
349
350

Note: the delete operation may impose a security problem because one SMP can delete theinformation of a participant created by a different SMP. Therefore the deletion does not directly
delete the information in the index but only marks the respective records internally as “deleted”
so that the data can be restored in case of a misuse.

351
352
353

6.5 Existence check of a participant

354

REST request: GET /indexer/1.0/{participantID}

Checking whether a Business Card of a participant is present in the PD Indexer can be performed via
the following interface:

13/23

Peppol Implementation Specification
Peppol Directory v1.1.1
355
356

Note: {participantID} is the placeholder for the effective Peppol participant identifier in URL encoded
form

357

Example request:

358•

GET /indexer/1.0/iso6523-actorid-upis%3A%3A0088%3Agln1234

359
360

Note: using Peppol participant identifiers directly in URLs may impose problems. It must be ensured
that appropriate URL escaping is performed (e.g. : replaced with %3A).

361

REST response code:

362
363
364
365
366

●
●
●
●

HTTP 204 (OK, No content) – Yes, the participant is already in the PD Indexer.
HTTP 403 (Forbidden) – no client certificate or an invalid client certificate provided
HTTP 404 (Not found) –the participant is not in the PD Indexer.
HTTP 500 (Internal server error) – something internally went wrong. Response body SHOULD
contain the details in plain text.

367
368

Note: because of the internal asynchronous processing, it might take some time after an index
request until the participant is available in search results. See chapter 6.7 for more details.

369
370

Note: calling this API also requires the presence of a client certificate.

371
372
373
374

6.6 Auditing and Logging

375
376
377
378
379

6.7 Internal processing of the data (non-normative)

380
381
382
383
384
385

If the data retrieval from the SMP fails (for whatever reason) the work item is put into a special “retry
queue” and the data retrieval is retried sometime later (suggested duration until retry is 5 minutes –must be configurable). If an entry cannot be indexed after a certain period of time (suggested period
is 24 hours – must also be configurable), it is moved to a “dead work item queue”. In case of apermanent failure manual intervention is necessary. E.g. the PD administrator may re-trigger thework item manually or choose to drop it completely.

386
387
388

The asynchronous processing may impose problems when trying to check for the existence of acertain participant identifier in the index. This check will only return success if the item was alreadyprocessed and stored in the index but not if it is still in the work queue.

All successful calls to the PD Indexer (create/update/delete/get) are logged together with thetimestamp, the source IP address and some information from the provided certificate (country,
subject name and serial number) to ensure traceability of the performed actions.

Internally the Indexer keeps a FIFO work queue that is processed asynchronously. All new indexing
requests (create/update/delete) are put into that queue and wait for their serial processing to avoid
overloading a single SMP with queries. That’s why deletion (see chapter 6.4) may not trigger an
immediate return code like “not found” because the result is not known synchronously.

14/23

Peppol Implementation Specification
Peppol Directory v1.1.1
389
390
391
392
393
394
395
396
397
398
399

6.8 Internal data structure (non-normative)
The internal data structure of the PD Indexer is slightly different from the Business Card entities
defined in chapter 5.1. Besides the Business Card content, the following data elements should also be
stored:•••All supported Peppol document type identifiers as listed by the SMP service group interface.
Therefore, a separate SMP query on the ServiceGroup must be performed and the document
types must be extracted.
The unique identifier taken from the client certificate that triggered the indexing of the
document (the “requestor”). This can e.g. consist of the certificates subject name, serial
number and country code.
The date and time when the Business Card was last indexed.

400
401
402
403
404

7 PD Publisher (normative)

405

Currently two implementations are available:

406

https://directory.peppol.eu (production server)407

https://test-directory.peppol.eu (test server)

408
409
410

7.1 Search interface

411
412
413
414
415
416

7.1.1 Request
The relative base URL of the REST search service is /search/1.0/[format] which is thenfollowed by a list of query parameters as outlined below. The [format] placeholder in the request
API denotes the desired response format. Initially xml (for XML output) and json (for JSON output)
are supported but other formats might be added as future extensions. All search REST requests are
HTTP GET requests. Other HTTP methods like POST, PUT etc. are not supported.

417

The search routines use the following text matching algorithms:

418
419
420
421

This section describes the components of the PD Publisher. It consists of a machine-to-machine
search interface as well as a search interface for humans as well as a list of registered Peppol
participants for download. Additional features can be integrated into the Publisher after the initial
version.

This section only describes the machine-to-machine search interface. It uses REST as the protocol andresponds with XML or JSON data.

••

Exact match (case sensitive): the search term and the indexed values must be completely
equal, including case sensitivity.
Exact match (case insensitive): the search term and the indexed values must be completely
equal, excluding case sensitivity.

15/23

Peppol Implementation Specification
Peppol Directory v1.1.1
422
423
424
425
426
427

•

•

Partial match: the search term must be equal or fully contained in the indexed value in a caseinsensitive way (e.g. searching for “tici” or “TICI” in the indexed value “participant” will be amatch)Starts with match: a special version of the partial match that requires the indexed value tobegin with the search term in a case insensitive way (e.g. search for “part” or “PART” will
match “participant” but “art” won’t match “participant”)

Parameter nameq

Explanation
General purpose query term.
This term is searched in all fields with the matching rules of the respective
fields.
Multiple search terms can be provided separated by a whitespace character. If
multiple search terms are provided, they are interpreted as “AND” operators,
so only results with all query terms are returned.
participant
Searches for exact matches (case insensitive) in the participant identifier field(the identifier scheme must be part of the value).
nameSearches for partial matches in the entity name field.
Only search terms consisting of at least 3 characters are used for search.
This parameter can occur more than once.
Tokens are not split when using this parameter.
country
Searches for exact matches (case insensitive) in the country code field.
This parameter can theoretically occur more than once but it does not makesense, because a business card cannot have more than one country.
geoinfo
Searches for partial matches in the geographic information field.
Only search terms consisting of at least 3 characters are used for search.
This parameter can occur more than once.
Tokens are not split when using this parameter.
identifierScheme Searches for exact matches (case insensitive) in the additional identifier typefield (only the type, not the value).
Tokens are not split when using this parameter.
Combine this field with identifierValue field for fine-grained searching.
identifierValue
Searches for exact matches (case insensitive) in the additional identifier value
field (only the value, not the type).
Tokens are not split when using this parameter.
Combine this field with identifierScheme field for fine-grained searching.
websiteSearches for partial matches in the website field.
Only search terms consisting of at least 3 characters are used for search.
This parameter can occur more than once.
Tokens are not split when using this parameter.
contact
Searches for partial matches in the contact fields (type, name, phone number
and email address).
Only search terms consisting of at least 3 characters are used for search.
This parameter can occur more than once.
Tokens are not split when using this parameter.
addinfo
Searches for partial matches in the additional information field.
Only search terms consisting of at least 3 characters are used for search.

16/23

Peppol Implementation Specification
Peppol Directory v1.1.1

428
429

This parameter can occur more than once.
Tokens are not split when using this parameter.
regdateSearches for exact matches in the registration date field. The value of the dateto search must be provided in the format ‘YYYY-MM-DD’ (ISO 8601/XML
Schema based date format).
The parameter supports neither a time nor a time zone.
doctype
Searches for exact matches (case sensitive) in the document type identifier
field (the identifier scheme must be part of the value).
If multiple of the query parameters are used together only the results matching ALL query terms are
returned (like a boolean AND operation).

430

The following table contains the additional parameters that can be used to control the result subset:
Parameter nameresultPageIndex

resultPageCountbeautify

Explanation
The result page to be shown. If this parameter is not present the first page isreturned. The result page index is 0-based meaning that the first page has index
0. The index of the first search result returned is calculated byresultPageIndex * resultPageCountThe number of results to be returned on a single page. If this parameter is notpresent 20 results are returned by default.
Format the results so that they are more human readable? This should only be
used for debugging purposes as it increases the transferred data volume. Bydefault the returned code is minified.

431
432
433
434

7.1.2 Response
If no query term parameter (see table in chapter 7.1.1) is provided the return value is HTTP 400 (BadRequest).

435
436

In addition to the result Business Cards, each response contains the following fields (in a syntaxspecific way):
Field nameversiontotal-result-countused-result-countresult-page-index
result-page-countfirst-result-index

last-result-index

Explanation
The version of the response layout, defining the contained fields. This is only
present to handle future modifications. The current version is 1.0.
The total number of matching documents.
The number of results contained in the response. This is always ≤ total-resultcount as it is based on the paging parameters used.
The 0-based index of the result page.
The number of entities to show on a single page.
The effective 0-based index of the first result item returned (inclusive). This is
the result of
result-page-index * result-page-count.
The effective 0-based index of the last result item returned (inclusive). This is
the result ofmin ((result-page-index + 1) * result-page-count - 1, total-result-count - 1).

17/23

Peppol Implementation Specification
Peppol Directory v1.1.1
query-terms
creation-dt

The combined query string that was used to perform a search. This is mainly fordebugging purposes to cross-check which parameters took effect in searching.
The UTC date and time when this response was created. If possible it isformatted according to XML Schema (XSD) rules.

437
438
439
440
441
442

Note: the PD Publisher will deliver at most the top 1.000 results. If the combination of
resultPageIndex and resultPageCount results in too small (< 0) or too large values (>1000) the return value is HTTP 400 (Bad Request). The index of the first search result returned isresultPageIndex * resultPageCount. The index of the last search result returned is(resultPageIndex + 1) * resultPageCount - 1.

443

7.2 User interface (non-normative)

444
445
446
447
448

7.2.1 Use case Search
The PD Publisher must offer a publicly available web page where the user can enter search terms tosearch for one or more Peppol participants. It should provide a simple search form where only a setof terms can be entered and the PD Publisher will search for the best possible matches. Additionally,an extended search form with all fields (as outlined in chapter 7.1.1) should be available.

449

The search results will be shown on the website and will also be made available for download.

450
451
452
453

7.2.2 Use case Browse
The PD Publisher should offer a list of all registered business entities so that the information isbrowsable or even downloadable as e.g. an Excel document. This implies that the full data must be
stored in the PD Indexer.

454
455
456

8 Annex A - Business Card XSD

457
458

https://github.com/phax/phoss-directory/tree/master/phoss-directorybusinesscard/src/main/resources/schemas459

The details in the versions are as follows:

460
461
462
463
464
465
466
467

The Peppol Directory implementation supports multiple Business Card formats. The official Business
Card XML Schemas can be found in the following folder:••

peppol-directory-business-card-20160112.xsd
o This is the original proposal of the data format
o It contains a single entity name without a language
peppol-directory-business-card-20161123.xsd
o This is the official data format version 1
o Compared to 20160112 it does not contain the fields “AdditionalInformation”,“Contact” and “WebsiteURL” but for the rest it is identical.
o It contains a single entity name without a language

18/23

Peppol Implementation Specification
Peppol Directory v1.1.1
468
469
470
471

•

peppol-directory-business-card-20180621.xsd
o An extension to the 20160112 format
o It allows to specify more than one name in different languageso This is the preferred version to implement

472
473
474

9 Annex B - Implementation proposal (non-normative)

475
476

All data described in this document must be stored and/or transmitted in UTF-8 character encoding
set. Using other character encodings is prohibited.

477

The rest of this chapter assumes that the development is done with Java.

478
479
480
481
482

9.1 PD Server

483
484
485

9.1.1 PD Indexer
The PD Indexer is responsible for gathering the business cards from the different SMPs and storing it
into a searchable index. It is also responsible for periodically grabbing all participants from the SML.

486

The basic components are:

487
488
489
490
491
492
493
494
495
496
497
498
499
500
501

This section roughly describes, how the PD Server could be implemented and how existing SMP
servers could be modified to interact with the PD server.

For simplicity the PD Server should be implemented as a regular Java web application that is runnable
on a regular servlet container like Apache Tomcat or Jetty. It internally consists of two main parts:
the PD Indexer and the PD Publisher. Both components have to expose a component to the outside
world but need to fulfil different tasks.

•

•
•
•
•
•

A “work queue” that handles the requested actions for certain participants with a certain
priority handling (requests from SMPs have a higher priority than SML crawling results). The
work queue must be able to filter out duplicate requests and leave only the ones with thehighest priority.
A “fetcher” that grabs action items from the work queue and queries the SMP for thecorresponding data of a participant
An “indexer” that takes the fetch results and stores them into a searchable index
A scheduled “SML retriever” that retrieves the participant list from the SML and stores all
entries for updating in the work queue.
A REST server implementing the interfaces as defined in chapter 6 and accordingly filling thework queue. Only HTTP requests providing a valid Peppol SMP client certificate are accepted.
An “auditor” that keeps track of all indexing actions together with some meta information

The PD Indexer is based on Apache Lucene (https://lucene.apache.org/core/ - Apache 2 License) for
the indexing. The REST interface is to be done with Jersey (https://jersey.java.net/ - CDDL 1.1 or GPL
2 with Classpath exception) like with the SMP.

19/23

Peppol Implementation Specification
Peppol Directory v1.1.1
502
503
504
505
506

9.1.2 PD Publisher
A simple PD Publisher can be built with the ph-oton library (https://github.com/phax/ph-oton Apache 2 License) which offers capabilities to create state of the art (responsive, fast, nice looking)web applications quickly. For the main searching Apache Lucene will be used (must be identical tothe version used for indexing).

507

The basic components of the PD Publisher are:

508
509
510
511
512

•
•
•
•
•

A REST based search interface as described in chapter 7.1
A public web page for the simple search
A public web page for the extended search
A public web page with the most recently added participants
A secure web site to see the log and audit entries

513
514
515
516
517

9.2 SMP-PD interface

518
519

The Open Source phoss SMP (https://github.com/phax/phoss-smp) and other commercial SMP
implementations already support the Business Card API.

520
521
522

The CEF SMP server (https://ec.europa.eu/cefdigital/wiki/display/CEFDIGITAL/SMP) cannot be used
for Peppol because it only supports the OASIS BDXR SMP 1.0 interface and it does not support therequired Business Card interface.

The PD software suite should ship with a library that can be used to trigger the indexing in the PD
Indexer. SMP software providers can use this library to simplify the process of integrating theirsoftware with the PD as they just need to call this when relevant information changes (newparticipant, Business Card update, participant deletion).

20/23