20.3. PDND e-Service Template

La PDND fornisce uno strumento specializzato che migliora i processi di co-progettazione delle API ottimizzando la pubblicazione e il riutilizzo dei servizi elettronici. Questa funzionalità è definita e regolamentata nel presente documento.

  • "Linee Guida sull'infrastruttura tecnologica della Piattaforma Digitale Nazionale Dati per l'interoperabilità dei sistemi informativi e delle basi di dati" (PDND).

Il template del servizio elettronico serve come modello standardizzato contenente tutti i metadati tecnici e descrittivi necessari per un servizio elettronico. I Gestori delle API, che possono essere sia Fornitori che Consumatori all'interno dell'ecosistema PDND, POSSONO creare e mantenere questi template.

Una volta che un e-service template è pubblicato, è accessibile attraverso il Catalogo Template PDND che è un repository centralizzato che facilita il riutilizzo. Questo catalogo consente a qualsiasi Partecipante PDND autorizzato di sfogliare i template disponibili e istanziare nuovi servizi elettronici basati su progetti esistenti.

20.3.1. Definizione e linee guida dell'e-service template PDND

L'infrastruttura PDND supporta la gestione del ciclo di vita dei Servizi Elettronici Template, simile a quella dei servizi elettronici tradizionali. Gli stati del ciclo di vita includono: Draft, Active, Supsended e Deprecated. Come per i servizi elettronici tradizionali, PDND applica il controllo degli accessi basato sui ruoli per governare le transizioni di stato.

20.3.1.1. Gestione dei Servizi Elettronici Template

20.3.1.1.1. Creazione del Servizio Elettronico Template

I Partecipanti sono abilitati a creare Servizi Elettronici Template tramite una procedura guidata accessibile attraverso l'interfaccia web PDND (le API saranno disponibili in futuro). Il flusso di lavoro di creazione rispecchia da vicino quello della creazione standard di servizi elettronici, con le seguenti distinzioni:

  • Un campo aggiuntivo identifica il destinatario previsto del template.

  • Il campo "Audience" è omesso.

  • Le soglie sono opzionali e servono come raccomandazioni per i Partecipanti che implementano il template.

Ai Partecipanti è vietato creare più template con lo stesso nome: i nomi dei template DEVONO essere unici per partecipante. Alla creazione, un template è inizialmente impostato sullo stato Draft. I template possono quindi essere pubblicati nel Catalogo Template, rendendoli così accessibili a tutti i Partecipanti.

20.3.1.1.2. Modifica del Servizio Elettronico Template

I Partecipanti che hanno creato un template possono modificarlo. La portata dei campi modificabili dipende dallo stato del ciclo di vita del template:

  • Se il template è in stato Draft, tutti i campi sono modificabili.

  • Per i template in altri stati, solo un sottoinsieme limitato di campi può essere modificato direttamente.

  • I campi che non possono essere modificati nei template pubblicati richiedono la creazione di una nuova versione del template per applicare le modifiche.

Il versionamento dei template funziona in modo simile a quello dei servizi elettronici, dato che le modifiche al modello possono impattare i servizi istanziati e quindi i Partecipanti che consumano quell'istanza.

I seguenti campi possono essere modificati senza attivare una nuova versione del template:

  • Name

  • Intended Recipient

  • Description

  • Voucher Time Limit

  • Documentation (escludendo la specifica OpenAPI)

  • Attributes

20.3.1.1.3. Sospensione del e-service Template

I template, come i servizi elettronici, possono essere Sospesi. Quando sospesi:

  • Il template viene rimosso dal catalogo pubblico dei template.

  • L'istanziazione di nuove istanze dal template sospeso è disabilitata.

  • Le istanze precedentemente istanziate rimangono inalterate.

  • I template possono essere riattivati in qualsiasi momento.

  • I template non possono essere eliminati.

20.3.1.1.4. Istanziazione del e-service Template

I Partecipanti possono istanziare un Servizio Elettronico Template sfogliando il Catalogo Template e selezionando un template. Questo processo genera un nuovo servizio elettronico.

I vincoli di istanziazione includono:

  • Solo i template in stato Attivo sono idonei per l'istanziazione.

  • L'istanziazione è facilitata attraverso una procedura guidata nell'interfaccia web PDND.

  • A causa dell'obiettivo di standardizzazione dei template, la maggior parte dei campi è pre-compilata e immutabile durante l'istanziazione.

  • Le seguenti informazioni non possono essere modificate durante l'istanziazione:

    • Caricamento della documentazione

    • Tempo di scadenza del token

    • Nome, descrizione e attributi

