{
  "openapi": "3.1.0",
  "info": {
    "title": "Parola Viva — Open Data API",
    "description": "Bibbia Martini (73 libri, 35.714 versetti) e calendario liturgico del Rito Romano come Open Data.\n\nTutti gli endpoint sono file JSON statici o dinamici (Worker), senza autenticazione.\n\n**Testo:** Bibbia Martini (1769–1781), pubblico dominio.\n**Dati strutturati e calendario liturgico:** CC-BY 4.0.\nA cura di [Giovanni Novelli](https://about.novelli.me) — [parolaviva.art](https://parolaviva.art)\n\n---\n\n**MCP Server** — Per assistenti AI (Claude, ChatGPT, ecc.) è disponibile un server [Model Context Protocol](https://modelcontextprotocol.io) all'endpoint `POST https://parolaviva.art/mcp/v1` (alias: `https://mcp.parolaviva.art`) (JSON-RPC 2.0, Streamable HTTP). 34 tool + 3 prompt. Documentazione: [/opendata](https://parolaviva.art/opendata).\n\nNuovi tool MCP (giugno 2026): people_search, places_search, faq_search, occasions_list, reading_plans_list, famous_passages, catalog_search (34 totali).",
    "version": "1.0.0",
    "contact": {
      "name": "Giovanni Novelli",
      "url": "https://about.novelli.me"
    },
    "license": {
      "name": "CC-BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    }
  },
  "servers": [
    {
      "url": "https://parolaviva.art",
      "description": "Produzione"
    }
  ],
  "tags": [
    {
      "name": "Bibbia",
      "description": "Testo integrale della Bibbia Martini"
    },
    {
      "name": "Liturgia",
      "description": "Letture liturgiche del Rito Romano"
    },
    {
      "name": "Ricerca",
      "description": "Ricerca nel testo biblico"
    },
    {
      "name": "Catalogo",
      "description": "Catalogo dei passi contemplativi"
    },
    {
      "name": "Concordanza",
      "description": "Concordanza lemmatizzata della Bibbia Martini"
    },
    {
      "name": "Similarità",
      "description": "Similarità semantica tra capitoli della Bibbia Martini"
    },
    {
      "name": "Persone",
      "description": "Persone bibliche (54) con versetti chiave"
    },
    {
      "name": "Luoghi",
      "description": "Luoghi biblici (47) con versetti chiave"
    },
    {
      "name": "Domande",
      "description": "Domande frequenti sulla Bibbia (46) con versetti di risposta"
    },
    {
      "name": "Occasioni",
      "description": "Letture per occasioni liturgiche (matrimonio, funerali, ecc.)"
    },
    {
      "name": "Piani",
      "description": "Piani di lettura biblica"
    },
    {
      "name": "Passi Famosi",
      "description": "Galleria dei 288 passi biblici più famosi"
    }
  ],
  "paths": {
    "/api/v1/bibbia/indice.json": {
      "get": {
        "tags": [
          "Bibbia"
        ],
        "summary": "Indice dei libri",
        "description": "Restituisce l'elenco dei 73 libri della Bibbia Martini con sigle, nomi completi e numero di capitoli.",
        "operationId": "getIndiceBibbia",
        "responses": {
          "200": {
            "description": "Elenco dei libri",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Libro"
                  }
                },
                "example": [
                  {
                    "s": "gen",
                    "n": "Genesi",
                    "m": "Gen",
                    "c": 50
                  },
                  {
                    "s": "gv",
                    "n": "Vangelo secondo Giovanni",
                    "m": "Gv",
                    "c": 21
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/api/v1/bibbia/{libro}/{capitolo}.json": {
      "get": {
        "tags": [
          "Bibbia"
        ],
        "summary": "Capitolo della Bibbia",
        "description": "Restituisce tutti i versetti di un capitolo. Il testo è della Bibbia Martini, fedelmente riprodotto.",
        "operationId": "getCapitoloBibbia",
        "parameters": [
          {
            "name": "libro",
            "in": "path",
            "required": true,
            "description": "Sigla breve del libro (campo `s` dall'indice). Es: `gen`, `gv`, `sal`, `1cor`.",
            "schema": {
              "type": "string"
            },
            "example": "gv"
          },
          {
            "name": "capitolo",
            "in": "path",
            "required": true,
            "description": "Numero del capitolo (da 1 al massimo indicato nell'indice).",
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "example": 3
          }
        ],
        "responses": {
          "200": {
            "description": "Capitolo con versetti",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Capitolo"
                },
                "example": {
                  "l": "Gv",
                  "n": "Vangelo secondo Giovanni",
                  "c": 3,
                  "v": [
                    {
                      "n": 1,
                      "t": "Or v'era tra' Farisei un uomo, per nome Nicodemo, uno de' capi de' Giudei."
                    },
                    {
                      "n": 16,
                      "t": "Imperocché Iddio ha talmente amato il mondo, che ha dato il suo unigenito Figliuolo, affinché chiunque crede in lui non perisca, ma abbia la vita eterna."
                    }
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Libro o capitolo non trovato",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Errore"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/bibbia/{sigla}/{capitolo}/liturgia": {
      "get": {
        "tags": [
          "Liturgia"
        ],
        "summary": "Occorrenze liturgiche di un capitolo",
        "description": "Restituisce tutte le celebrazioni in cui un capitolo viene letto nella liturgia. Dati pre-generati, cache immutabile.",
        "operationId": "getLiturgiaCapitolo",
        "parameters": [
          {
            "name": "sigla",
            "in": "path",
            "required": true,
            "description": "Sigla del libro (es. gv, sal, gen)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "capitolo",
            "in": "path",
            "required": true,
            "description": "Numero del capitolo",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Occorrenze liturgiche del capitolo",
            "content": {
              "application/json": {
                "example": {
                  "occorrenze": [
                    {
                      "celebrazione": "IV Domenica di Quaresima",
                      "ciclo": "A",
                      "tipo": "salmo",
                      "riferimento": "Sal 22,1-6"
                    }
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Capitolo non trovato",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Errore"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/bibbia/{sigla}/{capitolo}/{versetti}": {
      "get": {
        "tags": [
          "Bibbia"
        ],
        "summary": "Versetti specifici di un capitolo",
        "description": "Restituisce solo i versetti specificati da un capitolo. Più efficiente di scaricare tutto il capitolo e filtrare client-side.",
        "operationId": "getVersetti",
        "parameters": [
          {
            "name": "sigla",
            "in": "path",
            "required": true,
            "description": "Sigla del libro (es. gen, gv, sal)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "capitolo",
            "in": "path",
            "required": true,
            "description": "Numero del capitolo",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "versetti",
            "in": "path",
            "required": true,
            "description": "Versetto singolo (es. 16) o range (es. 1-5)",
            "schema": {
              "type": "string",
              "pattern": "^\\d+(-\\d+)?$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Versetti richiesti con riferimento e link",
            "content": {
              "application/json": {
                "example": {
                  "libro": "Gv",
                  "capitolo": 3,
                  "riferimento": "Gv 3,16",
                  "versetti": [
                    {
                      "n": 16,
                      "t": "Imperocchè Iddio ha talmente amato il mondo..."
                    }
                  ],
                  "link": "https://parolaviva.art/bibbia/gv/3/16"
                }
              }
            }
          },
          "404": {
            "description": "Libro, capitolo o versetti non trovati"
          }
        }
      }
    },
    "/api/v1/casuale": {
      "get": {
        "tags": [
          "Bibbia"
        ],
        "summary": "Versetto casuale",
        "description": "Restituisce un versetto casuale dalla Bibbia Martini. Filtri opzionali per libro, tema o tag (questi ultimi limitano la scelta ai passi contemplativi corrispondenti). Non cachato.",
        "operationId": "getCasuale",
        "parameters": [
          {
            "name": "libro",
            "in": "query",
            "required": false,
            "description": "Sigla del libro (es. gen, gv, sal)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tema",
            "in": "query",
            "required": false,
            "description": "Tema contemplativo (es. giardino, passione, luce-oro)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tag",
            "in": "query",
            "required": false,
            "description": "Tag tematico (es. amore, salvezza, creazione)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Versetto casuale con riferimento, testo e link",
            "content": {
              "application/json": {
                "example": {
                  "riferimento": "Sal 22,1",
                  "testo": "Il Signore mi governa, e niuna cosa a me mancherà:",
                  "link": "https://parolaviva.art/bibbia/sal/22/1"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/catalogo": {
      "get": {
        "tags": [
          "Catalogo"
        ],
        "summary": "Cerca nel catalogo passi contemplativi",
        "description": "Cerca tra i passi contemplativi pubblicati per tema, libro, tag o testo.",
        "parameters": [
          {
            "name": "tema",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Tema sacro"
          },
          {
            "name": "libro",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Sigla libro"
          },
          {
            "name": "tag",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Tag"
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Testo nel titolo"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 300
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lista passi"
          }
        }
      }
    },
    "/api/v1/cerca": {
      "get": {
        "tags": [
          "Ricerca"
        ],
        "summary": "Ricerca avanzata nel testo biblico",
        "description": "Cerca nella Bibbia Martini (35.714 versetti). Operatori: AND, OR, NOT, parentesi, wildcard, frasi esatte. Case-insensitive, ignora accenti. Parametri: limit (default 50, max 500, 0=tutti), format (full/refs).",
        "operationId": "cercaBibbia",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Query di ricerca (da 2 a 200 caratteri). Supporta AND, OR, NOT, parentesi, wildcard (* come prefisso/suffisso) e frasi esatte tra virgolette.",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 200
            },
            "examples": {
              "semplice": {
                "value": "principio",
                "summary": "Parola singola"
              },
              "and": {
                "value": "amore AND verita",
                "summary": "Operatore AND"
              },
              "or": {
                "value": "pace OR gioia",
                "summary": "Operatore OR"
              },
              "wildcard_prefisso": {
                "value": "am*",
                "summary": "Wildcard prefisso"
              },
              "wildcard_suffisso": {
                "value": "*osa",
                "summary": "Wildcard suffisso"
              },
              "frase": {
                "value": "\"nel principio\"",
                "summary": "Frase esatta"
              },
              "complessa": {
                "value": "(pace OR gioia) AND cuore",
                "summary": "Query composta"
              },
              "not": {
                "value": "amore AND NOT odio",
                "summary": "Operatore NOT (esclusione)"
              }
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Numero massimo di risultati. Default 50, massimo 500. Usa 0 per ottenere tutti i risultati.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 500,
              "default": 50
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "description": "Formato dei risultati: `full` (default) restituisce oggetti con riferimento e testo; `refs` restituisce solo i riferimenti biblici come array di stringhe.",
            "schema": {
              "type": "string",
              "enum": [
                "full",
                "refs"
              ],
              "default": "full"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Risultati della ricerca",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RisultatoRicerca"
                },
                "example": {
                  "risultati": [
                    {
                      "riferimento": "Gv 1,1",
                      "testo": "Nel principio era il Verbo, e il Verbo era appresso Dio, e il Verbo era Dio."
                    }
                  ],
                  "totale": 1
                }
              }
            }
          },
          "400": {
            "description": "Query non valida (meno di 3 o più di 50 caratteri)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Errore"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/cerca/arricchita": {
      "get": {
        "tags": [
          "Ricerca"
        ],
        "summary": "Ricerca arricchita con contesto liturgico",
        "description": "Cerca nella Bibbia Martini e arricchisce i risultati con il contesto liturgico. Per ogni capitolo nei risultati, indica quante volte appare nel lezionario e in quali tipi di celebrazione. Combina ricerca testuale e occorrenze liturgiche in una sola chiamata.",
        "operationId": "cercaArricchita",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Query di ricerca (stessa sintassi di `/api/v1/cerca`).",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 200
            }
          },
          {
            "name": "libro",
            "in": "query",
            "required": false,
            "description": "Filtra per libro (sigla breve).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Max risultati (default 20, max 100).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Risultati con contesto liturgico per capitolo",
            "content": {
              "application/json": {
                "example": {
                  "risultati": [
                    {
                      "riferimento": "Sal 22,1",
                      "testo": "Il Signore mi governa...",
                      "link": "https://parolaviva.art/bibbia/sal/22/1"
                    }
                  ],
                  "totale": 1,
                  "contesto_liturgico": {
                    "sal/22": {
                      "occorrenze": 5,
                      "tipi": {
                        "salmo": 4,
                        "prima": 1
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Query non valida"
          }
        }
      }
    },
    "/api/v1/concordanza": {
      "get": {
        "tags": [
          "Ricerca"
        ],
        "summary": "Concordanza lemmatizzata",
        "description": "Concordanza lemmatizzata della Bibbia Martini. Restituisce varianti ortografiche, frequenza, distribuzione per libro e versetti di esempio. Con `kwic=true`, aggiunge Key Word In Context (max 100 risultati, campione stratificato per sezione biblica).",
        "operationId": "getConcordanza",
        "parameters": [
          {
            "name": "lemma",
            "in": "query",
            "required": false,
            "description": "Lemma da cercare (es. 'figlio', 'dire'). Alternativa a forma.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "forma",
            "in": "query",
            "required": false,
            "description": "Forma testuale esatta (es. 'figliuoli'). Viene risolta al lemma.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "libro",
            "in": "query",
            "required": false,
            "description": "Filtra per libro (sigla breve).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "kwic",
            "in": "query",
            "required": false,
            "description": "Se `true`, aggiunge array `kwic` con contesto testuale (max 100 risultati da 20 capitoli stratificati per sezione biblica).",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "finestra",
            "in": "query",
            "required": false,
            "description": "Parole di contesto prima/dopo nel KWIC (default 5, min 2, max 10).",
            "schema": {
              "type": "integer",
              "minimum": 2,
              "maximum": 10,
              "default": 5
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Dati del lemma con forme, distribuzione, esempi e opzionalmente KWIC",
            "content": {
              "application/json": {
                "example": {
                  "lemma": "figlio",
                  "pos": "NOUN",
                  "frequenza": 1847,
                  "forme": {
                    "figliuolo": 523,
                    "figliuoli": 412,
                    "figlio": 312
                  },
                  "libri": {
                    "gv": 85,
                    "mt": 73
                  },
                  "kwic": [
                    {
                      "rif": "Gv 3,16",
                      "prima": "il suo unigenito",
                      "parola": "Figliuolo",
                      "dopo": "affinché chiunque crede"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Nessun lemma o forma specificato"
          },
          "404": {
            "description": "Lemma non trovato"
          }
        }
      }
    },
    "/api/v1/confronta": {
      "get": {
        "tags": [
          "Similarità"
        ],
        "summary": "Confronta due capitoli",
        "description": "Confronta due capitoli della Bibbia: restituisce il punteggio di similarità combinata (se presente nella top-10) e i lemmi condivisi con le rispettive frequenze.",
        "operationId": "getConfronta",
        "parameters": [
          {
            "name": "sigla1",
            "in": "query",
            "required": true,
            "description": "Sigla del primo libro",
            "schema": {
              "type": "string"
            },
            "example": "gen"
          },
          {
            "name": "cap1",
            "in": "query",
            "required": true,
            "description": "Capitolo del primo libro",
            "schema": {
              "type": "integer"
            },
            "example": 1
          },
          {
            "name": "sigla2",
            "in": "query",
            "required": true,
            "description": "Sigla del secondo libro",
            "schema": {
              "type": "string"
            },
            "example": "gv"
          },
          {
            "name": "cap2",
            "in": "query",
            "required": true,
            "description": "Capitolo del secondo libro",
            "schema": {
              "type": "integer"
            },
            "example": 1
          }
        ],
        "responses": {
          "200": {
            "description": "Risultato del confronto",
            "content": {
              "application/json": {
                "example": {
                  "capitolo_1": "gen 1",
                  "capitolo_2": "gv 1",
                  "similarita_combinata": 0.025,
                  "lemmi_condivisi": [
                    {
                      "parola": "principio",
                      "frequenza": 3
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Parametri mancanti",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Errore"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/domande": {
      "get": {
        "tags": [
          "Domande"
        ],
        "summary": "Cerca domande bibliche",
        "description": "Cerca tra 46 domande frequenti con versetti di risposta dalla Bibbia Martini.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Testo nella domanda o nei tag"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 200
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lista domande con versetti"
          }
        }
      }
    },
    "/api/v1/dossier/{sigla}/{capitolo}": {
      "get": {
        "tags": [
          "Bibbia"
        ],
        "summary": "Dossier completo di un passo",
        "description": "Aggregazione in 1 chiamata di: testo biblico, paralleli autoriali, capitoli simili (top-5), occorrenze liturgiche e parole chiave (frequenze). 5 fetch parallele server-side per massima efficienza.",
        "operationId": "getDossierCapitolo",
        "parameters": [
          {
            "name": "sigla",
            "in": "path",
            "required": true,
            "description": "Sigla del libro (es. gv, sal, gen)",
            "schema": {
              "type": "string"
            },
            "example": "gv"
          },
          {
            "name": "capitolo",
            "in": "path",
            "required": true,
            "description": "Numero del capitolo",
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "example": 3
          }
        ],
        "responses": {
          "200": {
            "description": "Dossier completo del capitolo",
            "content": {
              "application/json": {
                "example": {
                  "sigla": "gv",
                  "capitolo": 3,
                  "link": "https://parolaviva.art/bibbia/gv/3/",
                  "testo": [
                    {
                      "n": 1,
                      "t": "Or v'era tra' Farisei..."
                    }
                  ],
                  "libro": "Gv",
                  "simili": [
                    {
                      "riferimento": "Gv 1",
                      "punteggio": 0.03,
                      "link": "https://parolaviva.art/bibbia/gv/1/"
                    }
                  ],
                  "liturgia": [],
                  "parole_chiave": [
                    {
                      "parola": "dio",
                      "frequenza": 12
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Parametri mancanti",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Errore"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/dossier/{sigla}/{capitolo}/{path}": {
      "get": {
        "tags": [
          "Bibbia"
        ],
        "summary": "Dossier completo di un passo specifico",
        "description": "Come il dossier del capitolo, ma per un range di versetti specifico. Include anche paralleli autoriali e correlazioni per tag (se il passo è nel catalogo contemplativi).",
        "operationId": "getDossierPasso",
        "parameters": [
          {
            "name": "sigla",
            "in": "path",
            "required": true,
            "description": "Sigla del libro",
            "schema": {
              "type": "string"
            },
            "example": "gv"
          },
          {
            "name": "capitolo",
            "in": "path",
            "required": true,
            "description": "Numero del capitolo",
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "example": 3
          },
          {
            "name": "path",
            "in": "path",
            "required": true,
            "description": "Versetto o range (es. 16, 1-5)",
            "schema": {
              "type": "string"
            },
            "example": "16"
          }
        ],
        "responses": {
          "200": {
            "description": "Dossier completo del passo",
            "content": {
              "application/json": {
                "example": {
                  "sigla": "gv",
                  "capitolo": 3,
                  "path": "16",
                  "link": "https://parolaviva.art/bibbia/gv/3/16",
                  "testo": [
                    {
                      "n": 16,
                      "t": "Imperocché Iddio ha talmente amato il mondo..."
                    }
                  ],
                  "libro": "Gv",
                  "paralleli": [],
                  "correlati": [],
                  "simili": [],
                  "liturgia": [],
                  "parole_chiave": []
                }
              }
            }
          },
          "400": {
            "description": "Parametri mancanti"
          }
        }
      }
    },
    "/api/v1/frequenze": {
      "get": {
        "tags": [
          "Ricerca"
        ],
        "summary": "Frequenza parole nei versetti",
        "description": "Conta la frequenza delle parole nei versetti specificati per query o lista di riferimenti. Utile per word cloud. Esclude stop words italiane per default. Componibile con /api/v1/cerca.",
        "operationId": "frequenzeParole",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Query di ricerca (stessa sintassi di `/api/v1/cerca`). Alternativa a `refs`.",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 200
            },
            "examples": {
              "query": {
                "value": "misericordia",
                "summary": "Frequenze nei versetti che contengono 'misericordia'"
              }
            }
          },
          {
            "name": "refs",
            "in": "query",
            "required": false,
            "description": "Lista di riferimenti separati da virgola, formato `sigla/capitolo` o `sigla/capitolo/versetto` o `sigla/capitolo/inizio-fine`. Max 100. Alternativa a `q`.",
            "schema": {
              "type": "string"
            },
            "examples": {
              "capitoli": {
                "value": "gen/1,sal/22",
                "summary": "Due capitoli interi"
              },
              "versetti": {
                "value": "gv/3/16,sal/22/1-6",
                "summary": "Versetti specifici"
              }
            }
          },
          {
            "name": "min",
            "in": "query",
            "required": false,
            "description": "Frequenza minima per includere una parola. Default 2.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 2
            }
          },
          {
            "name": "stopwords",
            "in": "query",
            "required": false,
            "description": "Se `0`, include anche stop words italiane. Default: escluse.",
            "schema": {
              "type": "string",
              "enum": [
                "0",
                "1"
              ],
              "default": "1"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Numero massimo di parole restituite. Default 100, massimo 500.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 500,
              "default": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Frequenze delle parole ordinate per frequenza decrescente",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RisultatoFrequenze"
                },
                "example": {
                  "parole": [
                    {
                      "parola": "signore",
                      "frequenza": 47
                    },
                    {
                      "parola": "misericordia",
                      "frequenza": 23
                    }
                  ],
                  "totale_versetti": 156,
                  "totale_parole_uniche": 89,
                  "query": "misericordia"
                }
              }
            }
          },
          "400": {
            "description": "Parametri non validi",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Errore"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/letture/cerca": {
      "get": {
        "tags": [
          "Liturgia"
        ],
        "summary": "Cerca letture per riferimento biblico",
        "description": "Dato un riferimento biblico, restituisce tutte le celebrazioni liturgiche in cui quel passo viene letto. Utile per sapere quando un versetto ricorre nella liturgia del Rito Romano.",
        "operationId": "cercaLetture",
        "parameters": [
          {
            "name": "r",
            "in": "query",
            "required": true,
            "description": "Riferimento biblico (es. 'Gv 3,16', 'Sal 22').",
            "schema": {
              "type": "string"
            },
            "examples": {
              "versetto": {
                "value": "Gv 3,16",
                "summary": "Versetto specifico"
              },
              "capitolo": {
                "value": "Sal 22",
                "summary": "Capitolo intero"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Occorrenze liturgiche del passo",
            "content": {
              "application/json": {
                "example": {
                  "riferimento": "Sal 22",
                  "occorrenze": [
                    {
                      "celebrazione": "IV Domenica di Quaresima",
                      "ciclo": "A",
                      "tipo": "salmo",
                      "rango": 2,
                      "colore": "viola"
                    }
                  ],
                  "totale": 1,
                  "link": "https://parolaviva.art/bibbia/sal/22"
                }
              }
            }
          },
          "400": {
            "description": "Riferimento mancante o non valido"
          },
          "503": {
            "description": "Indice riferimenti non disponibile"
          }
        }
      }
    },
    "/api/v1/letture/mese/{anno}/{mese}": {
      "get": {
        "tags": [
          "Liturgia"
        ],
        "summary": "Calendario liturgico del mese",
        "description": "Restituisce le letture liturgiche per tutti i giorni di un mese. Fetch parallele per tutti i giorni. Ogni giorno include celebrazione, colore, letture e lettura complementare con link.",
        "operationId": "getLettureMese",
        "parameters": [
          {
            "name": "anno",
            "in": "path",
            "required": true,
            "description": "Anno (2020-2030)",
            "schema": {
              "type": "integer"
            },
            "example": 2026
          },
          {
            "name": "mese",
            "in": "path",
            "required": true,
            "description": "Mese (1-12)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 12
            },
            "example": 3
          }
        ],
        "responses": {
          "200": {
            "description": "Calendario del mese con tutti i giorni",
            "content": {
              "application/json": {
                "example": {
                  "anno": 2026,
                  "mese": 3,
                  "giorni_totali": 31,
                  "giorni": [
                    {
                      "data": "2026-03-01",
                      "celebrazione": "Domenica...",
                      "colore": "viola"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Parametri mancanti",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Errore"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/letture/oggi": {
      "get": {
        "tags": [
          "Liturgia"
        ],
        "summary": "Letture liturgiche di oggi",
        "description": "Restituisce le letture liturgiche del giorno corrente con testo integrale, link e lettura complementare. Per default include il testo dei versetti; passa `include_text=0` per ottenere solo i riferimenti.",
        "operationId": "getLettureOggi",
        "parameters": [
          {
            "name": "include_text",
            "in": "query",
            "required": false,
            "description": "Se `0`, restituisce solo i riferimenti senza testo. Default: include il testo.",
            "schema": {
              "type": "string",
              "enum": [
                "0",
                "1"
              ],
              "default": "1"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Letture di oggi con testo e link",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LettureGiorno"
                }
              }
            }
          },
          "404": {
            "description": "Letture di oggi non disponibili",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Errore"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/letture/prossima": {
      "get": {
        "tags": [
          "Liturgia"
        ],
        "summary": "Cerca prossimi giorni liturgici per criterio",
        "description": "Ricerca dichiarativa nel calendario liturgico: trova i prossimi giorni che soddisfano i criteri (colore, tipo di celebrazione, libro biblico nelle letture). Scansione giorno per giorno fino a `max_giorni`.",
        "operationId": "getLettureProssima",
        "parameters": [
          {
            "name": "colore",
            "in": "query",
            "required": false,
            "description": "Colore liturgico (bianco, rosso, verde, viola, rosa)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tipo",
            "in": "query",
            "required": false,
            "description": "Tipo di celebrazione (es. 'domenica', 'solennità', 'memoria')",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "libro",
            "in": "query",
            "required": false,
            "description": "Sigla del libro biblico presente nelle letture (es. gv, sal, is)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Numero massimo di risultati (default 3, max 20)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 20,
              "default": 3
            }
          },
          {
            "name": "max_giorni",
            "in": "query",
            "required": false,
            "description": "Giorni massimi da scandire (default 90, max 365)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 365,
              "default": 90
            }
          },
          {
            "name": "anno",
            "in": "query",
            "required": false,
            "description": "Anno di partenza (default: oggi)",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "mese",
            "in": "query",
            "required": false,
            "description": "Mese di partenza (default: oggi)",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "giorno",
            "in": "query",
            "required": false,
            "description": "Giorno di partenza (default: oggi)",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Giorni liturgici trovati",
            "content": {
              "application/json": {
                "example": {
                  "filtro": {
                    "colore": "rosso"
                  },
                  "da": "2026-03-16",
                  "trovati": 3,
                  "giorni": [
                    {
                      "data": "2026-03-19",
                      "celebrazione": "...",
                      "colore": "rosso",
                      "link": "https://parolaviva.art/liturgia/2026-03-19"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/letture/settimana": {
      "get": {
        "tags": [
          "Liturgia"
        ],
        "summary": "Letture della settimana",
        "description": "Restituisce le letture liturgiche per N giorni consecutivi (default 7, max 14) a partire dalla data specificata. Ogni giorno include celebrazione, colore, letture con link e lettura complementare.",
        "operationId": "getLettureSettimana",
        "parameters": [
          {
            "name": "anno",
            "in": "query",
            "required": true,
            "description": "Anno (es. 2026)",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "mese",
            "in": "query",
            "required": true,
            "description": "Mese (1-12)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 12
            }
          },
          {
            "name": "giorno",
            "in": "query",
            "required": true,
            "description": "Giorno (1-31)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 31
            }
          },
          {
            "name": "giorni",
            "in": "query",
            "required": false,
            "description": "Numero di giorni da restituire (default 7, max 14)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 14,
              "default": 7
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Array di giorni con letture",
            "content": {
              "application/json": {
                "example": {
                  "giorni": [
                    {
                      "data": "2026-03-16",
                      "celebrazione": "Lunedì della IV settimana di Quaresima",
                      "colore": "viola",
                      "letture": {},
                      "link": "https://parolaviva.art/liturgia/2026-03-16"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Parametri mancanti",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Errore"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/letture/{anno}/{data}.json": {
      "get": {
        "tags": [
          "Liturgia"
        ],
        "summary": "Letture liturgiche del giorno",
        "description": "Restituisce le letture liturgiche del Rito Romano per un giorno specifico, con testo integrale dalla Bibbia Martini. Include la lettura complementare del [piano triennale](https://parolaviva.art/lettura-complementare) (a cura di Giovanni Novelli) nei giorni feriali.",
        "operationId": "getLettureGiorno",
        "parameters": [
          {
            "name": "anno",
            "in": "path",
            "required": true,
            "description": "Anno (disponibili: 2020–2030).",
            "schema": {
              "type": "integer"
            },
            "example": 2026
          },
          {
            "name": "data",
            "in": "path",
            "required": true,
            "description": "Data nel formato `MM-GG` (mese-giorno).",
            "schema": {
              "type": "string",
              "pattern": "^\\d{2}-\\d{2}$"
            },
            "example": "03-10"
          }
        ],
        "responses": {
          "200": {
            "description": "Letture del giorno",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LettureGiorno"
                }
              }
            }
          },
          "404": {
            "description": "Data non trovata",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Errore"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/liturgia/tempo": {
      "get": {
        "tags": [
          "Liturgia"
        ],
        "summary": "Tempo liturgico corrente",
        "description": "Restituisce il tempo liturgico del Rito Romano per una data. Include nome del tempo, colore, settimana, anno liturgico (A/B/C), prossima solennità e prossima domenica.",
        "operationId": "getTempoLiturgico",
        "parameters": [
          {
            "name": "anno",
            "in": "query",
            "required": true,
            "description": "Anno (es. 2026).",
            "schema": {
              "type": "integer",
              "minimum": 1583
            }
          },
          {
            "name": "mese",
            "in": "query",
            "required": false,
            "description": "Mese (1-12). Se omesso, usa oggi o 1 gennaio.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 12
            }
          },
          {
            "name": "giorno",
            "in": "query",
            "required": false,
            "description": "Giorno (1-31). Se omesso, usa oggi o 1 gennaio.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 31
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tempo liturgico con dettagli",
            "content": {
              "application/json": {
                "example": {
                  "data": "2026-03-16",
                  "anno_liturgico": "B",
                  "tempo": "quaresima",
                  "nome_tempo": "Quaresima",
                  "colore": "viola",
                  "inizio_tempo": "2026-02-18",
                  "fine_tempo": "2026-04-02",
                  "settimana": 4,
                  "prossima_solennita": {
                    "data": "2026-03-19",
                    "nome": "San Giuseppe, Sposo della Beata Vergine Maria",
                    "rango": 1,
                    "colore": "bianco"
                  },
                  "prossima_domenica": {
                    "data": "2026-03-22",
                    "nome": "IV Domenica di Quaresima"
                  },
                  "link": "https://parolaviva.art/liturgia/2026-03-16"
                }
              }
            }
          },
          "400": {
            "description": "Parametro anno mancante o non valido"
          }
        }
      }
    },
    "/api/v1/luoghi": {
      "get": {
        "tags": [
          "Luoghi"
        ],
        "summary": "Cerca luoghi biblici",
        "description": "Cerca tra i 47 luoghi biblici per nome o tag.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Nome o tag"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 200
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lista luoghi"
          }
        }
      }
    },
    "/api/v1/occasioni": {
      "get": {
        "tags": [
          "Occasioni"
        ],
        "summary": "Elenca occasioni liturgiche",
        "description": "Lista delle 12 occasioni liturgiche con letture bibliche associate.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 12,
              "maximum": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lista occasioni con letture"
          }
        }
      }
    },
    "/api/v1/paralleli/{sigla}/{capitolo}/{path}": {
      "get": {
        "tags": [
          "Catalogo"
        ],
        "summary": "Paralleli e correlazioni di un passo",
        "description": "Restituisce i paralleli autoriali, le correlazioni per tag (>= 2 tag comuni) e la navigazione intra-capitolo per un passo contemplativo pubblicato.",
        "operationId": "getParalleli",
        "parameters": [
          {
            "name": "sigla",
            "in": "path",
            "required": true,
            "description": "Sigla del libro biblico (es. gv, sal, gen)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "capitolo",
            "in": "path",
            "required": true,
            "description": "Numero del capitolo (es. 3, 22)",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "path",
            "in": "path",
            "required": true,
            "description": "Path del passo: versetto o range (es. 16, 1-6)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paralleli autoriali, correlazioni per tag e navigazione intra-capitolo",
            "content": {
              "application/json": {
                "example": {
                  "passo": {
                    "riferimento": "Gen 1,1-5",
                    "titolo": "Al principio creo' Dio il cielo e la terra",
                    "tema": "notte-stelle"
                  },
                  "paralleli_autoriali": [
                    {
                      "riferimento": "Pr 8,22-31",
                      "titolo": "La Sapienza presso Dio",
                      "link": "https://parolaviva.art/bibbia/pr/8/22-31"
                    }
                  ],
                  "correlazioni_tag": [],
                  "stesso_capitolo": []
                }
              }
            }
          },
          "404": {
            "description": "Passo non trovato nel catalogo"
          }
        }
      }
    },
    "/api/v1/passi-famosi": {
      "get": {
        "tags": [
          "Passi Famosi"
        ],
        "summary": "Cerca passi biblici famosi",
        "description": "Cerca tra 288 passi biblici famosi curati. Filtra per tema, libro, tag o testo libero.",
        "parameters": [
          {
            "name": "tema",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Tema sacro (es. 'luce-oro', 'giardino')"
          },
          {
            "name": "libro",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Sigla libro (es. 'gv', 'sal')"
          },
          {
            "name": "tag",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Tag (es. 'fede', 'amore')"
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Testo nel titolo"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 200
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lista passi famosi"
          }
        }
      }
    },
    "/api/v1/persone": {
      "get": {
        "tags": [
          "Persone"
        ],
        "summary": "Cerca persone bibliche",
        "description": "Cerca tra le 54 persone bibliche per nome o tag. Restituisce versetti chiave e link.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Nome o tag da cercare"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 200
            },
            "description": "Numero massimo risultati"
          }
        ],
        "responses": {
          "200": {
            "description": "Lista persone"
          }
        }
      }
    },
    "/api/v1/piani": {
      "get": {
        "tags": [
          "Piani"
        ],
        "summary": "Elenca piani di lettura",
        "description": "Lista dei piani di lettura biblica disponibili.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 10,
              "maximum": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lista piani di lettura"
          }
        }
      }
    },
    "/api/v1/piano": {
      "get": {
        "tags": [
          "Liturgia"
        ],
        "summary": "Piano di lettura del giorno",
        "description": "Restituisce le letture liturgiche e la lettura complementare per 1-7 giorni consecutivi. Con `include_text=1` risolve il testo integrale dei versetti per ogni lettura.",
        "operationId": "getPianoLettura",
        "parameters": [
          {
            "name": "data",
            "in": "query",
            "required": false,
            "description": "Data di partenza in formato ISO `YYYY-MM-DD` (default: oggi)",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "example": "2026-03-16"
          },
          {
            "name": "giorni",
            "in": "query",
            "required": false,
            "description": "Numero di giorni (default 1, max 7)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 7,
              "default": 1
            }
          },
          {
            "name": "include_text",
            "in": "query",
            "required": false,
            "description": "Se `1`, include il testo integrale dei versetti per ogni lettura. Default: `0`.",
            "schema": {
              "type": "string",
              "enum": [
                "0",
                "1"
              ],
              "default": "0"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Piano di lettura con letture liturgiche e complementare",
            "content": {
              "application/json": {
                "example": {
                  "data": "2026-03-16",
                  "celebrazione": "Lunedì...",
                  "colore": "viola",
                  "letture": {
                    "prima": {
                      "riferimento": "Is 65,17-21"
                    }
                  },
                  "complementare": {
                    "riferimento": "Es 28,1-43"
                  },
                  "link_piano": "https://parolaviva.art/piano/2026-03-16"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/riferimento": {
      "get": {
        "tags": [
          "Bibbia"
        ],
        "summary": "Risolvi un riferimento biblico",
        "description": "Dato un riferimento in formato umano (es. 'Gv 3,16', 'Gen 1,1-5', 'Sal 22'), restituisce il testo dei versetti con link. Accetta sigle Martini, CEI e nomi completi in italiano.",
        "operationId": "getRiferimento",
        "parameters": [
          {
            "name": "r",
            "in": "query",
            "required": true,
            "description": "Riferimento biblico in formato umano",
            "schema": {
              "type": "string"
            },
            "examples": {
              "singolo": {
                "value": "Gv 3,16",
                "summary": "Versetto singolo"
              },
              "range": {
                "value": "Gen 1,1-5",
                "summary": "Range di versetti"
              },
              "capitolo": {
                "value": "Sal 22",
                "summary": "Capitolo intero"
              },
              "nome_esteso": {
                "value": "Genesi 1,1-5",
                "summary": "Nome completo"
              }
            }
          },
          {
            "name": "contesto",
            "in": "query",
            "required": false,
            "description": "Numero di versetti di contesto prima/dopo il range richiesto (1-10). Aggiunge `contesto_versetti` e `target` alla risposta.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10
            },
            "example": 3
          }
        ],
        "responses": {
          "200": {
            "description": "Versetti richiesti con metadati e link",
            "content": {
              "application/json": {
                "example": {
                  "libro": "Gv",
                  "capitolo": 3,
                  "riferimento": "Gv 3,16",
                  "versetti": [
                    {
                      "n": 16,
                      "t": "Imperocchè Iddio ha talmente amato il mondo..."
                    }
                  ],
                  "link": "https://parolaviva.art/bibbia/gv/3/16"
                }
              }
            }
          },
          "400": {
            "description": "Riferimento non valido o parametro mancante"
          },
          "404": {
            "description": "Libro o capitolo non trovato"
          }
        }
      }
    },
    "/api/v1/sezioni": {
      "get": {
        "tags": [
          "Bibbia"
        ],
        "summary": "Elenco delle sezioni bibliche",
        "description": "Restituisce le 7 sezioni della Bibbia (pentateuco, storici, sapienziali, profeti, vangeli_atti, lettere, apocalisse) con le sigle dei libri contenuti.",
        "operationId": "getSezioni",
        "responses": {
          "200": {
            "description": "Mappa sezione → sigle dei libri",
            "content": {
              "application/json": {
                "example": {
                  "sezioni": {
                    "pentateuco": [
                      "gen",
                      "es",
                      "lv",
                      "nm",
                      "dt"
                    ],
                    "vangeli_atti": [
                      "mt",
                      "mc",
                      "lc",
                      "gv",
                      "at"
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/sezioni/{sezione}": {
      "get": {
        "tags": [
          "Bibbia"
        ],
        "summary": "Libri di una sezione biblica",
        "description": "Restituisce i libri di una sezione con nome completo, sigla e numero di capitoli. Sezioni valide: pentateuco, storici, sapienziali, profeti, vangeli_atti, lettere, apocalisse.",
        "operationId": "getSezione",
        "parameters": [
          {
            "name": "sezione",
            "in": "path",
            "required": true,
            "description": "Nome della sezione",
            "schema": {
              "type": "string",
              "enum": [
                "pentateuco",
                "storici",
                "sapienziali",
                "profeti",
                "vangeli_atti",
                "lettere",
                "apocalisse"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Libri della sezione",
            "content": {
              "application/json": {
                "example": {
                  "sezione": "vangeli_atti",
                  "libri": [
                    {
                      "s": "mt",
                      "n": "Vangelo secondo Matteo",
                      "m": "Mt",
                      "c": 28
                    }
                  ],
                  "totale": 5
                }
              }
            }
          },
          "404": {
            "description": "Sezione non trovata",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Errore"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/simili/{sigla}/{capitolo}": {
      "get": {
        "tags": [
          "Similarità"
        ],
        "summary": "Capitoli semanticamente simili",
        "description": "Top-10 capitoli simili. Metodi: `combinato` (default, RRF), `tfidf` (lessicale), `embedding` (neurale MiniLM). Pre-calcolati su 1.334 capitoli, con punteggi e lemmi comuni.",
        "operationId": "getSimili",
        "parameters": [
          {
            "name": "sigla",
            "in": "path",
            "required": true,
            "description": "Sigla del libro (es. gen, gv, sal, is)",
            "schema": {
              "type": "string"
            },
            "example": "gen"
          },
          {
            "name": "capitolo",
            "in": "path",
            "required": true,
            "description": "Numero del capitolo",
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "example": 1
          },
          {
            "name": "metodo",
            "in": "query",
            "required": false,
            "description": "Metodo di similarità: `combinato` (default), `tfidf`, `embedding`.",
            "schema": {
              "type": "string",
              "enum": [
                "combinato",
                "tfidf",
                "embedding"
              ],
              "default": "combinato"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Top-10 capitoli simili con punteggi e lemmi comuni",
            "content": {
              "application/json": {
                "example": {
                  "sigla": "gen",
                  "capitolo": 1,
                  "riferimento": "Gen 1",
                  "metodo": "combinato",
                  "simili": [
                    {
                      "sigla": "gen",
                      "capitolo": 6,
                      "riferimento": "Gen 6",
                      "punteggio": 0.0325,
                      "punteggio_tfidf": 0.34,
                      "punteggio_embedding": 0.8,
                      "lemmi_comuni": [
                        "dio",
                        "terra",
                        "secondo",
                        "specie",
                        "uomo"
                      ]
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Metodo non valido"
          },
          "404": {
            "description": "Capitolo non trovato"
          }
        }
      }
    },
    "/api/v1/statistiche": {
      "get": {
        "tags": [
          "Catalogo"
        ],
        "summary": "Statistiche del corpus",
        "description": "Statistiche della Bibbia Martini (libri, capitoli, versetti per sezione) e dei passi contemplativi pubblicati (temi, tag frequenti, paralleli).",
        "operationId": "getStatistiche",
        "responses": {
          "200": {
            "description": "Statistiche del corpus biblico e contemplativo",
            "content": {
              "application/json": {
                "example": {
                  "bibbia": {
                    "traduzione": "Antonio Martini (1769–1781)",
                    "libri": 73,
                    "capitoli": 1334,
                    "versetti": 35714
                  },
                  "contemplativi": {
                    "passi_pubblicati": 6,
                    "temi_usati": [
                      "luce-oro",
                      "giardino"
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/catalogo.json": {
      "get": {
        "tags": [
          "Catalogo"
        ],
        "summary": "Catalogo dei passi contemplativi",
        "description": "Catalogo completo dei passi pubblicati su Parola Viva, con metadati, temi, tag e cross-reference.",
        "operationId": "getCatalogo",
        "responses": {
          "200": {
            "description": "Catalogo completo",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Catalogo"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Libro": {
        "type": "object",
        "description": "Un libro della Bibbia Martini.",
        "properties": {
          "s": {
            "type": "string",
            "description": "Sigla breve (usata negli URL)",
            "example": "gv"
          },
          "n": {
            "type": "string",
            "description": "Nome completo del libro",
            "example": "Vangelo secondo Giovanni"
          },
          "m": {
            "type": "string",
            "description": "Sigla formato Martini",
            "example": "Gv"
          },
          "c": {
            "type": "integer",
            "description": "Numero di capitoli",
            "example": 21
          }
        },
        "required": [
          "s",
          "n",
          "m",
          "c"
        ]
      },
      "Versetto": {
        "type": "object",
        "description": "Un versetto della Sacra Scrittura.",
        "properties": {
          "n": {
            "type": "integer",
            "description": "Numero del versetto",
            "example": 16
          },
          "t": {
            "type": "string",
            "description": "Testo del versetto (Bibbia Martini)",
            "example": "Imperocché Iddio ha talmente amato il mondo, che ha dato il suo unigenito Figliuolo..."
          }
        },
        "required": [
          "n",
          "t"
        ]
      },
      "Capitolo": {
        "type": "object",
        "description": "Un capitolo della Bibbia con tutti i suoi versetti.",
        "properties": {
          "l": {
            "type": "string",
            "description": "Sigla del libro",
            "example": "Gv"
          },
          "n": {
            "type": "string",
            "description": "Nome completo del libro",
            "example": "Vangelo secondo Giovanni"
          },
          "c": {
            "type": "integer",
            "description": "Numero del capitolo",
            "example": 3
          },
          "v": {
            "type": "array",
            "description": "Versetti del capitolo",
            "items": {
              "$ref": "#/components/schemas/Versetto"
            }
          }
        },
        "required": [
          "l",
          "n",
          "c",
          "v"
        ]
      },
      "Lettura": {
        "type": "object",
        "description": "Una lettura liturgica con riferimento biblico e testo.",
        "properties": {
          "riferimento": {
            "type": "string",
            "description": "Riferimento biblico",
            "example": "Gv 3,16-21"
          },
          "testo": {
            "type": "string",
            "description": "Testo integrale della lettura (Bibbia Martini)"
          }
        },
        "required": [
          "riferimento",
          "testo"
        ]
      },
      "LetturaComplementare": {
        "type": "object",
        "description": "Lettura del piano triennale di lettura integrale.",
        "properties": {
          "riferimento": {
            "type": "string",
            "description": "Riferimento biblico",
            "example": "Es 28,1-43"
          },
          "anno_piano": {
            "type": "string",
            "description": "Anno del ciclo triennale (A, B o C)",
            "enum": [
              "A",
              "B",
              "C"
            ],
            "example": "A"
          },
          "giorno_piano": {
            "type": "integer",
            "description": "Giorno nel piano annuale (1–313)",
            "example": 119
          },
          "testo": {
            "type": "string",
            "description": "Testo integrale (Bibbia Martini)"
          }
        },
        "required": [
          "riferimento",
          "anno_piano",
          "giorno_piano",
          "testo"
        ]
      },
      "LettureGiorno": {
        "type": "object",
        "description": "Letture liturgiche complete di un giorno.",
        "properties": {
          "data": {
            "type": "string",
            "format": "date",
            "description": "Data (YYYY-MM-DD)",
            "example": "2026-03-10"
          },
          "link": {
            "type": "string",
            "format": "uri",
            "description": "URL della pagina liturgica contemplativa",
            "example": "https://parolaviva.art/liturgia/2026-03-10"
          },
          "rito": {
            "type": "string",
            "description": "Rito liturgico",
            "example": "romano"
          },
          "celebrazione": {
            "type": "string",
            "description": "Nome della celebrazione",
            "example": "Martedì della III settimana di Quaresima"
          },
          "id_celebrazione": {
            "type": "string",
            "description": "Identificativo macchina della celebrazione",
            "example": "quaresima-3-mar"
          },
          "rango": {
            "type": "integer",
            "description": "Rango liturgico (1 = solennità, 13 = feria)",
            "example": 9
          },
          "colore": {
            "type": "string",
            "description": "Colore liturgico",
            "enum": [
              "bianco",
              "rosso",
              "verde",
              "viola",
              "rosa",
              "nero"
            ],
            "example": "viola"
          },
          "ciclo_domenicale": {
            "type": [
              "string",
              "null"
            ],
            "description": "Ciclo domenicale (A, B, C) o null per i feriali"
          },
          "ciclo_feriale": {
            "type": "integer",
            "description": "Ciclo feriale (1 o 2)",
            "example": 2
          },
          "letture": {
            "type": "object",
            "description": "Letture della Messa. Sempre presenti: prima, salmo, vangelo. Opzionale: seconda (solennità e domeniche), sequenza.",
            "properties": {
              "prima": {
                "$ref": "#/components/schemas/Lettura"
              },
              "salmo": {
                "$ref": "#/components/schemas/Lettura"
              },
              "seconda": {
                "$ref": "#/components/schemas/Lettura"
              },
              "sequenza": {
                "$ref": "#/components/schemas/Lettura"
              },
              "vangelo": {
                "$ref": "#/components/schemas/Lettura"
              }
            },
            "required": [
              "prima",
              "salmo",
              "vangelo"
            ]
          },
          "complementare": {
            "$ref": "#/components/schemas/LetturaComplementare"
          }
        },
        "required": [
          "data",
          "rito",
          "celebrazione",
          "colore",
          "rango",
          "letture"
        ]
      },
      "Catalogo": {
        "type": "object",
        "description": "Catalogo completo dei passi contemplativi.",
        "properties": {
          "meta": {
            "type": "object",
            "properties": {
              "titolo": {
                "type": "string"
              },
              "sottotitolo": {
                "type": "string"
              },
              "url_base": {
                "type": "string",
                "format": "uri"
              },
              "autore": {
                "type": "string"
              },
              "versione_catalogo": {
                "type": "string"
              }
            }
          },
          "temi": {
            "type": "object",
            "description": "Dizionario dei 10 temi sacri, indicizzati per ID.",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "nome": {
                  "type": "string"
                },
                "descrizione": {
                  "type": "string"
                },
                "palette": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "font_primario": {
                  "type": "string"
                },
                "font_secondario": {
                  "type": "string"
                }
              }
            }
          },
          "passi": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "sigla": {
                  "type": "string",
                  "description": "Sigla del libro biblico (es. gv, sal, gen)"
                },
                "capitolo": {
                  "type": "integer",
                  "description": "Numero del capitolo (es. 3, 22)"
                },
                "path": {
                  "type": "string",
                  "description": "Versetto o range (es. 16, 1-6)"
                },
                "riferimento": {
                  "type": "string",
                  "description": "Riferimento biblico leggibile"
                },
                "titolo": {
                  "type": "string"
                },
                "tema": {
                  "type": "string",
                  "description": "ID del tema"
                },
                "tags": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "paralleli": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "pubblicato": {
                  "type": "boolean"
                },
                "data": {
                  "type": "string",
                  "format": "date"
                }
              }
            }
          }
        }
      },
      "RisultatoRicerca": {
        "type": "object",
        "properties": {
          "risultati": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "riferimento": {
                  "type": "string",
                  "description": "Riferimento biblico (es. Gv 1,1)"
                },
                "testo": {
                  "type": "string",
                  "description": "Testo del versetto"
                }
              }
            }
          },
          "totale": {
            "type": "integer",
            "description": "Numero di risultati restituiti"
          }
        },
        "required": [
          "risultati",
          "totale"
        ]
      },
      "RisultatoFrequenze": {
        "type": "object",
        "properties": {
          "parole": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "parola": {
                  "type": "string",
                  "description": "Parola (normalizzata, minuscolo, senza accenti)"
                },
                "frequenza": {
                  "type": "integer",
                  "description": "Numero di occorrenze"
                }
              }
            },
            "description": "Parole ordinate per frequenza decrescente"
          },
          "totale_versetti": {
            "type": "integer",
            "description": "Numero di versetti analizzati"
          },
          "totale_parole_uniche": {
            "type": "integer",
            "description": "Numero di parole uniche restituite"
          },
          "query": {
            "type": "string",
            "description": "Query usata (presente solo in modalità query)"
          }
        },
        "required": [
          "parole",
          "totale_versetti",
          "totale_parole_uniche"
        ]
      },
      "Errore": {
        "type": "object",
        "properties": {
          "errore": {
            "type": "string",
            "description": "Messaggio di errore"
          }
        }
      }
    }
  }
}