Documento digitale
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"
]
},
"registry_code": {
"title": "Identificativo interno del registro",
"description": "Eventuale numero identificativo assegnato o codice di risposta restituito dal sistema di protocollazione. Dipende dall'implementazione del sistema di protocollo",
"type": [
"string",
"null"
],
"examples": [
"OK",
"123"
]
}
},
"required": [
"transmission_type",
"date",
"document_number",
"registry_code"
]
},
"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"
}
]
},
"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",
"event_created_at",
"event_id",
"type",
"short_description",
"main_document",
"tenant_id",
"owner_id",
"created_at",
"updated_at",
"source_type",
"recipient_type"
]
}Oggetto Author - mapping
Indica i dati del cittadino ed è composto come segue. Non tutti i seguenti campi saranno sempre presenti nel documento
"type" -> sarà sempre "human"
"tax_identification_number" -> sarà sempre "anonymous"
"name" -> nome
"family_name" -> cognome
"street_name" -> via
"building_number" -> numero civico
"postal_code" -> codice postale
"town_name" -> nome del comune
"country_subdivision"-> provincia
"country" -> stato/nazione
"email" -> indizizzo email
"role" -> sender/receiver : indice se il cittadino è il mittente o il destinataio del documemnto correnteLast updated