Invece, i seguenti campi devono essere specificati durante l'istanziazione:

  • Audience

  • Thresholds

  • Automatic/Manual Approval Policy

Inoltre, sebbene la specifica OpenAPI sia fissa, i seguenti campi di metadati possono essere forniti in modo che PDND possa aggiornare automaticamente la specifica YAML:

  • Contatti (nome, email, URL, URL Termini e Condizioni)

  • URL del server

Ogni servizio elettronico istanziato mantiene un ciclo di vita indipendente analogo ai servizi elettronici standard.

20.3.1.2. Gestione delle Versioni

Il versioning dei template segue un processo controllato:

  • La pubblicazione di una nuova versione del template la imposta su Active.

  • La versione precedentemente Active viene automaticamente trasferita a Deprecated.

  • È consentita solo una versione Active per template in qualsiasi momento.

  • I template possono anche avere una singola versione Draft che coesiste con la versione Active.

Le istanze derivate dai template mantengono un versioning indipendente poiché i Partecipanti possono aggiornare i campi specifici dell'istanza (ad esempio, URL del server) più volte, mentre l'istanza rimane collegata alla versione del template di origine.

Di conseguenza, le versioni dei template e le versioni delle istanze sono indipendenti e non direttamente correlate.

I Partecipanti che istanziano un template possono quindi aggiornare sia l'istanza specifica o, se disponibile, aggiornare a una versione più recente del template.

20.3.1.3. Template per Fonte Autentica

La funzionalità del servizio elettronico template viene utilizzata per standardizzare la trasmissione dei dati dalle Fonti Autentiche ai Fornitori di Attestati Elettronici. Il servizio elettronico template DOVREBBE essere pubblicato all'interno della PDND dal Fornitore di Attestati Elettronici ed è accessibile attraverso il Catalogo Template PDND.

20.3.1.3.1. Parametri del Template per Fonte Autentica

Il servizio elettronico template DEVE rispettare le seguenti proprietà:

  • Name: IT Wallet - Fonte Autentica - <Nome dell'Attestato Elettronico>

  • Intended Recipients: IT Wallet - Fonte Autentica - <Dominio della Fonte Autentica>

  • Description: Descrizioni utili al Fornitore di Attestati Elettronici in relazione al nuovo attestato elettronico <Nome dell'Attestato Elettronico>

  • Technology: REST

  • Data variation via Signal Hub: True

  • Version changelog: Servizio elettronico Fonte Autentica tramite implementazione template

  • Voucher Time Limit: 20

  • Suggest custom threshold: False

  • Suggest manual agreement approval policy: False

  • Attributes: <Nome ufficiale dell'Ente Pubblico Fornitore di Attestati Elettronici>

20.3.1.3.2. Istanziazione del Template per Fonte Autentica

Ogni Fonte Autentica DOVREBBE istanziare il servizio elettronico template IT Wallet - Fonte Autentica nella PDND. Il processo di istanziazione risulterà in un nuovo servizio elettronico che DEVE soddisfare i seguenti requisiti:

  • Signal Hub: True

  • Politica di approvazione manuale: False

  • Soglia giornaliera chiamate API per ogni fornitore: maggiore di 10000

  • Soglia giornaliera chiamate API: maggiore di 10000

Informazioni aggiuntive richieste durante il processo di creazione sono dipendenti dal fornitore.

20.3.1.3.3. Specifica OpenAPI della Fonte Autentica PDND

