Descrizione in dettaglio di un documento generato dalla piattaforma
Contesto
Secondo l'AGID, il documento informatico è la “rappresentazione informatica di atti, fatti o dati giuridicamente rilevanti" in contrapposizione al documento analogico ("rappresentazione non informatica di atti, fatti o dati giuridicamente rilevanti")".
La piattaforma genera documenti informatici a partire da diversi tipi di servizi offerti.
Il documento informatico ci permette di avere un'unica struttura dati a partire da diverse tipologie di servizi. Questo ci dà il vantaggio di dover gestire un’unica entità durante il processo di protocollazione.
Struttura
Il documento generato dall’area personale del cittadino è stato progettato seguendo le linee guida suggerite dall’AGID. Esso è composto dai seguenti elementi:
Documento principale: descrive in dettaglio il servizio o l'oggetto a cui il documento si riferisce.
Allegati del documento principale: rappresentano l'insieme dei file che accompagnano la documento principale, fornendo ulteriori dettagli, dati o documentazione di supporto.
metadati: includono informazioni utili per la comprensione del contesto del documento informatico. Ci forniscono dettagli sulle informazioni di base, come la data di creazione, il mittente, il destinatario, e altri dettagli pertinenti. Alcuni di essi non possono mancare(vedi sezione seguente).
Specifiche funzionali del documento
Nella nostra piattaforma il documento è implementato in forma di evento Kafka, in formato JSON, descritto dal seguente JSON SCHEMA.
Per una migliore visualizzazione si consiglia di usare un viewer online.
{"$schema":"https://json-schema.org/draft/2020-12/schema#","$id":"https://schema.opencontent.io/document.schema#","type":"object","title":"Documento","definitions": {"registration_info": {"type":"object","title":"Informazioni sul protocollo del documento","properties": {"transmission_type": {"title":"Tipo di trasmissione","type":"string","enum": ["inbound","outbound","internal" ],"examples": ["inbound" ] },"date": {"title":"Data protocollo","type":"string","format":"date-time","examples": ["2022-08-24T11:59:57+02:00" ] },"document_number": {"title":"Numero di protocollo","description":"Numero di protocollo assegnato dal sistema di protocollazione","type":"string","maxLength":255,"examples": ["Prot-123-456-789","123" ] } },"required": ["transmission_type","date","document_number" ] },"folder_info": {"type":"object","title":"Informazioni sul fascicolo","properties": {"title": {"title":"Oggetto del Fascicolo","type": ["string","null" ],"maxLength":255 },"id": {"title":"Numero di Fascicolo","type": ["string","null" ],"maxLength":255 } },"required": ["title","id" ] },"file": {"title":"File","type":"object","properties": {"name": {"title":"Titolo del file","type":"string" },"description": {"title":"Descrizione del file","type": ["string","null" ] },"mime_type": {"title":"Mime type del file","type":"string" },"url": {"title":"Download url della risorsa","type":"string","format":"uri" },"md5": {"title":"Hash md5 del binario","type":"string" },"filename": {"title":"Nome completo del file con estensione","type":"string" },"internal_url": { "title": "Eventuale url interno della risorsa a disposizione dei sistemi dell'ente che sarà utilizzato per servire il binario se questo non viene salvato nello storage della piattaforma",
"type": ["string","null" ],"format":"uri" } },"required": ["name","filename","description","mime_type","url","md5" ] },"image": {"type":"object","title":"Risorsa immagine","properties": {"name": {"title":"Titolo dell'immagine","type":"string" },"filename": {"title":"Nome dell'immagine","type":"string" },"description": {"title":"Descrizione dell'immagine","type":"string" },"license": {"title":"Licenza di utilizzo","type":"string","enum": ["?","??","???" ] },"type": {"title":"Tipologia dell'immagine o mime-type","type":"string" },"url": {"title":"Url della risorsa","type":"string","format":"uri" } },"required": ["name","filename","license","type","url","description" ] },"author": {"type":"object","title":"Autore","properties": {"type": {"type":"string","enum": ["human","legal" ] },"tax_identification_number": {"type":"string" },"name": {"type":"string" },"family_name": {"type": ["string","null" ] },"street_name": {"type": ["string","null" ] },"building_number": {"type": ["string","null" ] },"postal_code": {"type": ["string","null" ] },"town_name": {"type": ["string","null" ] },"country_subdivision": {"type": ["string","null" ] },"country": {"type": ["string","null" ] },"email": {"type":"string","format":"email" } },"required": ["type","tax_identification_number","name","family_name","street_name","building_number","postal_code","town_name","country_subdivision","country","email","role" ] } },"properties": {"title": {"type":"string","maxLength":255,"title":"Titolo del documento", "description": "Nome del documento. Il nome del Documento deve essere facilmente comprensibile dai cittadini. Vincoli: massimo 160 caratteri spazi inclusi",
"examples": ["Istanza di certificato anagrafico" ] },"id": {"type":"string","format":"uuid","title":"Identificativo interno del documento","description":"Identificatore uuid ad uso interno","examples": ["4a68415b-e1a8-4f3a-a229-3f6678fd81d1" ] },"app_id": {"title":"App ID","type":"string","examples": ["document-dispatcher:1.1.1" ] },"event_created_at": {"title":"Data di creazione dell'evento","type":"string","format":"date-time","examples": ["2023-11-23T14:14:23+00:00" ] },"event_id": {"title":"ID dell'evento","type":"string","format":"uuid" },"event_version": {"type":"integer","title":"Versione del documento","description":"Versione del documento","default":1,"examples": [1 ] },"external_id": {"type": ["string","null" ],"title":"Identificativo del documento ad uso dell'ente","description":"Un numero identificativo del documento (es DOI, ISBN)","examples": ["Cert567-2023","4a68415b-e1a8-4f3a-a229-3f6678fd81d1" ] },"registration_data": {"title":"Protocollo","anyOf": [ {"title":"Informazioni sul protocollo del documento","$ref":"#/definitions/registration_info" }, {"title":"Nessuna informazione sul protocollo","type":"null" } ] },"folder": {"title":"Fascicolo","anyOf": [ {"title":"Informazioni sul fascicolo","$ref":"#/definitions/folder_info" }, {"title":"Nessuna informazione sul fascicolo","type":"null" } ] },"status": {"title":"Stato del documento","description":"Stato del documento: descrive lo stato di protocollazione del documento","type":"string","enum": ["DOCUMENT_CREATED","REGISTRATION_PENDING","REGISTRATION_FAILED","PARTIAL_REGISTRATION","REGISTRATION_COMPLETE" ] },"type": {"title":"Tipo di documento", "description": "Tipologia del documento: viene utilizzata una tassonomia custom che va intesa come sotto tassonomia di Istanza https://schema.gov.it/lodview/controlled-vocabulary/classifications-for-documents/government-documents-types/8",
"type":"string","enum": ["application-request","integration-request","integration-response","application-outcome","application-withdraw","application-revocation" ] },"remote_id": {"title":"Pratica associata","description":"Identificativo della pratica associata","type": ["string","null" ],"format":"uuid","examples": ["842b37e7-d835-49f0-92e2-a393ecda2e53" ] },"remote_collection": {"title":"Servizio collegato","anyOf": [ {"title":"Servizio collegato", "description": "Se il documento non è collegato a una pratica è possibile indicare il servizio che ha generato il documento",
"type":"object","properties": {"id": {"type":"string","format":"uuid","examples": ["842b37e7-12a4-49f0-92e2-a393ecda2e53" ] },"type": {"type":"string","enum": ["service","service-group","subscription","calendar" ],"examples": ["service" ] } },"required": ["id","type" ] }, {"title":"Nessuna servizio collegato","type":"null" } ] },"topics": {"title":"Argomenti","description":"Argomenti collegabili","type":"array","minItems":0,"items": {"title":"Argomento","type":"string","minItems":0 } },"short_description": {"title":"Descrizione breve", "description": "Descrizione sintetica del documento (max 255 caratteri) utilizzando un linguaggio semplice che possa aiutare qualsiasi utente a identificare con chiarezza il documento. Non utilizzare un linguaggio ricco di riferimenti normativi",
"type":"string","maxLength":255 },"description": {"title":"Descrizione", "description": "L'oggetto del documento, utilizzando un linguaggio semplice che possa aiutare qualsiasi utente a identificare con chierazza il documento. Non utilizzare un linguaggio ricco di riferimenti normativi.",
"type": ["string","null" ] },"main_document": {"title":"URL documento","$ref":"#/definitions/file" },"image_gallery": {"title":"Galleria di immagini","type":"array","items": {"$ref":"#/definitions/image" },"minItems":0 },"has_organization": {"title":"Ufficio responsabile del documento","anyOf": [ {"title":"Link alla scheda dell'ufficio responsabile del documento","type":"string","format":"uri","examples": ["https://example.com/offices/1" ] }, {"title":"Nessuna informazione sull'ufficio","type":"null" } ] },"attachments": {"title":"Allegati","description":"Altre risorse oltre alla principale","type":"array","minItems":0,"items": {"$ref":"#/definitions/file" } },"distribution_license_id": {"title":"Licenza di distribuzione","type": ["string","null" ] },"related_public_services": {"title":"Servizi collegati","description":"Servizi che usano questo documento come input","type":"array","items": {"type":"object","title":"Servizio collegato","properties": {"name": {"id":"Id del servizio","type":"string" },"type": {"title":"Tipologia del servizio","type":"string" },"url": {"title":"Descrizione del file","type":"string","format":"uri" } },"required": ["id","type","url" ] },"minItems":0 },"valid_from": {"title":"Data inizio validità","description":"Data da cui il documento è valido","type": ["string","null" ],"format":"date-time","examples": ["2022-08-24T11:59:57+02:00" ] },"valid_to": {"title":"Data fine validità","description":"Data da cui il documento non è più valido","type": ["string","null" ],"format":"date-time","examples": ["2022-08-24T11:59:57+02:00" ] },"removed_at": {"title":"Data ultima disponibilità","description":"Data fino alla quale il documento sarà disponibile online","type": ["string","null" ],"format":"date-time","examples": ["2022-08-24T11:59:57+02:00" ] },"expire_at": {"title":"Data scadenza", "description": "Solitamente uguale a fine validità, è la data entro la quale il documento deve essere eventualmente rinnovato",
"type": ["string","null" ],"format":"date-time","examples": ["2022-08-24T11:59:57+02:00" ] },"more_info": {"title":"Ulteriori informazioni","description":"Ulteriori informazioni sul documento","type": ["string","null" ] },"normative_requirements": {"title":"Riferimenti normativi","description":"Lista di link con riferimenti normativi utili per il documento","type":"array","minItems":0,"items": {"type":"string","format":"uri" } },"related_documents": {"title":"Documenti collegati","description":"Lista di documenti allegati: link a quelli strutturati a loro volta come documenti","type":"array","minItems":0,"items": {"type":"string","format":"uri" } },"life_events": {"title":"Life Events","description":"Life Events collegabili","type":"array","minItems":0,"items": {"type":"string" } },"business_events": {"title":"Business Events","description":"Business Events collegabili","type":"array","minItems":0,"items": {"type":"string" } },"allowed_readers": {"title":"Lista di identificatori di persone che possono accedere in lettura al documento","description":"??? Vedi onotologia...","type":"array","minItems":0,"items": {"type":"string" } },"tenant_id": {"title":"Ente","type":"string","format":"uuid","description":"Uuid del tenant","examples": ["842b37e7-d835-49f0-92e2-a393ecda2e53" ] },"owner_id": {"title":"Proprietario","description":"Uuid del proprietario del documento","type":"string","format":"uuid" },"document_url": {"title":"Url pubblico del documento","type": ["string","null" ],"format":"uri" },"created_at": {"title":"Data di creazione","type":"string","format":"date-time","examples": ["2022-08-24T11:59:57+02:00" ] },"updated_at": {"title":"Data ultima modifica","type":"string","format":"date-time","examples": ["2022-08-24T11:59:57+02:00" ] },"author": {"title":"Autore/i","description":"Persone che hanno redatto il documento","type":"array","minItems":0,"items": {"$ref":"#/definitions/author" } },"source_type": {"title":"Tipologia del soggetto che ha generato il documento","description":"In base a questo che si identifica la transmission type","type":"string","enum": ["tenant","user" ] },"recipient_type": {"title":"Tipologia di destinatario del documento","description":"In base a questo che si identifica la transmission type","type":"string","enum": ["tenant","user" ] },"last_seen": {"title":"Data ultima visualizzazione da parte del destinatario","type": ["string","null" ],"format":"date-time","examples": ["2022-08-24T11:59:57+02:00" ] } },"required": ["title","id","event_version","app_id","status","event_created_at","event_id","type","short_description","main_document","tenant_id","owner_id","created_at","updated_at","source_type","recipient_type" ]}
Struttura e mapping
Ecco una tabella che rappresenta il tuo JSON Schema con le colonne Campo, Tipo, Obbligatorio e Validazione.
