Guide5 min di lettura

Buone pratiche per l'annotazione di documenti legali

Come annotare documenti legali in Potato, tra contratti, atti giudiziari e testi normativi: etichettatura di span, estrazione di entità e deployment self-hosted attento alla privacy.

Potato Team18 gennaio 2026

Il testo legale è un problema di annotazione a sé. La struttura è densa, il lessico è specialistico e un'etichetta sbagliata può avere conseguenze legali concrete. Questa guida spiega come affrontarlo per bene.

Perché l'annotazione legale è difficile

Già solo il gergo impone di lavorare con annotatori formati, non con crowd worker presi a caso. I documenti sono lunghi, con contratti che a volte arrivano a centinaia di pagine, e le sezioni rimandano di continuo ad altre sezioni. La precisione conta più del solito, perché uno span impreciso può cambiare il senso di una clausola. E buona parte di quel senso dipende dal tipo di documento e dalla giurisdizione, quindi il contesto non è mai facoltativo.

Per i meccanismi di base dell'annotazione a span e su testo, vedi la documentazione sorgente.

Segmentazione dei documenti

Suddividere documenti lunghi

json

{
  "id": "contract_001_section_3.2",
  "text": "The Licensor grants to the Licensee a non-exclusive, non-transferable license...",
  "section_number": "3.2",
  "section_title": "License Grant",
  "document_id": "contract_001"
}

Annotazione a livello di sezione

yaml

instance_display:
  fields:
    - key: section_title
      type: text
    - key: text
      type: text

Riconoscimento di entità legali

Entità specifiche dei contratti

yaml

annotation_schemes:
  - annotation_type: span
    name: legal_entities
    description: "Mark the parties, defined terms, dates, amounts and obligations."
    labels:
      - name: PARTY
        color: "#FECACA"
        tooltip: "Contracting parties, including Licensor, Licensee and named companies"
      - name: DEFINED_TERM
        color: "#FDE68A"
        tooltip: "A term given a specific meaning by the definitions section"
      - name: DATE
        color: "#BBF7D0"
        tooltip: "Dates and time periods, including notice and cure periods"
      - name: MONETARY
        color: "#C4B5FD"
        tooltip: "Amounts, fees, penalties and caps"
      - name: OBLIGATION
        color: "#BFDBFE"
        tooltip: "Language creating a duty, such as shall, must or agrees to"
      - name: CONDITION
        color: "#FED7AA"
        tooltip: "Language making a duty conditional, such as if, unless or provided that"
      - name: REFERENCE
        color: "#E0E7FF"
        tooltip: "A cross-reference to another section or document"

Individuare gli obblighi

yaml

  - annotation_type: radio
    name: clause_type
    description: "What type of clause is this?"
    labels:
      - Definitions
      - Grant of rights
      - Consideration and payment
      - Term and termination
      - Representations and warranties
      - Indemnification
      - Limitation of liability
      - Confidentiality
      - Intellectual property
      - Dispute resolution
      - Boilerplate

Classificazione delle clausole

Tipi di clausola contrattuale

yaml

  - annotation_type: multiselect
    name: obligation_type
    description: "Which kinds of obligation does this clause create?"
    labels:
      - Performance
      - Payment
      - Restriction
      - Conditional obligation
      - Warranty
 
  - annotation_type: likert
    name: risk
    description: "How much risk does this clause carry for the receiving party?"
    size: 5
    min_label: "Low risk"
    max_label: "High risk"
 
  - annotation_type: text
    name: risk_notes
    description: "Explain the risk factors you identified."
    rows: 4
    min_chars: 20

Valutazione del rischio

yaml

annotation_schemes:
  - annotation_type: span
    name: case_entities
    description: "Mark case metadata and the parties to the proceeding."
    labels:
      - name: CASE_NUMBER
        tooltip: "The docket or case identifier"
      - name: COURT
        tooltip: "Court name and jurisdiction"
      - name: JUDGE
      - name: PLAINTIFF
      - name: DEFENDANT
      - name: ATTORNEY
      - name: LEGAL_CITATION
        tooltip: "Citations to cases, statutes and regulations"
      - name: RULING
 
  - annotation_type: span
    name: argument_structure
    description: "Mark the claim, its support, and the court's conclusion."
    labels:
      - name: CLAIM
        color: "#FECACA"
      - name: PREMISE
        color: "#BBF7D0"
      - name: EVIDENCE
        color: "#BFDBFE"
      - name: REBUTTAL
        color: "#FED7AA"
      - name: CONCLUSION
        color: "#E0E7FF"

