Skip to content

Commit c364509

Browse files
SaramandusSaramandus
authored
Merge pull request #143 from webuild-consortium/cs-template
WBCS template
2 parents 154ecee + 29da407 commit c364509

2 files changed

Lines changed: 238 additions & 19 deletions

File tree

‎conformance-specs/README.md‎

Lines changed: 43 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,64 @@
1-
<h1 align="center">
2-
Conformance Specifications (CS)
3-
</h1>
4-
5-
<p align="center">
6-
<a href="#about">About</a> •
7-
<a href="#contributing">Contributing</a> •
8-
<a href="#approved-css">Approved CSs</a> •
9-
<a href="#licensing">Licensing</a>
10-
</p>
1+
# WE BUILD Conformance Specifications (WBCS)
112

123
## About
13-
The Conformance Specifications define how WE BUILD participants implement wallet interfaces and communication protocols between issuers, wallets, and relying parties (RPs).
4+
The WE BUILD Conformance Specifications (WBCS) define how WE BUILD participants implement wallet interfaces and communication protocols between issuers, wallets, and relying parties.
145
They ensure interoperability and conformance by translating ADR decisions into precise implementation requirements.
156

16-
The ITB will be based on the CS as a starting point. The test suites in the ITB are relying predominantly on the CS.
7+
The ITB will be based on the WBCS as a starting point. The test suites in the ITB are relying predominantly on the WBCS.
178

189
## Contributing
1910

