{
  "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). 16 tools: `bible_get_index`, `bible_get_chapter`, `bible_search`, `bible_get_verses`, `bible_word_freq`, `bible_get_parallels`, `bible_get_random`, `bible_concordance`, `bible_vocabulary`, `bible_get_similar`, `liturgy_get_readings`, `liturgy_get_week`, `liturgy_get_season`, `liturgy_search_readings`, `project_stats`, `catalog_get`. Documentazione: [/opendata](https://parolaviva.art/opendata).",
    "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": "Feed", "description": "Feed Atom e JSON delle letture"},
    {"name": "Concordanza", "description": "Concordanza lemmatizzata della Bibbia Martini"},
    {"name": "Similarità", "description": "Similarità semantica tra capitoli della Bibbia Martini"}
  ],
  "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/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/letture/{dataISO}.json": {
      "get": {
        "tags": ["Liturgia"],
        "summary": "Letture liturgiche per data ISO",
        "description": "Alias dell'endpoint precedente con data in formato ISO (YYYY-MM-DD). Restituisce le stesse letture liturgiche con link alla pagina contemplativa.",
        "operationId": "getLettureGiornoISO",
        "parameters": [
          {
            "name": "dataISO",
            "in": "path",
            "required": true,
            "description": "Data in formato ISO `YYYY-MM-DD`.",
            "schema": {"type": "string", "format": "date"},
            "example": "2026-03-15"
          }
        ],
        "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/cerca/parole.json": {
      "get": {
        "tags": ["Ricerca"],
        "summary": "Indice parole per autocompletamento",
        "description": "Array JSON con tutte le parole distinte presenti nella Bibbia Martini, ordinate alfabeticamente. Utile per autocompletamento nei campi di ricerca. File statico, cache immutabile.",
        "operationId": "paroleIndice",
        "responses": {
          "200": {
            "description": "Elenco parole",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {"type": "string"},
                  "example": ["aaron", "aarone", "aaronne", "abba", "abbandona"]
                }
              }
            }
          }
        }
      }
    },
    "/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/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/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/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/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/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"]}
                }
              }
            }
          }
        }
      }
    },
    "/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/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/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.80,
                      "lemmi_comuni": ["dio", "terra", "secondo", "specie", "uomo"]
                    }
                  ]
                }
              }
            }
          },
          "400": {"description": "Metodo non valido"},
          "404": {"description": "Capitolo non trovato"}
        }
      }
    },
    "/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/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"}
        }
      }
    },
    "/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"}
              }
            }
          }
        }
      }
    },
    "/datapackage.json": {
      "get": {
        "tags": ["Catalogo"],
        "summary": "Manifesto Frictionless Data",
        "description": "Descrizione dei dataset secondo lo standard [Frictionless Data](https://specs.frictionlessdata.io/data-package/).",
        "operationId": "getDataPackage",
        "responses": {
          "200": {
            "description": "Data Package",
            "content": {
              "application/json": {}
            }
          }
        }
      }
    },
    "/feeds/letture.atom": {
      "get": {
        "tags": ["Feed"],
        "summary": "Feed Atom — letture liturgiche",
        "description": "Feed Atom 1.0 con le letture liturgiche del mese corrente, in ordine cronologico (dal 1° all'ultimo giorno del mese).",
        "operationId": "getFeedLettureAtom",
        "responses": {
          "200": {
            "description": "Feed Atom",
            "content": {
              "application/atom+xml": {}
            }
          }
        }
      }
    },
    "/feeds/letture.json": {
      "get": {
        "tags": ["Feed"],
        "summary": "Feed JSON — letture liturgiche",
        "description": "Feed JSON 1.1 con le letture liturgiche del mese corrente.",
        "operationId": "getFeedLettureJson",
        "responses": {
          "200": {
            "description": "JSON Feed 1.1",
            "content": {
              "application/feed+json": {}
            }
          }
        }
      }
    },
    "/feeds/complementare.atom": {
      "get": {
        "tags": ["Feed"],
        "summary": "Feed Atom — lettura complementare",
        "description": "Feed Atom 1.0 con le letture complementari del piano triennale (a cura di Giovanni Novelli) per il mese corrente.",
        "operationId": "getFeedComplementareAtom",
        "responses": {
          "200": {
            "description": "Feed Atom",
            "content": {
              "application/atom+xml": {}
            }
          }
        }
      }
    },
    "/feeds/complementare.json": {
      "get": {
        "tags": ["Feed"],
        "summary": "Feed JSON — lettura complementare",
        "description": "Feed JSON 1.1 con le letture complementari del piano triennale (a cura di Giovanni Novelli) per il mese corrente.",
        "operationId": "getFeedComplementareJson",
        "responses": {
          "200": {
            "description": "JSON Feed 1.1",
            "content": {
              "application/feed+json": {}
            }
          }
        }
      }
    }
  },
  "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"}
        }
      }
    }
  }
}