Di seguito è riportata la specifica OpenAPI completa per i servizi elettronici della Fonte Autentica PDND:

  1openapi: 3.0.1
  2info:
  3  title: IT Wallet API - AS web services
  4  version: 0.2.0
  5  description: |
  6    # IT Wallet Authentic Source e-Service exposed via PDND.
  7    ### ModI patterns to be used:
  8      - <b>ID_AUTH_CHANNEL_01</b>: Direct Trust TLS (HTTPS)
  9      - <b>ID_AUTH_REST_01</b>: Authorization via PDND token
 10      - <b>INTEGRITY_REST_02</b>: Requests and responses are signed
 11      - <b>AUDIT_REST_02</b>: Additional properties (the pattern is optional if DPoP Token is used)
 12      - <b>DPoP Token</b>: Used as an alternative to a Bearer Token (optional)
 13  termsOfService: "https://authentic-source.example.it/tos/"
 14  contact:
 15    name: IT-Wallet <credential_name> <credential_provider>
 16    url: https://github.com/italia/eid-wallet-it-docs
 17  x-api-id: ASITW-01
 18  x-summary: IT-Wallet Authentic Source API.
 19servers:
 20  - url: https://test.authentic-source.example.it/v0.2.0
 21    description: Authentic Source API test server
 22  - url: https://authentic-source.example.it/v0.2.0
 23    description: Authentic Source API production server
 24security:
 25  - BearerAuth: []
 26  - DPoPAuth: []
 27paths:
 28  /status:
 29    get:
 30      tags:
 31        - status
 32      summary: Get Authentic Source API status.
 33      description: Health-check endpoint that returns the operational status of the Authentic Source API.
 34      operationId: authenticSourceStatus
 35      parameters:
 36        - name: DPoP
 37          in: header
 38          description: Use only if the DPoP voucher has been requested from PDND.
 39          schema:
 40            type: string
 41            format: JWT
 42          required: false
 43      responses:
 44        "200":
 45          description: Service available
 46          content:
 47            application/problem+json:
 48              schema:
 49                $ref: "#/components/schemas/ProblemDetails"
 50          headers:
 51            Cache-Control:
 52              $ref: "#/components/headers/CacheControlHeader"
 53            X-RateLimit-Limit:
 54              $ref: "#/components/headers/RateLimitLimitHeader"
 55            X-RateLimit-Remaining:
 56              $ref: "#/components/headers/RateLimitRemainingHeader"
 57            X-RateLimit-Reset:
 58              $ref: "#/components/headers/RateLimitResetHeader"
 59        "429":
 60          description: Too Many Requests
 61          content:
 62            application/problem+json:
 63              schema:
 64                $ref: "#/components/schemas/ProblemDetails"
 65          headers:
 66            # RFC 6585 defines Retry-After. X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset are not required because redundant along with Retry-After.
 67            Retry-After:
 68              $ref: "#/components/headers/RetryAfterHeader"
 69        "503":
 70          description: Service Unavailable
 71          content:
 72            application/problem+json:
 73              schema:
 74                $ref: "#/components/schemas/ProblemDetails"
 75          headers:
 76            Retry-After:
 77              $ref: "#/components/headers/RetryAfterHeader"
 78
 79  /attribute-claims/{datasetId}:
 80    post:
 81      tags:
 82        - credential
 83      summary: Get Attribute Claims
 84      description: >-
 85        This service provides the Credential Issuer with all attribute claims necessary for the issuance of a Digital Credential
 86      operationId: attributeClaims
 87      parameters:
 88        - in: path
 89          name: datasetId
 90          schema:
 91            type: string
 92          required: true
 93          description: Identifier of the dataset as registered in the Authentic Source Registry
 94        - name: DPoP
 95          in: header
 96          description: Use only if the DPoP voucher has been requested from PDND.
 97          schema:
 98            type: string
 99            format: JWT