Annotazione di atti giudiziari

Estrazione delle informazioni sul caso

text

keyword,label,schema,color
shall,OBLIGATION,legal_entities,#FEE2E2
must,OBLIGATION,legal_entities,#FEE2E2
agrees to,OBLIGATION,legal_entities,#FEE2E2
may,permission,legal_entities,#D1FAE5
unless,CONDITION,legal_entities,#DBEAFE
provided that,CONDITION,legal_entities,#DBEAFE
notwithstand*,CONDITION,legal_entities,#DBEAFE

Struttura argomentativa

yaml

keyword_highlights_file: data/legal_terms.csv

Evidenziare i termini legali

yaml

keyword_highlight_settings:
  keyword_probability: 0.8       # show 80% of matched keywords
  random_word_probability: 0.05  # highlight ~5% of other words as distractors

Controllo qualità in ambito legale

yaml

num_annotators_per_item: 3
 
gold_standards:
  enabled: true
  items_file: data/gold_clauses.json
  mode: mixed
  frequency: 20
  accuracy:
    min_threshold: 0.85
    evaluation_count: 10
  feedback:
    show_correct_answer: true
    show_explanation: true

Configurazione completa per l'annotazione legale

yaml

annotation_task_name: "Contract Clause Analysis"
task_description: "Classify contract clauses and mark the entities they refer to."
 
data_files:
  - data/contract_sections.json
 
item_properties:
  id_key: id
  text_key: text
 
instance_display:
  fields:
    - key: section_title
      type: text
    - key: text
      type: text
 
annotation_schemes:
  - annotation_type: radio
    name: clause_type
    description: "What type of clause is this?"
    labels:
      - Grant of rights
      - Consideration and payment
      - Term and termination
      - Indemnification
      - Limitation of liability
      - Confidentiality
      - Other
 
  - annotation_type: span
    name: legal_entities
    description: "Mark the parties, defined terms, dates, amounts and obligations."
    labels:
      - name: PARTY
        color: "#FECACA"
      - name: DEFINED_TERM
        color: "#FDE68A"
      - name: MONETARY
        color: "#C4B5FD"
      - name: DATE
        color: "#BBF7D0"
      - name: OBLIGATION
        color: "#BFDBFE"
 
  - annotation_type: likert
    name: risk
    description: "How much risk does this clause carry for the receiving party?"
    size: 5
    min_label: "Low risk"
    max_label: "High risk"
 
  - annotation_type: text
    name: issues
    description: "Note any unusual or problematic language."
    rows: 4
    min_chars: 20
 
num_annotators_per_item: 3
 
gold_standards:
  enabled: true
  items_file: data/gold_clauses.json
  mode: mixed
  frequency: 20
  accuracy:
    min_threshold: 0.85
    evaluation_count: 10
 
agreement_metrics:
  enabled: true
  min_overlap: 2
 
output_annotation_dir: annotation_output

Scrivere le linee guida per gli annotatori

Delle buone linee guida per un task legale chiariscono l'ambito (quali documenti, quali giurisdizioni) e includono un glossario, così gli annotatori leggono i termini nel tuo stesso modo. Sii esplicito sul linguaggio ambiguo e su quando un rimando incrociato va annotato e quando invece va ignorato. E stabilisci cosa conta come confine corretto di uno span, perché in questo ambito il «più o meno» quasi mai basta.

Buone pratiche

Usa annotatori che il dominio lo conoscono davvero, perché senza l'etichettatura legale non funziona. Spezza i documenti lunghi in sezioni che una persona riesca a tenere a mente. Evidenzia il linguaggio legale che pesa, così nessuno lo scorre distrattamente. Tieni alta la ridondanza, visto che un errore costa caro. Aggiungi uno strato di revisione esperta in cui sono gli avvocati a gestire i casi limite. Definisci ogni etichetta con precisione. E dai agli annotatori la struttura intorno e le sezioni collegate, perché una clausola isolata può trarre in inganno.

Documentazione completa su Schemi di Annotazione.