Problem
The current Specification Template states that every Service API endpoint listed in a Building Block specification must be implemented and that all APIs must be defined using OpenAPI.
This assumes a single mandatory synchronous HTTP API surface. Some Building Blocks expose optional capabilities and also rely on protocol-specific standards such as AsyncAPI, OpenID Connect, OID4VCI/OID4VP, SDMX, and OGC APIs.
The Digital Registries rewrite demonstrates the issue clearly. A conformant registry should select the API families applicable to its role rather than being required to implement every possible family. This is not unique to Registries and is likely relevant to Identity, Wallet, Messaging, Payments, and future Building Blocks.
Requested changes
1. Core and Optional Key Functionalities
Allow a Building Block specification to designate Key Functionalities as either Core or Optional.
2. Conditional applicability
Clarify that:
- Global requirements apply to every conformant implementation.
- A REQUIRED requirement linked exclusively to an Optional Key Functionality becomes mandatory when an implementation claims that functionality.
- An unselected Optional Key Functionality imposes no requirements.
This should preserve the existing requirement-level classifiers while making applicability explicit.
3. Conformance profiles
Define a conformance profile as a declared combination of Key Functionalities, sub-capabilities, and protocol bindings.
An implementation should be able to declare the profiles or capabilities it supports. A specification may define named profiles without requiring every implementation to support every profile.
4. Service interface requirements
Clarify that every endpoint or protocol operation belonging to a claimed capability must be implemented. Endpoints belonging only to unclaimed Optional Key Functionalities should not be mandatory.
5. Contract formats and protocol bindings
Generalize the current OpenAPI-only rule:
- OpenAPI for synchronous HTTP APIs.
- AsyncAPI for event-driven interfaces.
- Protocol-native specifications and conformance mechanisms for standards such as OpenID Connect, OID4VCI/OID4VP, SDMX, and OGC.
- Every interface remains documented, discoverable, traceable to Functional Requirements, and testable.
Suggested wording
A Building Block specification may define Core and Optional Key Functionalities. Global REQUIRED requirements apply to every conformant implementation. Requirements linked exclusively to an Optional Key Functionality apply when an implementation claims support for that functionality.
Service interfaces must use an appropriate machine-readable contract or recognized protocol specification. OpenAPI shall be used for synchronous HTTP APIs, AsyncAPI for event-driven interfaces where applicable, and protocol-native specifications may be used when the interface conforms to an established standard with defined discovery and conformance mechanisms.
Acceptance criteria
Motivation from Digital Registries
The proposed Digital Registries model consists of a mandatory Registry Core plus one or more optional API families, including Consultation, Write, Notification, Evidence, Aggregated Data, Access Transparency, Provisioning, and Identity Federation. Each claimed family needs normative requirements and conformance tests, but requiring all families would undermine the domain-agnostic purpose of the Building Block.
Problem
The current Specification Template states that every Service API endpoint listed in a Building Block specification must be implemented and that all APIs must be defined using OpenAPI.
This assumes a single mandatory synchronous HTTP API surface. Some Building Blocks expose optional capabilities and also rely on protocol-specific standards such as AsyncAPI, OpenID Connect, OID4VCI/OID4VP, SDMX, and OGC APIs.
The Digital Registries rewrite demonstrates the issue clearly. A conformant registry should select the API families applicable to its role rather than being required to implement every possible family. This is not unique to Registries and is likely relevant to Identity, Wallet, Messaging, Payments, and future Building Blocks.
Requested changes
1. Core and Optional Key Functionalities
Allow a Building Block specification to designate Key Functionalities as either Core or Optional.
2. Conditional applicability
Clarify that:
This should preserve the existing requirement-level classifiers while making applicability explicit.
3. Conformance profiles
Define a conformance profile as a declared combination of Key Functionalities, sub-capabilities, and protocol bindings.
An implementation should be able to declare the profiles or capabilities it supports. A specification may define named profiles without requiring every implementation to support every profile.
4. Service interface requirements
Clarify that every endpoint or protocol operation belonging to a claimed capability must be implemented. Endpoints belonging only to unclaimed Optional Key Functionalities should not be mandatory.
5. Contract formats and protocol bindings
Generalize the current OpenAPI-only rule:
Suggested wording
Acceptance criteria
Motivation from Digital Registries
The proposed Digital Registries model consists of a mandatory Registry Core plus one or more optional API families, including Consultation, Write, Notification, Evidence, Aggregated Data, Access Transparency, Provisioning, and Identity Federation. Each claimed family needs normative requirements and conformance tests, but requiring all families would undermine the domain-agnostic purpose of the Building Block.