100          required: false
101        - name: Agid-JWT-Signature
102          in: header
103          description: >-
104            JWT containing the signature of the message headers whose integrity
105            needs to be guaranteed, to comply with the INTEGRITY_REST_02
106            security pattern (see <a target="blank"
107            href="https://italia.github.io/eid-wallet-it-docs/versione-corrente/en/e-service-pdnd.html">e-Service PDND</a>). <br/><br/>
108
109            <a target="blank" href="https://jwt.io/#debugger-io?token=eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ0YzNiMmExLTk4NzYtNTQzMi0xMGZlLWRjYmE5ODc2NTQzMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJzdWIiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJhdWQiOiJodHRwczovL2F1dGhlbnRpYy1zb3VyY2UuZXhhbXBsZS5pdCIsImlhdCI6MTczMzM5Nzg0MCwibmJmIjoxNzMzNDAxNjI4LCJleHAiOjE3MzM0MDE0NDAsImp0aSI6ImQzZjdiMmM5LTI3NGEtNDJiNy04ZjhkLTJlOWQ4YjE3MzRiMCIsInNpZ25lZF9oZWFkZXJzIjpbeyJkaWdlc3QiOiJTSEEtMjU2PTcyZTE4YmRkZGYxM2M5MTFiNGRkNTYyZWUyMTk3OWE1YzlmMjM1YzNhMDFiZDE0MjZlODU3ZDhjMWEyODJmNDEifSx7ImNvbnRlbnQtdHlwZSI6ImFwcGxpY2F0aW9uL2pzb24ifV19.tG5-P96CCA6N1IYC-xk4GumoVkA3NFolpbBn2vQ2e9vpWQ8f5Sm2l4-1VrXfKTx-CUVz_puiwqkBhulrNKj2fA">EXAMPLE
110            ON JWT.IO</a>
111          required: true
112          schema:
113            type: string
114            format: JWT
115            example: eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ0YzNiMmExLTk4NzYtNTQzMi0xMGZlLWRjYmE5ODc2NTQzMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJzdWIiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJhdWQiOiJodHRwczovL2F1dGhlbnRpYy1zb3VyY2UuZXhhbXBsZS5pdCIsImlhdCI6MTczMzM5Nzg0MCwibmJmIjoxNzMzNDAxNjI4LCJleHAiOjE3MzM0MDE0NDAsImp0aSI6ImQzZjdiMmM5LTI3NGEtNDJiNy04ZjhkLTJlOWQ4YjE3MzRiMCIsInNpZ25lZF9oZWFkZXJzIjpbeyJkaWdlc3QiOiJTSEEtMjU2PTcyZTE4YmRkZGYxM2M5MTFiNGRkNTYyZWUyMTk3OWE1YzlmMjM1YzNhMDFiZDE0MjZlODU3ZDhjMWEyODJmNDEifSx7ImNvbnRlbnQtdHlwZSI6ImFwcGxpY2F0aW9uL2pzb24ifV19.tG5-P96CCA6N1IYC-xk4GumoVkA3NFolpbBn2vQ2e9vpWQ8f5Sm2l4-1VrXfKTx-CUVz_puiwqkBhulrNKj2fA
116        - name: Digest
117          in: header
118          description: >-
119            Digest of the message payload, to comply with the INTEGRITY_REST_02
120            security pattern. According to <a target="blank" href="https://www.rfc-editor.org/rfc/rfc3230.html#section-4.2">RFC
121            3230 §4.2</a>, the format MUST be the following: digest-algorithm=encoded
122            digest output.
123          required: true
124          schema:
125            type: string
126            example: SHA-256=72e18bdddf13c911b4dd562ee21979a5c9f235c3a01bd1426e857d8c1a282f41
127        - name: Agid-JWT-TrackingEvidence
128          in: header
129          description: >-
130            If the Voucher type is Bearer, this header represents a JWT acting as a proof of possession, to comply with the REST_JWS_2021_POP security
131            pattern using the POP_TPoP implementation. Otherwise, it is a JWT containing the data tracked in the Consumer's domain, to comply with AUDIT_REST_02 (see <a target="blank"
132            href="https://italia.github.io/eid-wallet-it-docs/versione-corrente/en/e-service-pdnd.html">e-Service PDND</a>). <br/><br/>
133            <a target="blank" href="https://jwt.io/#debugger-io?token=eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ0YzNiMmExLTk4NzYtNTQzMi0xMGZlLWRjYmE5ODc2NTQzMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJhdWQiOiJodHRwczovL2F1dGhlbnRpYy1zb3VyY2UuZXhhbXBsZS5pdCIsImV4cCI6MTczMzA1MjYwMCwibmJmIjoxNzMzMDM2NDUwLCJpYXQiOjE3MzMwMzY0MDAsImp0aSI6ImE0YjVjNmQ3LWU4ZjktYWJjZC1lZjEyLTM0NTY3ODkwMTIzNCIsImRub25jZSI6NjUyODQyNDIxMzY4NSwicHVycG9zZUlkIjoiYjJjM2Q0ZTUtZjZnNy1oOGk5LWowazEtbG1ubzEyMzQ1Njc4IiwidXNlcklEIjoiYThiN2M2ZDUtZTRmMy1nMmgxLWk5ajAta2xtbm9wcXJzdHV2IiwibG9hIjoic3Vic3RhbnRpYWwifQ.y42yfMeW2H9h0b0j0BODUml8yF20stY9q3BwoVU5BB90afBj852Q0QlInncdhjXhUjLS1V76cGBxkutDNvxRNA">EXAMPLE
134            ON JWT.IO</a>
135          required: false
136          schema:
137            type: string
138            format: JWT
139            example: eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ0YzNiMmExLTk4NzYtNTQzMi0xMGZlLWRjYmE5ODc2NTQzMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJhdWQiOiJodHRwczovL2F1dGhlbnRpYy1zb3VyY2UuZXhhbXBsZS5pdCIsImV4cCI6MTczMzA1MjYwMCwibmJmIjoxNzMzMDM2NDUwLCJpYXQiOjE3MzMwMzY0MDAsImp0aSI6ImE0YjVjNmQ3LWU4ZjktYWJjZC1lZjEyLTM0NTY3ODkwMTIzNCIsImRub25jZSI6NjUyODQyNDIxMzY4NSwicHVycG9zZUlkIjoiYjJjM2Q0ZTUtZjZnNy1oOGk5LWowazEtbG1ubzEyMzQ1Njc4IiwidXNlcklEIjoiYThiN2M2ZDUtZTRmMy1nMmgxLWk5ajAta2xtbm9wcXJzdHV2IiwibG9hIjoic3Vic3RhbnRpYWwifQ.y42yfMeW2H9h0b0j0BODUml8yF20stY9q3BwoVU5BB90afBj852Q0QlInncdhjXhUjLS1V76cGBxkutDNvxRNA
140      requestBody:
141        required: true
142        content:
143          application/json:
144            schema:
145              $ref: "#/components/schemas/CredentialClaimsRequest"
146      responses:
147        "200":
148          description: OK
149          headers:
150            Agid-JWT-Signature:
151              description: JWT containing the signature of the message headers whose integrity needs to be guaranteed, to comply with the INTEGRITY_REST_02 security pattern (see <a target="blank" href="https://italia.github.io/eid-wallet-it-docs/versione-corrente/en/e-service-pdnd.html">e-Service PDND</a>). <a target="blank" href="https://jwt.io/#debugger-io?token=ew0KICAiYWxnIjogIkVTMjU2IiwNCiAgImtpZCI6ICJhMWY1YzhkMi00YjM3LTRlOTEtYjBkMi03OWUzZjBjNGE4ZWYiLA0KICAidHlwIjogIkpXVCINCn0.ew0KICAiaXNzIjogIjEyMzRhYmNkLWVmNTYtZ2g3OC1pOWowLWtsbW5vcHFyc3R3eCIsDQogICJzdWIiOiAiMTIzNGFiY2QtZWY1Ni1naDc4LWk5ajAta2xtbm9wcXJzdHd4IiwNCiAgImF1ZCI6ICJodHRwczovL2ZydWl0b3JlLmV4YW1wbGUvZW50ZS1leGFtcGxlL3YxIiwNCiAgImlhdCI6IDE3MzMzOTc4NDAsDQogICJuYmYiOiAxNzMzNDAxNjI4LA0KICAiZXhwIjogMTczMzQwMTQ0MCwNCiAgImp0aSI6ICI4ZTEyZjRiNy05YzNhLTRmODMtOWI4ZC01MWEyYzdmNmU5ZDQiLA0KICAic2lnbmVkX2hlYWRlcnMiOiBbDQogICAgew0KICAgICAgImRpZ2VzdCI6ICJTSEEtMjU2PTc5YTIwYTc0NDMzNjQyMDMwMTgzMDYwMGFkOWJkY2E5OTM1OTNmODc2MjA5YTAwNGI1OTliNTgzMDk1YjBhNjEiDQogICAgfSwNCiAgICB7DQogICAgICAiY29udGVudC10eXBlIjogImFwcGxpY2F0aW9uL2pzb24iDQogICAgfQ0KICBdDQp9.DpuBNo2UgQhL7WLin4mpdZrbIpQq3tPvCX6HfktkxG7L5mk6a8OK1Hg0mQcZfFi3gelS-aL9kFS-6MoSy4csBg">EXAMPLE
152              required: true
153              schema:
154                type: string
155            Digest:
156              description: Digest of the message payload, to comply with the INTEGRITY_REST_02 security pattern. According to RFC 3230 Section 4.2 <a target="blank" href="https://www.rfc-editor.org/rfc/rfc3230.html#section-4.2">RFC 3230 §4.2</a>, the format MUST be the following digest-algorithm=encoded digest output.
157              required: true
158              schema:
159                type: string
160                example: SHA-256=79a20a744336420301830600ad9bdca993593f876209a004b599b583095b0a61
161            Cache-Control:
162              $ref: "#/components/headers/CacheControlHeader"
163            X-RateLimit-Limit:
164              $ref: "#/components/headers/RateLimitLimitHeader"
165            X-RateLimit-Remaining:
166              $ref: "#/components/headers/RateLimitRemainingHeader"
167            X-RateLimit-Reset:
168              $ref: "#/components/headers/RateLimitResetHeader"
169          content:
170            application/json:
171              schema:
172                $ref: "#/components/schemas/CredentialClaimsResponse"
173              example:
174                interval: 864000
175                userClaims:
176                  given_name: "Mario"
177                  family_name: "Rossi"
178                  birth_date: "1980-01-10"
179                  place_of_birth:
180                    country: "IT"
181                    region: "Roma"
182                    locality: "Roma"
183                  tax_id_code: "TINIT-RSSMRA80A01H501Z"
184                  personal_administrative_number: "12345A123A"
185                attributeClaims:
186                  - object_id: "6F9619FF-8B86-D011-B42D-00C04FC964FF"
187                    status: "VALID"
188                    last_updated: "2025-01-15T10:30:00Z"
189                    institute_name: "Nome Istituto Universitario"
190                    programme_type_name: "Laurea Magistrale"
191                    degree_course_name: "Computer Science - Informatica"
192                    academic_qualification_date: "2025-06-25"
193                  - object_id: "7A0720AB-9C97-E122-C53E-11D05FD075GG"
194                    status: "VALID"
195                    last_updated: "2025-01-10T08:00:00Z"
196                    institute_name: "Nome Istituto Universitario"
197                    programme_type_name: "Laurea Triennale"
198                    degree_course_name: "Informatica"
199                    academic_qualification_date: "2022-11-27"
200                metadataClaims:
201                  - object_id: "6F9619FF-8B86-D011-B42D-00C04FC964FF"
202                    issuance_date: "2025-06-25"
203                  - object_id: "7A0720AB-9C97-E122-C53E-11D05FD075GG"
204                    issuance_date: "2022-11-27"
205        "400":
206          description: Bad Request
207          content:
208            application/problem+json:
209              schema:
210                $ref: "#/components/schemas/ProblemDetails"
211          headers:
212            X-RateLimit-Limit:
213              $ref: "#/components/headers/RateLimitLimitHeader"
214            X-RateLimit-Remaining:
215              $ref: "#/components/headers/RateLimitRemainingHeader"
216            X-RateLimit-Reset:
217              $ref: "#/components/headers/RateLimitResetHeader"
218        "401":
219          description: Unauthorized
220          content:
221            application/problem+json:
222              schema:
223                $ref: "#/components/schemas/ProblemDetails"
224          headers:
225            X-RateLimit-Limit:
226              $ref: "#/components/headers/RateLimitLimitHeader"
227            X-RateLimit-Remaining:
228              $ref: "#/components/headers/RateLimitRemainingHeader"
229            X-RateLimit-Reset:
230              $ref: "#/components/headers/RateLimitResetHeader"
231            WWW-Authenticate:
232              $ref: "#/components/headers/WWWAuthenticateHeader"
233        "404":
234          description: Claims not found
235          content:
236            application/problem+json:
237              schema:
238                $ref: "#/components/schemas/ProblemDetails"
239          headers:
240            X-RateLimit-Limit:
241              $ref: "#/components/headers/RateLimitLimitHeader"
242            X-RateLimit-Remaining:
243              $ref: "#/components/headers/RateLimitRemainingHeader"
244            X-RateLimit-Reset:
245              $ref: "#/components/headers/RateLimitResetHeader"
246        "429":
247          description: Too Many Requests
248          content:
249            application/problem+json:
250              schema:
251                $ref: "#/components/schemas/ProblemDetails"
252          headers:
253            # RFC 6585 defines Retry-After. X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset are not required because redundant along with Retry-After.
254            Retry-After:
255              $ref: "#/components/headers/RetryAfterHeader"
256        "500":
257          description: Internal Server Error.
258          content:
259            application/problem+json:
260              schema:
261                $ref: "#/components/schemas/ProblemDetails"
262          headers:
263            Retry-After:
264              $ref: "#/components/headers/RetryAfterHeader"
265        "503":
266          description: Service Unavailable
267          content:
268            application/problem+json:
269              schema:
270                $ref: "#/components/schemas/ProblemDetails"
271          headers:
272            Retry-After:
273              $ref: "#/components/headers/RetryAfterHeader"
274
275tags:
276  - name: status
277    description: Endpoint di health check dell'API.
278  - name: credential
279    description: Retrieve information about the credential.
280
281components:
282  securitySchemes:
283    BearerAuth:
284      type: http
285      scheme: bearer
286      bearerFormat: JWT
287      description: PDND Bearer Token
288    DPoPAuth:
289      type: apiKey
290      in: header
291      name: DPoP
292      description: DPoP proof JWT (RFC 9449).
293
294  headers:
295    CacheControlHeader:
296      schema:
297        type: string
298        enum:
299          - no-store
300      description: no-store
301    RateLimitLimitHeader:
302      schema:
303        type: integer
304        format: int32
305        minimum: 0
306      description: Maximum number of requests within the time window.
307    RateLimitRemainingHeader:
308      schema:
309        type: integer
310        format: int32
311        minimum: 0
312      description: Remaining requests within the time window.
313    RateLimitResetHeader:
314      schema:
315        type: integer
316        format: int32
317        minimum: 0
318      description: UTC epoch in seconds, corresponding to when the window for the current rate limit will reset.
319    RetryAfterHeader:
320      schema:
321        type: integer
322        format: int32
323        minimum: 0
324      description: Seconds to wait before receiving another response.
325    WWWAuthenticateHeader:
326      schema:
327        type: string
328        example: >-
329          Bearer error="invalid_token", error_description="The access token expired"
330      description: The request cannot be fulfilled because the Voucher is expired, revoked or otherwise malformed. See <a target="blank" href="https://datatracker.ietf.org/doc/html/rfc6750.html#section-3">RFC6750</a> and <a target="blank" href="https://datatracker.ietf.org/doc/html/rfc9449.html#section-7.1-11">RFC9449</a> for details.
331
332  schemas:
333    CredentialClaimsResponse:
334      type: object
335      properties:
336        userClaims:
337          description: List of User Claims.
338          type: object
339          properties:
340            given_name:
341              description: Current First Name.
342              type: string
343              example: "Mario"
344            family_name:
345              description: Current Family Name.
346              type: string
347              example: "Rossi"
348            birth_date:
349              description: Date of Birth.
350              type: string
351              example: "1980-01-10"
352            place_of_birth:
353              $ref: "#/components/schemas/place_of_birth"
354            tax_id_code:
355              description: National tax identification number. REQUIRED if personal_administrative_number is absent.
356              type: string
357              example: "TINIT-XXXXXXXXXXXXXXXX"
358            personal_administrative_number:
359              description: National unique identifier of a natural person. REQUIRED if tax_id_code is absent.
360              type: string
361              example: "XX00000XX"
362        attributeClaims:
363          description: List of Datasets of Attribute.
364          type: array
365          items:
366            type: object
367            properties:
368              object_id:
369                description: Unique identifier of the Dataset. It MUST NOT contain personal data. Required also if additionalProperties are not present. This parameter MUST be used to notify through Signal Hub data updating or availability.
370                type: string
371                example: "6F9619FF-8B86-D011-B42D-00C04FC964FF"
372              issuance_date:
373                description: Administrative validity start date of the Dataset
374                type: string
375                example: "2025-01-01"
376              expiry_date:
377                description: Administrative expiry date of the Dataset.
378                type: string
379                example: "2025-12-31"
380            additionalProperties:
381              oneOf:
382                - type: string
383                - type: integer
384                  format: int32
385                - type: integer
386                  format: int64
387                - type: number
388                  format: float
389                - type: number
390                  format: double
391                - type: boolean
392                - type: array
393                  items:
394                    $ref: '#/components/schemas/additionalPropertiesArray'
395                - type: object
396                  additionalProperties:
397                    $ref: '#/components/schemas/additionalPropertiesObject'
398            required: [object_id]
399        metadataClaims:
400          description: List of Metadata of Attribute.
401          type: array
402          items:
403            type: object
404            properties:
405              object_id:
406                description: Unique identifier of the Dataset. It MUST NOT contain personal data.
407                type: string
408                example: "6F9619FF-8B86-D011-B42D-00C04FC964FF"
409              description:
410                description: Human-Readable description of the Dataset.
411                type: string
412                example: "Example: Master's Degree in Computer Science"
413              status:
414                description: |
415                  Stato del Dataset. OBBLIGATORIO se additionalProperties di attributeClaims sono presenti. I dataset Issued e Expired ricadono in VALID; la scadenza è verificata
416                  tramite metadata claims (es. expiry_date, nbf/exp). INVALID indica revoca attiva da parte dell'AS.
417                  Per come questo stato influenza il ciclo di vita dell'Attestato Elettronico gestito dal
418                  Fornitore di Attestati Elettronici, vedere la sezione <a target="blank" href="https://italia.github.io/eid-wallet-it-docs/versione-corrente/it/credential-revocation.html#aggiornamento-dello-stato-da-parte-delle-fonti-autentiche">Aggiornamento dello Stato da parte delle Fonti Autentiche</a>.
419                type: string
420                enum:
421                  - VALID
422                  - INVALID
423                  - SUSPENDED
424                x-enum-description:
425                  - VALID - Il dataset è valido (include Issued e Expired; la scadenza è verificata via metadata).
426                  - INVALID - Il dataset è stato attivamente revocato dalla Fonte Autentica.
427                  - SUSPENDED - Il dataset è temporaneamente non valido (tipicamente reversibile).
428                example: "VALID"
429              status_description:
430                description: Human-Readable description of the Status.
431                type: string
432                example: "Example: Master's Degree in Computer Science"
433              last_updated:
434                description: OBBLIGATORIO se additionalProperties di attributeClaims sono presenti. Last time the status or attributes of the Dataset have been updated. Its format is `YYYY-MM-DDTHH:MM:SSZ`.
435                type: string
436                example: "2025-01-15T10:30:00Z"
437              interval:
438                description: Required if userClaims and additionalProperties of AttributeClaim parameters are not present. This represents the estimated amount of time (in seconds) required before making the request of the attribute claims again.
439                type: integer
440                format: int64
441                example: 864000
442            required: [object_id, description]
443      required: [attributeClaims, metadataClaims]
444    CredentialClaimsRequest:
445      required:
446        - unique_id
447      type: object
448      properties:
449        unique_id:
450          type: string
451          description: ID ANPR or Tax identification number
452        object_id:
453          type: string
454          description: Unique identifier of the Credential dataset. If this parameter is present only the indicated dataset is returned.
455    additionalPropertiesArray:
456      type: array
457      items:
458        oneOf:
459        - type: string
460        - type: integer
461          format: int32
462        - type: integer
463          format: int64
464        - type: number
465          format: float
466        - type: number
467          format: double
468        - type: boolean
469        - type: object
470          additionalProperties:
471            $ref: '#/components/schemas/additionalPropertiesObject'
472    additionalPropertiesObject:
473      type: object
474      oneOf:
475        - type: string
476        - type: integer
477          format: int32
478        - type: integer
479          format: int64
480        - type: number
481          format: float
482        - type: number
483          format: double
484        - type: boolean
485    place_of_birth:
486      description: Place of Birth.
487      type: object
488      properties:
489        country:
490          description: "alpha-2 country code as specified in ISO 3166-1"
491          type: string
492          example: "IT"
493        region:
494          description: "Name of a state, province, district, or local area"
495          type: string
496          example: "Roma"
497        locality:
498          description: "Name of a municipality, city, town, or village"
499          type: string
500          example: "Roma"
501      anyOf:
502        - required: [country]
503        - required: [region]
504        - required: [locality]
505    ProblemDetails:
506      type: object
507      description: RFC7807-compliant problem details object for error responses.
508      properties:
509        type:
510          type: string
511          format: uri
512          description: An absolute URI that identifies the problem type.
513        title:
514          type: string
515          description: A short, human-readable summary of the problem type.
516        status:
517          type: integer
518          format: int32
519          description: The HTTP status code generated by the origin server for this occurrence of the problem.
520        detail:
521          type: string
522          description: A human-readable explanation specific to this occurrence of the problem.
523        instance:
524          type: string
525          format: uri
526          description: An absolute URI that identifies the specific occurrence of the problem.
527      required: [title, status, detail]