20-
The Architecture group define the CS, with help from all implementing participants (wallets, issuers and verifiers). For members of the consortium, find more information on the CS processes are held on [open social - Architecture Group](https://portal.webuildconsortium.eu/group/architecture).
11+
The Architecture group define the WBCS, with help from all implementing participants. Propose new WBCSs using the [template](_template.md).
2112

2213
## CS Process Summary for WE BUILD Large Scale Pilots (LSPs)
2314

24-
Conformance Specifications (CS) progress through the following process towards the Large Scale Pilots (LSPs):
15+
```mermaid
16+
---
17+
config:
18+
flowchart:
19+
defaultRenderer: 'elk'
20+
subGraphTitleMargin:
21+
bottom: 25
22+
---
23+
24+
graph TB
25+
%% flowchart
26+
27+
subgraph "WP4 (Architecture)"
28+
Proposal -- Discuss --> Review
29+
Review -- Rejected --> Proposal
30+
Review -- Approved --> WBCS
31+
end
32+
33+
subgraph "Participants from WP2, WP3 and WP4"
34+
Implementations["Implementations
35+
(wallets, issuers, verifiers)"]
36+
end
2537
26-
![CS Process and Roles](https://github.com/webuild-consortium/wp4-architecture/blob/main/images/WPRoles.png)
38+
subgraph "Testing Group"
39+
ITB["ITB"]
40+
end
2741
28-
### Approved CSs
42+
WBCS -- "Guiding" --> Implementations
43+
WBCS -- "Configure" --> ITB
44+
Implementations -- "Test" --> ITB
2945
30-
| **CS #** | **CS Title** |
46+
Anyone -- "Create/adapt" --> Proposal
47+
SpecEfforts["Specification efforts"] -- "New wallet interface definitions" --> WBCS
48+
TestDev["Test development"] -- "New version test cases" --> ITB
49+
```
50+
51+
### Approved WBCSs
52+
53+
| **WBCS #** | **WBCS Title** |
3154
| -------- | ------------------------------------------------------------------------------------ |
3255
| CS-001 | [Credential Issuance - v1.0](cs-01-credential-issuance.md) |
3356
| CS-002 | [Credential Presentation - v1.0](cs-02-credential-presentation.md) |
3457
| |
35-
### CSs Under Development
3658

37-
| **CS #** | **CS Title** |
59+
### WBCSs Under Development
60+
61+
| **WBCS #** | **WBCS Title** |
3862
| -------- | ------------ |
3963
| | |
4064

‎conformance-specs/_template.md‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
# WE BUILD - Conformance Specification: <TITLE>
2+
3+
Version <VERSION>
4+
5+
## Table of Contents
6+
7+
- [1. Introduction](#1-introduction)
8+
- [2. Scope](#2-scope)
9+
- [3. Normative Language](#3-normative-language)
10+
- [4. Roles and Components](#4-roles-and-components)
11+
- [5. Protocol Overview](#5-protocol-overview)
12+
- [6. High-level Flows](#6-high-level-flows)
13+
- [7. Normative Requirements](#7-normative-requirements)
14+
- [8. Interface Definitions](#8-interface-definitions)
15+
- [9. Conformance](#9-conformance)
16+
- [References](#references)
17+
18+
# 1. Introduction
19+
20+
This document defines the **WE BUILD Conformance Specification for <TITLE>**.
21+
22+
Its purpose is to describe how relevant actors within the WE BUILD ecosystem are expected to interoperate in a consistent and testable way.
23+
24+
This specification should:
25+
26+
- identify the relevant protocol or functional area
27+
- clarify which actors are involved
28+
- define the main requirements needed for interoperability
29+
- support implementation and conformance testing
30+
31+
This specification is based on <BASE STANDARD / PROFILE / ADR> and should be read together with other applicable WE BUILD specifications where relevant.
32+
33+
# 2. Scope
34+
35+
This specification defines the conformance expectations for <DOMAIN / CAPABILITY>.
36+
37+
It should make clear:
38+
39+
- what this specification covers
40+
- which roles are in scope
41+
- which capabilities are required
42+
- what is out of scope
43+
44+
Out-of-scope items should be listed where needed, especially if they are handled by other WE BUILD documents or external specifications.
45+
46+
# 3. Normative Language
47+
48+
The keywords **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **MAY**, and **OPTIONAL** are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).
49+
50+
These keywords indicate the strength of requirements for conforming implementations.
51+
52+
# 4. Roles and Components
53+
54+
This section identifies the roles and components relevant to this specification.
55+
56+
Only roles that matter for this specification should be included.
57+
58+
Examples may include:
59+
60+
- **Wallet Unit (WU):** software acting on behalf of the Holder
61+
- **Holder:** person or organisation controlling the Wallet Unit
62+
- **Issuer:** entity issuing credentials or attestations
63+
- **Verifier:** entity requesting and validating presentations
64+
- **Authorisation Server:** component supporting OAuth / OpenID interactions
65+
- **Trust Provider:** component or service publishing trust-related information
66+
67+
# 5. Protocol Overview
68+
69+
This section gives a short explanation of how the protocol or function works at a high level.
70+
71+
It should help the reader understand:
72+
73+
- which standards or mechanisms are used
74+
- how the main actors interact
75+
- which security or trust features are important
76+
- what the overall outcome of the interaction is
77+
78+
This section should stay concise. Detailed behaviour belongs in later sections.
79+
80+
# 6. High-level Flows
81+
82+
This section describes the main interaction flows between actors.
83+
84+
Flows should be written as step-by-step sequences that help implementers understand how the protocol operates.
85+
86+
Example subsections:
87+
88+
## 6.1 <Flow Name>
89+
90+
Describe:
91+
92+
- participating actors
93+
- how the interaction begins
94+
- the main sequence of actions
95+
- the expected outcome
96+
97+
Example:
98+
99+
1. <STEP 1>
100+
2. <STEP 2>
101+
3. <STEP 3>
102+
103+
# 7. Normative Requirements
104+
105+
This section defines the normative requirements for implementations.
106+
107+
Requirements may be grouped in the way that best fits the specification, for example by:
108+
109+
- role
110+
- component
111+
- capability
112+
- protocol step
113+
114+
Example structure:
115+
116+
## 7.1 <Role or Component>
117+
118+
<ROLE OR COMPONENT> **MUST**:
119+
120+
1. <REQUIREMENT 1>
121+
2. <REQUIREMENT 2>
122+
123+
<ROLE OR COMPONENT> **SHOULD**:
124+
125+
1. <RECOMMENDATION 1>
126+
127+
<ROLE OR COMPONENT> **MUST NOT**:
128+
129+
1. <PROHIBITED BEHAVIOUR>
130+
131+
# 8. Interface Definitions
132+
133+
This section describes the technical interfaces used by the protocol.
134+
135+
Examples may include:
136+
137+
- HTTP endpoints
138+
- wallet invocation URLs
139+
- metadata endpoints
140+
- credential request structures
141+
- presentation responses
142+
- trust registry queries
143+
144+
For each interface, describe:
145+
146+
- direction of communication
147+
- transport method
148+
- request parameters
149+
- response structure
150+
151+
Example subsection:
152+
153+
## 8.1 <Interface Name>
154+
155+
*Direction:* <SENDER> → <RECEIVER>
156+
*Method:* <HTTP METHOD>
157+
158+
**Request**
159+
160+
- <FIELD 1>
161+
- <FIELD 2>
162+
163+
**Response**
164+
165+
- <FIELD 1>
166+
- <FIELD 2>
167+
168+
Example (illustrative only):
169+
170+
```text
171+
<EXAMPLE REQUEST OR URL>
172+
```
173+
# 9. Conformance
174+
175+
An implementation **conforms to this specification** if it implements the requirements defined in this document for its role and supports the relevant interfaces and flows.
176+
177+
Where relevant, conformance may be stated separately for each role.
178+
179+
**Example**
180+
181+
An implementation conforms as a **<ROLE 1 CONFORMANCE CLASS>** if it:
182+
183+
1. implements the applicable requirements in Section 7
184+
2. supports the relevant interfaces and flows in Sections 6 and 8
185+
3. supports any required standards or formats referenced by this specification
186+
187+
Additional WE BUILD profiles may define stricter requirements for specific use cases. Such profiles **MUST NOT** weaken the mandatory requirements in this specification.
188+
189+
# References
190+
191+
[1] <ORGANISATION> (<YEAR>) <TITLE>. Available at: <URL> (Accessed: <DATE>).
192+
193+
[2] <ORGANISATION> (<YEAR>) <TITLE>. Available at: <URL> (Accessed: <DATE>).
194+
195+
[3] <ORGANISATION> (<YEAR>) <TITLE>. Available at: <URL> (Accessed: <DATE>).

0 commit comments

Comments
 (0)