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"
          ]
        }
      },
      "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

Campo	Tipo	Obbligatorio	Validazione
title	String	✅	MaxLength: 255, descrizione chiara del documento, massimo 160 caratteri spazi inclusi
id	String (UUID)	✅	Formato: UUID, identificativo univoco
app_id	String	✅	-
event_created_at	String (DateTime)	✅	Formato: DateTime
event_id	String (UUID)	✅	Formato: UUID
event_version	Integer	✅	Valore di default: 1
external_id	String, Null	❌	-
registration_data	Object, Null	❌	Informazioni di protocollo
folder	Object, Null	❌	Informazioni sul fascicolo
status	String	✅	Valori: DOCUMENT_CREATED, REGISTRATION_PENDING, REGISTRATION_FAILED, PARTIAL_REGISTRATION, REGISTRATION_COMPLETE
type	String	✅	Tassonomia di Istanza: application-request, integration-request, integration-response, etc.
remote_id	String (UUID), Null	❌	-
remote_collection	Object, Null	❌	-
topics	Array[String]	❌	MinItems: 0
short_description	String	✅	MaxLength: 255
description	String, Null	❌	-
main_document	Object	✅	-
image_gallery	Array[Object]	❌	MinItems: 0
has_organization	String (URI), Null	❌	-
attachments	Array[Object]	❌	MinItems: 0
distribution_license_id	String, Null	❌	-
related_public_services	Array[Object]	❌	-
valid_from	String (DateTime), Null	❌	-
valid_to	String (DateTime), Null	❌	-
removed_at	String (DateTime), Null	❌	-
expire_at	String (DateTime), Null	❌	-
more_info	String, Null	❌	-
normative_requirements	Array[URI]	❌	-
related_documents	Array[URI]	❌	-
life_events	Array[String]	❌	MinItems: 0
business_events	Array[String]	❌	MinItems: 0
allowed_readers	Array[String]	❌	MinItems: 0
tenant_id	String (UUID)	✅	Uuid del tenant
owner_id	String (UUID)	✅	Uuid del proprietario del documento
document_url	String (URI), Null	❌	-
created_at	String (DateTime)	✅	-
updated_at	String (DateTime)	✅	-
author	Array[Object]	❌	MinItems: 0
source_type	String	✅	Valori: tenant, user
recipient_type	String	✅	Valori: tenant, user
last_seen	String (DateTime), Null	❌	-

registration_data

Campo	Tipo	Obbligatorio	Validazione
transmission_type	String	✅	Valori: Inbound, Outbound
date	String (Date)	❌	Data valida in formato YYYY-MM-DD
document_number	String	❌	Numero del documento

folder

Campo	Tipo	Obbligatorio	Validazione
title	String	✅	Titolo descrittivo del fascicolo
id	String	❌	Identificativo del fascicolo

main_document

Campo	Tipo	Obbligatorio	Validazione
name	String	✅	Nome del file
description	String	✅	Descrizione del documento
mime_type	String	✅	Formato MIME, es: application/pdf
url	String (URI)	✅	URL del documento
md5	String	❌	Hash MD5 del file
filename	String	✅	Nome del file salvato sul server

attachments

Campo	Tipo	Obbligatorio	Validazione
name	String	✅	Nome del file allegato
description	String	✅	Descrizione dell'allegato
mime_type	String	✅	Formato MIME, es: application/pdf
url	String (URI)	✅	URL dell'allegato
md5	String	❌	Hash MD5 del file
filename	String	✅	Nome del file salvato sul server

author

Campo	Tipo	Obbligatorio	Validazione
type	String	✅	Valori: human, legal
tax_identification_number	String	✅	Codice fiscale
name	String	✅	Nome dell'autore
family_name	String	✅	Cognome dell'autore
street_name	String	✅	Indirizzo
postal_code	String	✅	Codice postale
email	String	✅	Formato: email valido
role	String	✅	Ruolo (es: sender, receiver)