How to read review_Reading by phases#1109
Conversation
Intervento relativo all'introduzione relativo alla parte sui percorsi di lettura
📢 Documentation Preview 🔍This PR comes from a forked repository, so the documentation preview was not automatically generated.
|
📢 Documentation Preview 🔍This PR comes from a forked repository, so the documentation preview was not automatically generated.
|
📢 Documentation Preview 🔍This PR comes from a forked repository, so the documentation preview was not automatically generated.
|
📢 Documentation Preview 🔍This PR comes from a forked repository, so the documentation preview was not automatically generated.
|
Added role-based reading paths and clarified section references for each role in the IT-Wallet system. Updated references for better clarity and consistency throughout the document.
📢 Documentation Preview 🔍This PR comes from a forked repository, so the documentation preview was not automatically generated.
|
📢 Documentation Preview 🔍This PR comes from a forked repository, so the documentation preview was not automatically generated.
|
entities > authentic-sources
📢 Documentation Preview 🔍This PR comes from a forked repository, so the documentation preview was not automatically generated.
|
📢 Documentation Preview 🔍This PR comes from a forked repository, so the documentation preview was not automatically generated.
|
📢 Documentation Preview 🔍This PR comes from a forked repository, so the documentation preview was not automatically generated.
|
📢 Documentation Preview 🔍This PR comes from a forked repository, so the documentation preview was not automatically generated.
|
📢 Documentation Preview 🔍This PR comes from a forked repository, so the documentation preview was not automatically generated.
|
📢 Documentation Preview 🔍This PR comes from a forked repository, so the documentation preview was not automatically generated.
|
There was a problem hiding this comment.
Pull request overview
This PR restructures the “How to read the specification” documentation to provide guided reading paths organized by role and (new) project phases, in both Italian and English.
Changes:
- Reworks the reading-path section into a “reading by project phase” structure across the main ecosystem roles.
- Expands role descriptions with phase-specific objectives and direct section references.
- Adds/updates corresponding content in both
docs/it/anddocs/en/versions.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 14 comments.
| File | Description |
|---|---|
| docs/it/how-to-read-spec.rst | Replaces the previous role/journey block with a phase-based reading guide for each role (AS/WP/CI/RP). |
| docs/en/how-to-read-spec.rst | Introduces a similar phase-based structure in English, adding a new “Role based reading” section and expanding role guidance. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| **Obiettivo**: implementare gli endpoint per la comunicazione e adottare gli standard tecnologici (es. SD-JWT) che assicurano al Wallet di interfacciarsi con gli altri attori. | ||
|
|
||
| - **Sezione** ref:`endpoints:Endpoints`: per implementare correttamente le interfacce (API) del Wallet Provider necessarie all'interoperabilità del sistema (riferimento al paragrafo ref:`endpoints:Endpoint del Fornitore di Wallet`). |
|
|
||
| - **Sezione** :ref:`functionalities:Design dell'Esperienza Utente`: per progettare interfacce semplici e sicure garantendo che l’esperienza utente sia immediata e intuitiva. | ||
|
|
||
| - **Sezione** :ref:`entities:Entità`: per conoscere i requisiti di implementazione e gli attributi necessari per configurare la propria entità (riferimento al paragrafo :ref:`Soluzione Wallet`). |
|
|
||
| - **Sezione** :ref:`functionalities:Design dell'Esperienza Utente`: per conoscere i requisiti funzionali di alto livello a supporto dell’Esperienza Utente in tutte le fasi di interazione tra l’Utente e il servizio. | ||
|
|
||
| - **Sezione** :ref:`entities:Entità`: per conoscere i requisiti di implementazione e gli attributi necessari per configurare il proprio profilo di Issuer (riferimento ai paragrafi :ref:`Soluzione del Fornitore di Attestati Elettronici` e :ref:`aFonti Autentiche`). |
| - **Sezione** ref:`digital-credential-flows:Flussi relativi agli attestati elettronici`: per conoscere le specifiche di dettaglio per implementare i flussi di emissione, le modalità di presentazione dell’attestato elettronico e il flusso di recupero delle informazioni del wallet. | ||
|
|
||
| - **Sezione** ref:`endpoints:Endpoints`: per implementare correttamente le interfacce (API) di emissione, in particolare il Credential Endpoint e il Token Endpoint (riferimento al paragrafo ref:`endpoints:Endpoint del Credential Issuer`). |
| - **Sezione** ref:`digital-credential-flows:Flussi relativi agli attestati elettronici`: per l’implementazione del flusso di presentazione sia per scenari remoti che di prossimità (ref:`credential-presentation:12.2`. | ||
|
|
||
| * **Sezione** :ref:`wallet-solution:Soluzione Wallet`: Comprensione delle interazioni dell'Istanza del Wallet e dei protocolli di presentazione. | ||
| * **Sezione** :ref:`mobile-application-instance:Istanza dell'Applicazione Mobile`: Modelli di implementazione specifici per dispositivi mobili. | ||
| - **Sezione** ref:`endpoints:Endpoints`: per implementare correttamente le interfacce di ricezione e verifica dei dati (riferimento ai paragrafi ref:`relying-party-endpoints:Endpoint della Relying Party` e ref:`relying-party-endpoints:Endpoint del Backend del Provider di Relying Party`). |
|
|
||
| - **Section** :ref:`x5c-evaluation:X.509 Certificate Management Operations': Operational procedures for managing X.509 Certificates within the IT-Wallet federation | ||
|
|
||
| - **Section**: :ref:`est-plans:Test Plans': Information on how test environments support implementers, auditors, and compliance testing in validating Wallet Solution behavior. |
| ****Objective**: To technically design attestations by structuring metadata to meet technical and regulatory requirements, allowing the user to share only necessary information. | ||
|
|
||
| - **Section** :ref:`functionalities:User Experience Design`: For high-level functional requirements supporting the User Experience during all interaction phases. | ||
|
|
||
| - **Section** :ref:`entities:Entities`: Implementation requirements and attributes for configuring the Issuer profile (see paragraphs :ref:`entities:Credential Issuer Solution', and :ref:`entities:Authentic Sources') | ||
|
|
||
| - **Section** :ref:`digital-credential-management:Digital Credential Management`: Technical requirements for designing and managing the lifecycle of attestations. | ||
|
|
||
| - **Section** :ref:`algorithms:Cryptographic Algorithms': To meet security requirements by designing digital signature systems that make attestations unfalsifiable. | ||
|
|
||
| **Phase 3: Implementation** | ||
|
|
||
| **Objective**: To develop issuing endpoints based on the OpenID4VCI protocol, implementing release, renewal, and technical lifecycle management functions. | ||
|
|
||
| - **Section** ref:`digital-credential-flows:`Digital Credential Flows': Detailed specifications on implementing issuance flows, presentation methods, and wallet information retrieval. | ||
|
|
||
| - **Section** :ref:`endpoints:Endpoints`: Implementation of issuance interfaces, including the Credential Endpoint and Token Endpoint (see paragraph :ref:`endpoints:`Credential Issuer Endpoints'). |
|
|
||
| **Objective**: To develop issuing endpoints based on the OpenID4VCI protocol, implementing release, renewal, and technical lifecycle management functions. | ||
|
|
||
| - **Section** ref:`digital-credential-flows:`Digital Credential Flows': Detailed specifications on implementing issuance flows, presentation methods, and wallet information retrieval. |
| - **Section** :ref:`onboarding-high-level:Onboarding System': learning the methods for participating in the IT-Wallet ecosystem (see paragraph :ref:`ronboarding-high-level:Relying Party Operator Journey'). | ||
|
|
||
| **Testing and Validation:** | ||
| Section :ref:`test-plans:Test Plans` provides a comprehensive test matrix for validating implementations across different roles and interaction flows. | ||
| - **Section** :ref:`x5c-evaluation:X.509 Certificate Management Operations': Operational procedures for managing X.509 Certificates within the IT-Wallet federation | ||
|
|
||
| Implementation Approach | ||
| ^^^^^^^^^^^^^^^^^^^^^^^ | ||
| - **Section**: :ref:`est-plans:Test Plans': Information on how test environments support implementers, auditors, and compliance testing in validating Wallet Solution behavior. |
| NOTE | ||
|
|
||
| 1. **Foundation Phase**: Read Sections :ref:`introduction:Introduction`, :ref:`architecture-overview:Architecture Overview`, :ref:`brand-identity:Brand Identity`, and :ref:`trust-infrastructure:The Infrastructure of Trust` to establish conceptual understanding of the IT-Wallet paradigm, Brand Identity elements and trust infrastructure. | ||
| 2. **Role-Specific Phase**: Focus on primary role's essential sections to understand specific User Experience, functional and implementation requirements, main technical component, the general architecture and interaction flows (see Section :ref:`functionalities:User Experience Design`, :ref:`entities:Entities` and Section :ref:`endpoints:Endpoints` for more details). | ||
| 3. **Integration Phase**: Review secondary sections relevant to interactions with other ecosystem participants and platform integration requirements. | ||
| 4. **Validation Phase**: Study security considerations, testing guidance, and compliance requirements according to Sections :ref:`security-privacy-considerations:Security and Privacy Considerations`, :ref:`log-retention-policy:General Log Retention Policies`, and :ref:`test-plans:Test Plans` for additional information. | ||
| For implementers working on solutions that cover multiple roles (e.g., a combination of Credential Provider Solutions and Relying Parties), it is recommended to review the sections for all relevant roles before proceeding with development. It is important to pay particular attention to Entity Configuration requirements and to federation flows that apply across multiple roles. |
Title
Content
Review