Specifications - phax/peppol-cli GitHub Wiki
The normative sources for everything in this wiki, with the versions actually consulted. Facts on other pages that cite "the SML specification" or "the SMP specification" mean the versions below.
| Spec | Version / date | Notes |
|---|---|---|
| Peppol Service Metadata Locator (SML) | 1.3.0, 2025-02-06 | Discovery flow, the DNS name format, the participant hash, U-NAPTR rules, and the two SOAP management interfaces with all their operations and faults. |
| Peppol Service Metadata Publishing (SMP) | 1.4.0, 2025-02-06 | The REST read interface, resource URLs, percent encoding, HTTP status codes, the XML signature profile, and the redirect scheme. 1.4.0's change note is "Changes for mandatory TLS usage". |
| Peppol Policy for Transport Security | 1.1.0, 2020-04-20 | The TLS rules: approved CAs (Mozilla NSS list), no self-signed certificates, and an SSL Labs grade-A requirement โ from which the TLS 1.2 floor follows. Also states that TLS certificates come from third-party CAs, not from OpenPeppol. |
| Peppol Policy for use of Identifiers (PFUOI) | 4.4.0, 2025-02-06 | The authority for all three identifier types. POLICY 1 (lengths and character sets), POLICY 2 (casing โ participant values case-insensitive, document type and process values case-sensitive), POLICY 4/4a/5/6 (participant schemes, states, meta scheme, extended values), POLICY 7 (the DNS encoding, with an authoritative test vector), POLICY 16/17/20/23/23a/23b (document types, customization IDs, wildcards, abstract entries), POLICY 24/25/25a (processes), POLICY 28/28a (transport profiles). |
| OpenPeppol Service Provider Identification Scheme (SPIS) | 1.0.0, 2025-05-08 | The authoritative definition of the Seat ID and the SPID: structure, constraints, the canonical regular expression and the lexical representation. Published at https://docs.peppol.eu/edelivery/policies/. |
| Peppol PKI 2025 โ Issuing and Enrolment Process | OpenPeppol Confluence, OPMA space | The CSR-based enrolment flow verbatim: RSA 2048, AES-256-encrypted private key, SHA-256-signed CSR, empty subject (-subj "/") because the CA overrides Subject, SAN and extensions; issued certificate validity is 2 years, set by the CA. Also the Seat ID definition and the G2/G3 generation naming with their DigiCert platforms. |
| Peppol PKI 2025 โ Certificate Authorities | OpenPeppol Confluence, OPMA space | The two-tier G3 hierarchy with a separate issuing CA per role (Access Point, SMP), and the in-service dates: PROD from 2026-01-01, TEST (pilot) from 2025-07-01. |
The first two are published under CC BY-NC-ND 4.0 by OpenPeppol AISBL at https://docs.peppol.eu/edelivery/; the
PKI pages live in the OpenPeppol members area on Confluence.
The Confluence pages describe the process but not the certificate contents, so these were taken from the G3 trust
stores bundled in peppol-commons (peppol-commons/src/main/resources/truststore/2025/*.p12, password peppol) โ
authoritative, and checkable by anyone with the repository. All six CAs are SHA256withRSA with RSA-4096 keys,
valid from 2025-01-14 to 2035-01-13/14.
| Role | Production Subject DN | Test (pilot) Subject DN |
|---|---|---|
| Root | CN=PEPPOL Root CA - G3, O=OpenPEPPOL AISBL, C=BE |
CN=PEPPOL Root TEST CA - G3, OU=FOR TEST ONLY, O=OpenPEPPOL AISBL, C=BE |
| Access Point | CN=PEPPOL ACCESS POINT CA - G3, O=OpenPEPPOL AISBL, C=BE |
CN=PEPPOL ACCESS POINT TEST CA - G3, OU=FOR TEST ONLY, O=OpenPEPPOL AISBL, C=BE |
| SMP | CN=PEPPOL SERVICE METADATA PUBLISHER CA - G3, O=OpenPEPPOL AISBL, C=BE |
CN=PEPPOL SERVICE METADATA PUBLISHER TEST CA - G3, OU=FOR TEST ONLY, O=OpenPEPPOL AISBL, C=BE |
Revocation, from the CA certificate extensions: CRL http://crl.one.nl.digicert.com/PEPPOLRootCA-G3.crl, OCSP
http://ocsp.one.nl.digicert.com.
The OU=FOR TEST ONLY marker on every pilot CA is the useful operational detail: it makes a test certificate
unmistakable, so the CLI can say "this is a TEST certificate but --network is prod" instead of reporting a generic
chain failure.
Taken from the specs' own normative reference sections, so these names and versions are verified:
| Reference | Title | Relevance to peppol-cli
|
|---|---|---|
| PFUOI 4.4.0 | Peppol Policy for use of Identifiers 4.4.0 | The authority for participant, document type and process identifier formats. POLICY 7 specifies the participant hash. Both specs defer identifier format questions to it. |
| BDXL 1.0 | OASIS "Business Document Metadata Service Location Version 1.0" | The DNS-based discovery design the SML builds on. |
| RFC 4848 | "Domain-Based Application Service Location Using URIs and the Dynamic Delegation Discovery Service (DDDS)" | This is the U-NAPTR reference. It also makes the NAPTR service field case-insensitive. |
| RFC 3986 | Uniform Resource Identifier (URI): Generic Syntax | Percent encoding of identifiers in SMP URLs; URI component case sensitivity. |
| RFC 1034 / 1035 | Domain Names โ Concepts and Facilities / Implementation and Specification | The DNS layer itself. |
| RFC 6234 | US Secure Hash Algorithms | The SHA-256 used for the participant hash. |
| RFC 2119 | Key words for use in RFCs to Indicate Requirement Levels | MUST/SHOULD/MAY throughout. |
| XML-DSIG | XML Signature Syntax and Processing (Second Edition) | The SMP response signature. |
| WS-I BP 1.1, WS-I BSP 1.0 | WS-I Basic Profile / Basic Security Profile | The SML SOAP bindings must conform. |
| Spec | Needed for |
|---|---|
| Peppol PKI / certificate documentation | The CSR subject DN and required attributes. The Seat ID question is settled (it is the certificate Subject CN) and so is the CA generation naming (G2 = Config2018, G3 = Config2025, G3 being current and the only one supported). |
| Peppol Directory specification (if one exists) | The search API surface and the business card retrieval URL are now known from the phoss-directory implementation, so nothing is blocked. Still worth confirming whether an OpenPeppol specification defines the business card format and the businesscard/ SMP resource, since neither appears in Peppol SMP 1.4.0. > TODO(verify): does a published Peppol Directory / business card specification exist?
|
| Peppol Transport / AS4 profile | Only for the transport profile identifier values and the TLS requirements on AP endpoints. Not needed for any planned feature beyond reporting. |
| Peppol MLS specification | Only the specification's exact name and version are still open โ the scope question is settled (parse and validate, no generation; see Open Questions #4). |
| Peppol Business Message Envelope 2.0 | The envelope constraints behind peppol sbdh parse. PeppolSBDHData states in its own documentation that it maps to this specification's requirements, and PeppolSBDHDataReader enforces them, so nothing is blocked โ but the document itself has not been read for this wiki. Note the XSD bundled in peppol-sbdh for the binary and text payload wrappers is the older PEPPOL-EDN-Business-Message-Envelope-1.2-2019-02-01.xsd; the two version numbers are not a contradiction, they cover different things. |
Where a specification leaves something open, the answer was taken from the implementation and is labelled as such โ an implementation detail, not a guarantee.
| Question | Answer | Source |
|---|---|---|
Does a DeleteList() containing an unknown identifier delete the valid ones? |
No โ the whole batch is rejected and nothing is removed. Validation completes before the deletion loop, and the service method is @Transactional (rollbackFor = Exception.class). |
BDMSL ManageParticipantIdentifierBusinessImpl.deleteParticipantList
|
| Does the phoss-SMP import support a dry run? | Yes, from 8.6.1: query parameter dry-run (default false), alongside overwrite-existing. The result echoes dryRun into importResult/settings. An older server ignores the parameter and performs a real import, so the echoed attribute must be verified rather than trusted. |
phoss-SMP APIExecutorImportXMLVer1, ServiceGroupImport.importXMLVer10
|
| What does the phoss-SMP XML import return on partial failure? | A per-participant result: importResult with one action element per item (errorLevel, participantID, message, optional exception) plus a summary of counts per error level. The format depends on the server version: before 8.6.1 always XML, since 8.6.1 whatever the request's Accept header selects, with XML for anything that is not application/json โ including */*, an absent header and an unmatched value, which deliberately yields XML rather than a 406 because the import has already run. The two shapes carry the same fields; only the error-level counts differ, <errorlevel> elements against an errorlevels array. |
phoss-SMP APIExecutorImportXMLVer1 (isResponseAsXML (String)), ImportActionItem
|
What does Redirect/CertificateUID hold? |
The X.509 Certificate Subject X.500 Name (subject DN) of the destination SMP's signing certificate, by agreement. The schema documentation's phrase "Subject Unique Identifier" misleadingly suggests the X.509 subjectUniqueID field, which is deprecated and unused. |
peppol-smp-types-v1-ext.xsd plus project agreement |
| Does the resulting fault identify which identifiers were unknown? | The interface contract says no; BDMSL's fault message does name them. Surface the message verbatim, never parse it. | same |
Worth recording, because "we could not find it" and "it does not exist" are different statements and only the second one closes a question.
-
There is no OpenPeppol specification for the SMP write API. Peppol SMP 1.4.0 ยง3 says so for itself ("does not
specify interfaces for creating, updating, deleting and managing Service Metadata"), and no separate document
standardises one. The write API
peppol-smp-clientspeaks is the phoss-SMP one, which is why those commands live in their ownphoss-smparea โ see ADR context and the Feature Catalogue. -
SML 1.3.0 defines no certificate-change operation, and BDMSL supplies one anyway. The specification has nothing for rotating an SMP's own certificate; BDMSL's
BDMSLServiceexposesmanageChangeCertificate(ActionofUPSERT/READ/DELETE/ACTIVATE, optionalCertificateandMigrationDate, returning aStatusstring), authenticated as the current certificate so an SMP operator can roll their own. Its predecessorprepareChangeCertificateis deprecated for removal. The CLI adopts it as an explicitly labelled extension โ see the SML section. -
BDMSL exposes no SMP listing operation. Checked across all three non-spec services:
BDMSLService,BDMSLAdminService(SML-operator administration only) andBDMSLMonitoringService(isAliveonly). So "list the SMPs in the SML" cannot be done at all, by specification or by extension. - The Peppol Policy for Transport Security states no minimum TLS version. It mandates an SSL Labs grade of at least A, from which TLS 1.2 follows, rather than naming a version.
Verified from both specs; useful when the CLI has to produce or read these documents.
| Prefix | Namespace URI | From |
|---|---|---|
ids |
http://busdox.org/transport/identifiers/1.0/ |
both |
lrs |
http://busdox.org/serviceMetadata/locator/1.0/ |
SML |
smp |
http://busdox.org/serviceMetadata/publishing/1.0/ |
SMP โ also the identifier for the SMP REST binding version 1.x |
ds |
http://www.w3.org/2000/09/xmldsig# |
SMP |
wsa |
http://www.w3.org/2005/08/addressing |
SMP (endpoint references) |