FASE 1: PROGETTAZIONE
→ Usa canvas API design per definire:
  - Chi usa l'API (stakeholder)
  - Cosa fa l'API (use cases)
  - Come funziona (risorse e operazioni)
  - Perché serve (obiettivi di business)

FASE 2: GENERAZIONE
→ Genera specifica OpenAPI basata sul canvas
→ Applica template ModI e pattern standard
→ Crea schemi dati preliminari

FASE 2.5: GENERAZIONE ESEMPI REQUEST/RESPONSE
→ Genera example/examples per ogni requestBody (POST, PUT, PATCH)
→ Genera example per ogni response 2xx con body
→ Genera examples multipli per operazioni con varianti (es. polling asincrono)
→ Verifica coerenza dati tra request e response
→ Usa valori realistici (nomi, codici, date italiane)

FASE 3: ARRICCHIMENTO SEMANTICO
→ Usa dati-semantic-mcp per:
  - Cercare ontologie rilevanti
  - Mappare entità a vocabolari controllati
  - Aggiungere annotazioni JSON-LD
  - Inserire riferimenti x-jsonld-*
  - IMPORTANTE: Usare sempre prefissi per compattare le URI (vedi sezione dedicata)
  - Se una proprietà/classe NON ha corrispondenza, suggerire alternative o estensioni custom
  - Se le descrizioni ontologiche sono assenti/povere, proporre descrizioni arricchite

FASE 3.5: VALIDAZIONE SEMANTICA VIA MCP (OBBLIGATORIA)
→ Per OGNI URI in x-jsonld-type: inspect_concept(uri) per verificare che esista
→ Per OGNI proprietà in x-jsonld-context: get_property_details(propertyUri) per verificare esistenza e domain/range
→ Per OGNI vocabolario controllato referenziato: list_vocabularies() per verificare che il ConceptScheme esista
→ Produrre report di validazione semantica:
  - URI verificate OK
  - URI inesistenti (da rimuovere o sostituire)
  - URI con domain/range incompatibile (da segnalare)
  - Gap semantici documentati

REGOLA CRITICA: Non usare MAI una URI ontologica copiata da un template
senza prima verificarla con schema-gov-it MCP.
I template in questa skill sono un PUNTO DI PARTENZA, non una fonte di verità.
La fonte di verità sono le ontologie accessibili via MCP.

Pattern di verifica per ogni mappatura:
1. search_concepts(keyword="nome proprietà")
2. Se trovata: get_property_details(propertyUri) per verificare domain/range
3. Se domain/range compatibili: usare nel context con prefisso
4. Se domain/range incompatibili: segnalare e cercare alternativa
5. Se non trovata: segnalare gap, cercare in ontologie alternative

FASE 4: VALIDAZIONE
→ Usa oas-checker-mcp per verificare:
  - Conformità ModI AgID
  - Pattern di sicurezza
  - Struttura e naming
  - Gestione errori

FASE 5: ITERAZIONE
→ Correggi problemi identificati
→ Ri-valida con oas-checker-mcp
→ Raffina annotazioni semantiche

FASE 6: GENERAZIONE ESEMPI JSON-LD
→ SOLO per schemi con x-jsonld-context contenente mappature di proprietà, genera:
  - {schema}.json: Risposta JSON standard (application/json)
  - {schema}.jsonld: Risposta JSON-LD con @context espanso (application/ld+json)
→ NON generare file .jsonld per schemi senza x-jsonld-context
→ Il @context nel file .jsonld DEVE includere tutti i prefissi e mappature
→ I file devono essere validi JSON e validabili con tool JSON-LD
→ Documentare gap semantici: proprietà nel .json che non appaiono nel .jsonld

FASE 6.5: VALIDAZIONE ESEMPI JSON-LD (eseguire via Bash)
→ Installare pyld se non presente: pip install pyld
→ Eseguire lo script di validazione nella cartella jsonld/:

```bash
# Creare venv se non esiste e installare pyld
test -d jsonld/.venv || (python3 -m venv jsonld/.venv && jsonld/.venv/bin/pip install -q pyld)

cd jsonld/ && .venv/bin/python3 -c "
from pyld import jsonld
import json, glob, sys
errors = 0
for f in sorted(glob.glob('*.jsonld')):
    try:
        with open(f) as fh:
            doc = json.load(fh)
        if '@context' not in doc:
            # Cerca context annidati (schemi compositi)
            has_nested = any('@context' in v for v in doc.values() if isinstance(v, dict))
            if not has_nested:
                print(f'SKIP {f}: nessun @context (non e JSON-LD)')
                continue
        expanded = jsonld.expand(doc)
        # Verifica che l'espansione produca URI (non stringhe nude)
        n_triples = sum(len(node.keys()) - (1 if '@type' in node else 0) for node in expanded) if expanded else 0
        print(f'OK   {f} ({len(expanded)} nodi, ~{n_triples} proprieta espanse)')
    except json.JSONDecodeError as e:
        print(f'ERR  {f}: JSON non valido - {e}')
        errors += 1
    except Exception as e:
        print(f'ERR  {f}: {e}')
        errors += 1
sys.exit(1 if errors else 0)
"

## Struttura del Documento OpenAPI

### 1. Metadati Obbligatori (info)

```yaml
openapi: 3.0.3
info:
  title: Nome dell'API
  version: 1.0.0
  description: |
    Descrizione dettagliata dell'API che include:
    - Scopo e contesto di utilizzo
    - Funzionalità principali
    - Link a documentazione aggiuntiva
  termsOfService: 'https://example.gov.it/terms/'
  contact:
    name: Nome Ufficio/Struttura
    url: 'https://example.gov.it'
    email: api@example.gov.it
  license:
    name: CC BY 4.0
    url: 'https://creativecommons.org/licenses/by/4.0/'
  x-summary: Breve descrizione (max 80 caratteri)
  x-api-id: identificativo-unico-api

servers:
  - url: 'https://api.example.gov.it/v1'
    description: Ambiente di produzione
  - url: 'https://api-test.example.gov.it/v1'
    description: Ambiente di test

GET    /documenti
GET    /documenti/{id-documento}
POST   /documenti
PUT    /documenti/{id-documento}
DELETE /documenti/{id-documento}
GET    /documenti/{id-documento}/allegati

❌ /getDocumenti
❌ /documento_list
❌ /Documenti
❌ /documenti/get/{id}

responses:
  '200':
    description: La richiesta è stata elaborata con successo
  '201':
    description: La risorsa è stata creata con successo
  '204':
    description: Operazione completata senza contenuto di ritorno
  '400':
    description: Richiesta non valida
    content:
      application/problem+json:
        schema:
          $ref: '#/components/schemas/Problem'
  '401':
    description: Non autenticato
  '403':
    description: Non autorizzato
  '404':
    description: Risorsa non trovata
  '429':
    description: Troppe richieste (rate limiting)
    headers:
      X-RateLimit-Limit:
        schema:
          type: integer
        description: Limite di richieste
      X-RateLimit-Remaining:
        schema:
          type: integer
        description: Richieste rimanenti
      Retry-After:
        schema:
          type: integer
        description: Secondi prima di riprovare
  '500':
    description: Errore interno del server
    content:
      application/problem+json:
        schema:
          $ref: '#/components/schemas/Problem'
  '503':
    description: Servizio temporaneamente non disponibile

components:
  schemas:
    Problem:
      type: object
      required:
        - status
        - title
      properties:
        type:
          type: string
          format: uri
          description: URI che identifica il tipo di problema
          example: 'https://example.gov.it/probs/validation-error'
        status:
          type: integer
          format: int32
          description: Codice di stato HTTP
          example: 400
        title:
          type: string
          description: Titolo del problema
          example: Richiesta non valida
        detail:
          type: string
          description: Descrizione dettagliata dell'errore
          example: Il campo 'codice_fiscale' non è valido
        instance:
          type: string
          format: uri
          description: URI dell'istanza specifica del problema
          example: '/documenti/123'

components:
  headers:
    X-Request-ID:
      description: Identificativo univoco della richiesta per tracciamento
      schema:
        type: string
        format: uuid
    X-Correlation-ID:
      description: Identificativo per correlare richieste multiple
      schema:
        type: string
        format: uuid
    X-RateLimit-Limit:
      description: Numero massimo di richieste consentite
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Numero di richieste rimanenti
      schema:
      type: integer

paths:
  /documenti:
    get:
      parameters:
        - name: limit
          in: query
          description: Numero massimo di elementi da restituire
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: offset
          in: query
          description: Numero di elementi da saltare
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: cursor
          in: query
          description: Cursore per paginazione (alternativo a offset)
          schema:
            type: string
      responses:
        '200':
          description: Lista documenti
          headers:
            Link:
              description: Link per navigazione (first, prev, next, last)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Documento'
                  count:
                    type: integer
                    description: Numero totale di elementi
                  limit:
                    type: integer
                  offset:
                    type: integer

parameters:
  - name: q
    in: query
    description: Testo di ricerca
    schema:
      type: string
  - name: stato
    in: query
    description: Filtro per stato
    schema:
      type: string
      enum: [BOZZA, PUBBLICATO, ARCHIVIATO]
  - name: data_da
    in: query
    description: Data inizio (ISO 8601)
    schema:
      type: string
      format: date
  - name: data_a
    in: query
    description: Data fine (ISO 8601)
    schema:
      type: string
      format: date
  - name: sort
    in: query
    description: Campo per ordinamento (+ ascendente, - discendente)
    schema:
      type: string
      example: "+data_creazione"

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        Token JWT per autenticazione.
        Include l'header Authorization: Bearer {token}

security:
  - bearerAuth: []

components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: 'https://auth.example.gov.it/oauth2/token'
          scopes:
            read:documenti: Lettura documenti
            write:documenti: Scrittura documenti

security:
  - oauth2: [read:documenti]

tags:
  - name: Documenti
    description: Operazioni sui documenti
    x-goal: Gestione del ciclo di vita dei documenti
  - name: Allegati
    description: Gestione degli allegati
    x-goal: Upload e download di file allegati

paths:
  /documenti:
    get:
      tags:
        - Documenti

# x-jsonld: nessuna corrispondenza ontologica (schema tecnico/infrastrutturale)
StatusResponse:
  type: object
  properties:
    status: {type: string}
    version: {type: string}
    uptime: {type: integer}

# x-jsonld: contenitore API, semantica delegata ai sotto-schemi
IscrizioneAlbo:
  type: object
  properties:
    professionista:
      $ref: '#/components/schemas/ProfessionistaSanitario'  # ha x-jsonld-context
    iscrizione:
      $ref: '#/components/schemas/DettaglioIscrizione'      # ha x-jsonld-context

components:
  schemas:
    Documento:
      type: object
      x-jsonld-context:
        # 1. Prefissi (definire TUTTI quelli necessari)
        CPV: 'https://w3id.org/italia/onto/CPV/'
        dct: 'http://purl.org/dc/terms/'
        foaf: 'http://xmlns.com/foaf/0.1/'
        dcat: 'http://www.w3.org/ns/dcat#'
        schema: 'http://schema.org/'
        # 2. Namespace di default e base risorse
        '@vocab': 'https://w3id.org/italia/onto/CPV/'
        '@base': 'https://api.example.gov.it/v1/documenti/'
        # 3. Alias strutturali
        id: '@id'
        type: '@type'
        # 4. Mappature proprietà con prefissi compatti
        titolo: 'dct:title'
        descrizione: 'dct:description'
        data-creazione: 'dct:created'
        data-modifica: 'dct:modified'
        formato: 'dct:format'
        identificativo: 'dct:identifier'
      properties:
        id:
          type: string
          format: uri
        titolo:
          type: string
        descrizione:
          type: string

Documento:
  type: object
  x-jsonld-type: 'dcat:Dataset'
  x-jsonld-context:
    dcat: 'http://www.w3.org/ns/dcat#'  # OBBLIGATORIO: definire il prefisso usato in x-jsonld-type
    '@vocab': 'https://w3id.org/italia/onto/CPV/'
  properties:
    # ...

Persona:
  type: object
  x-jsonld-type: 'CPV:Person'  # Usare CPV:Person per contesto PA italiana
  x-jsonld-context:
    # OBBLIGATORIO: definire TUTTI i prefissi usati in x-jsonld-type e nelle mappature
    CPV: 'https://w3id.org/italia/onto/CPV/'
    foaf: 'http://xmlns.com/foaf/0.1/'
    nome: 'CPV:givenName'     # proprietà nativa CPV (NON foaf:firstName)
    cognome: 'CPV:familyName' # proprietà nativa CPV (NON foaf:lastName)
    email: 'foaf:mbox'        # Gap CPV: nessuna email nativa, fallback foaf
  properties:
    nome: {type: string}
    cognome: {type: string}
    email: {type: string, format: email}

Organizzazione:
  type: object
  x-jsonld-type: 'http://www.w3.org/ns/org#Organization'  # URI completa: nessun prefisso da definire
  properties:
    nome: {type: string}
    codice-ipa: {type: string}

x-jsonld-context:
  '@vocab': 'https://w3id.org/italia/onto/CPV/'
  # Classi principali
  Persona: 'CPV:Person'
  Indirizzo: 'CLV:Address'  # Core Location Vocabulary
  Organizzazione: 'COV:Organization'
  Documento: 'CPV:Document'

x-jsonld-context:
  dcat: 'http://www.w3.org/ns/dcat#'
  dct: 'http://purl.org/dc/terms/'
  foaf: 'http://xmlns.com/foaf/0.1/'
  
Dataset:
  x-jsonld-type: 'dcat:Dataset'
  x-jsonld-context:
    titolo: 'dct:title'
    descrizione: 'dct:description'
    parole-chiave: 'dcat:keyword'
    temi: 'dcat:theme'
    editore: 'dct:publisher'
    contatto: 'dcat:contactPoint'
    distribuzione: 'dcat:distribution'

x-jsonld-context:
  schema: 'http://schema.org/'
  
Evento:
  x-jsonld-type: 'schema:Event'
  x-jsonld-context:
    nome: 'schema:name'
    descrizione: 'schema:description'
    data-inizio: 'schema:startDate'
    data-fine: 'schema:endDate'
    luogo: 'schema:location'

x-jsonld-context:
  # Prefissi per ontologie italiane
  CPV: 'https://w3id.org/italia/onto/CPV/'
  CLV: 'https://w3id.org/italia/onto/CLV/'
  COV: 'https://w3id.org/italia/onto/COV/'
  SM: 'https://w3id.org/italia/onto/SM/'
  TI: 'https://w3id.org/italia/onto/TI/'
  l0: 'https://w3id.org/italia/onto/l0/'
  # Prefissi per ontologie internazionali
  dct: 'http://purl.org/dc/terms/'
  dcat: 'http://www.w3.org/ns/dcat#'
  foaf: 'http://xmlns.com/foaf/0.1/'
  schema: 'http://schema.org/'
  org: 'http://www.w3.org/ns/org#'
  skos: 'http://www.w3.org/2004/02/skos/core#'
  xsd: 'http://www.w3.org/2001/XMLSchema#'
  # Prefisso base per le risorse dell'API
  '@base': 'https://api.example.gov.it/v1/'
  # Vocabolario di default (il più usato nello schema)
  '@vocab': 'https://w3id.org/italia/onto/CPV/'

x-jsonld-context:
  nome: 'https://w3id.org/italia/onto/CPV/givenName'
  cognome: 'https://w3id.org/italia/onto/CPV/familyName'
  indirizzo: 'https://w3id.org/italia/onto/CLV/hasAddress'
  organizzazione: 'https://w3id.org/italia/onto/COV/Organization'

x-jsonld-context:
  CPV: 'https://w3id.org/italia/onto/CPV/'
  CLV: 'https://w3id.org/italia/onto/CLV/'
  COV: 'https://w3id.org/italia/onto/COV/'
  nome: 'CPV:givenName'      # proprietà nativa CPV (NON foaf:givenName)
  cognome: 'CPV:familyName'  # proprietà nativa CPV (NON foaf:familyName)
  indirizzo: 'CLV:hasAddress'
  organizzazione: 'COV:Organization'

# Esempio: proprietà senza corrispondenza
numero-protocollo:
  type: string
  description: |
    Numero di protocollo dell'ente.
    NOTA SEMANTICA: Non esiste una proprietà standard nelle ontologie
    italiane per il numero di protocollo. Si suggerisce:
    - Opzione 1: usare dct:identifier con qualificatore
    - Opzione 2: proporre estensione a ontologia CPV
  # Mappatura provvisoria con best-effort
  # x-jsonld-mapping: 'dct:identifier' (approssimativa)

# Esempio: descrizione arricchita
codice-fiscale:
  type: string
  description: |
    Codice fiscale italiano della persona fisica.
    Identificativo univoco rilasciato dall'Agenzia delle Entrate.
    Formato: 16 caratteri alfanumerici (6 lettere + 2 cifre + 1 lettera
    + 2 cifre + 1 lettera + 3 cifre + 1 lettera di controllo).
    Riferimento ontologico: CPV:taxCode
    (l'ontologia non fornisce descrizione - questa è stata integrata)
  pattern: '^[A-Z]{6}[0-9]{2}[A-Z][0-9]{2}[A-Z][0-9]{3}[A-Z]$'

# Esempio: enum con suggerimento vocabolario
stato:
  type: string
  description: |
    Stato della pratica.
    NOTA: Non esiste un vocabolario controllato AgID specifico per
    gli stati delle pratiche edilizie. Si suggerisce di:
    1. Verificare periodicamente https://github.com/italia/daf-ontologie-vocabolari-controllati
    2. Proporre un vocabolario al repository nazionale
    3. Nel frattempo, usare la codifica locale documentata qui sotto
  enum: [BOZZA, PRESENTATA, IN_ISTRUTTORIA, APPROVATA, RESPINTA]

PER OGNI SCHEMA:
  1. Cerca tipo ontologico → Se trovato: usa x-jsonld-type
                            → Se NON trovato: suggerisci tipo più vicino + segnala gap

  2. PER OGNI PROPRIETÀ:
     a. Cerca mappatura ontologica → Se trovata: aggiungi al context con prefisso
                                   → Se NON trovata: suggerisci alternativa
     b. Verifica description ontologica → Se buona: citala
                                        → Se assente/povera: proponi descrizione arricchita
     c. Se è un enum: cerca vocabolario controllato → Se trovato: referenzia con URI + prefisso
                                                    → Se NON trovato: segnala e suggerisci

  3. Genera report di copertura semantica:
     - N proprietà mappate / N totali
     - N gap identificati con suggerimenti
     - N descrizioni arricchite

Persona:
  type: object
  x-jsonld-type: 'CPV:Person'
  x-jsonld-context:
    '@vocab': 'https://w3id.org/italia/onto/CPV/'
    foaf: 'http://xmlns.com/foaf/0.1/'
    # Mappature verificate via MCP schema-gov-it
    nome: 'CPV:givenName'       # DatatypeProperty, domain: CPV:Person, range: xsd:string
    cognome: 'CPV:familyName'   # DatatypeProperty (Functional), domain: CPV:Person, range: xsd:string
    codice-fiscale: 'CPV:taxCode'
    data-nascita: 'CPV:dateOfBirth'  # DatatypeProperty (Functional), domain: CPV:Person, range: xsd:dateTime
    email: 'foaf:mbox'          # Gap CPV: nessuna proprietà email nativa
    telefono: 'foaf:phone'      # Gap CPV: nessuna proprietà telefono nativa
  required: [codice-fiscale, nome, cognome]
  properties:
    codice-fiscale:
      type: string
      pattern: '^[A-Z]{6}[0-9]{2}[A-Z][0-9]{2}[A-Z][0-9]{3}[A-Z]$'
    nome: {type: string}
    cognome: {type: string}
    data-nascita: {type: string, format: date}
    email: {type: string, format: email}
    telefono: {type: string}

Indirizzo:
  type: object
  x-jsonld-type: 'CLV:Address'
  x-jsonld-context:
    '@vocab': 'https://w3id.org/italia/onto/CLV/'
    # Mappature verificate via MCP schema-gov-it
    via: 'CLV:fullAddress'     # DatatypeProperty (Functional), domain: CLV:Address, range: Literal
    civico: 'CLV:hasNumber'    # ObjectProperty, domain: CLV:Address, range: CLV:CivicNumbering
    # cap: GAP SEMANTICO - CLV:postCode NON ESISTE nell'ontologia CLV
    comune: 'CLV:hasCity'      # ObjectProperty, domain: CLV:Address, range: CLV:City
    provincia: 'CLV:hasProvince'  # ObjectProperty, range: CLV:Province (NON stringa)
    regione: 'CLV:hasRegion'   # ObjectProperty, range: CLV:Region (NON stringa)
  properties:
    via: {type: string}
    civico: {type: string}
    cap:
      type: string
      pattern: '^\d{5}$'
      description: 'GAP SEMANTICO: CLV:postCode non esiste in CLV. Nessuna mappatura ontologica.'
    comune: {type: string}
    provincia: {type: string, minLength: 2, maxLength: 2}
    regione: {type: string}

Organizzazione:
  type: object
  x-jsonld-type: 'COV:Organization'
  x-jsonld-context:
    '@vocab': 'https://w3id.org/italia/onto/COV/'
    CLV: 'https://w3id.org/italia/onto/CLV/'
    SM: 'https://w3id.org/italia/onto/SM/'
    # Mappature verificate via MCP schema-gov-it
    nome: 'COV:legalName'      # DatatypeProperty, domain: COV:Organization, range: Literal
    codice-ipa: 'COV:IPAcode'
    partita-iva: 'COV:VATnumber'  # DatatypeProperty (Functional), domain: COV:PrivateOrganization, range: Literal
    # NOTA: COV:taxCode è il codice fiscale dell'organizzazione, NON la partita IVA!
    # email: GAP SEMANTICO - COV:email NON ESISTE. Alternativa: SM:emailAddress (domain: SM:Email)
    # pec: GAP SEMANTICO - COV:pec NON ESISTE. Nessuna proprietà standard per PEC in COV.
    indirizzo: 'CLV:hasAddress'
  properties:
    nome: {type: string}
    codice-ipa:
      type: string
      pattern: '^[a-z0-9_]+$'
    partita-iva:
      type: string
      pattern: '^\d{11}$'
    email:
      type: string
      format: email
      description: 'GAP SEMANTICO: COV:email non esiste. Alternativa: SM:emailAddress (domain SM:Email).'
    pec:
      type: string
      format: email
      description: 'GAP SEMANTICO: COV:pec non esiste. Nessuna proprietà standard per PEC nelle ontologie nazionali.'
    indirizzo:
      $ref: '#/components/schemas/Indirizzo'

DocumentoAmministrativo:
  type: object
  x-jsonld-type: 'CPV:Document'
  x-jsonld-context:
    '@vocab': 'https://w3id.org/italia/onto/CPV/'
    dct: 'http://purl.org/dc/terms/'
    foaf: 'http://xmlns.com/foaf/0.1/'
    identificativo: 'dct:identifier'
    titolo: 'dct:title'
    descrizione: 'dct:description'
    tipo: 'dct:type'
    formato: 'dct:format'
    data-creazione: 'dct:created'
    data-modifica: 'dct:modified'
    autore: 'dct:creator'
    editore: 'dct:publisher'
    soggetto: 'dct:subject'
    classificazione: 'CPV:hasClassification'
  properties:
    identificativo: {type: string}
    titolo: {type: string}
    descrizione: {type: string}
    tipo:
      type: string
      enum: [DELIBERA, DETERMINA, ORDINANZA, DECRETO]
    numero-protocollo: {type: string}
    data-protocollo: {type: string, format: date-time}

Pratica:
  type: object
  x-jsonld-type: 'https://w3id.org/italia/onto/CPV/Procedure'
  x-jsonld-context:
    '@vocab': 'https://w3id.org/italia/onto/CPV/'
    dct: 'http://purl.org/dc/terms/'
    numero: 'dct:identifier'
    oggetto: 'dct:title'
    descrizione: 'dct:description'
    stato: 'CPV:hasStatus'
    data-apertura: 'CPV:startDate'
    data-chiusura: 'CPV:endDate'
    responsabile: 'CPV:hasResponsible'
  properties:
    numero: {type: string}
    oggetto: {type: string}
    descrizione: {type: string}
    stato:
      type: string
      enum: [APERTA, IN_LAVORAZIONE, SOSPESA, CONCLUSA]
    data-apertura: {type: string, format: date-time}
    data-chiusura: {type: string, format: date-time}

components:
  schemas:
    # Persona con pieno supporto Linked Data
    PersonaCompleta:
      type: object
      description: |
        Persona fisica con mappatura completa a ontologie nazionali.
        Conforme a CPV (Core Vocabulary Pubbliche Amministrazioni).
      x-jsonld-type: 'https://w3id.org/italia/onto/CPV/Person'
      x-jsonld-context:
        '@vocab': 'https://w3id.org/italia/onto/CPV/'
        '@base': 'https://api.example.gov.it/persone/'
        foaf: 'http://xmlns.com/foaf/0.1/'
        xsd: 'http://www.w3.org/2001/XMLSchema#'
        # Mappature verificate via MCP schema-gov-it
        id: '@id'
        type: '@type'
        codice-fiscale:
          '@id': 'CPV:taxCode'
          '@type': 'xsd:string'
        nome:
          '@id': 'CPV:givenName'  # DatatypeProperty, domain: CPV:Person, range: xsd:string
          '@language': 'it'
        cognome:
          '@id': 'CPV:familyName'  # DatatypeProperty (Functional), domain: CPV:Person, range: xsd:string
          '@language': 'it'
        data-nascita:
          '@id': 'CPV:dateOfBirth'  # DatatypeProperty (Functional), domain: CPV:Person, range: xsd:dateTime
          '@type': 'xsd:date'
        luogo-nascita:
          '@id': 'CPV:hasBirthPlace'  # ObjectProperty, range: l0:Location - OK
          '@type': '@id'
        residenza:
          '@id': 'CPV:hasResidenceInTime'  # ObjectProperty, domain: CPV:Person, range: CPV:ResidenceInTime
          '@type': '@id'
        cittadinanza:
          '@id': 'CPV:hasCitizenship'
          '@type': '@id'
        contatti:
          '@id': 'CPV:hasContactPoint'
          '@container': '@set'
      required:
        - codice-fiscale
        - nome
        - cognome
      properties:
        id:
          type: string
          format: uri
          readOnly: true
          example: 'https://api.example.gov.it/persone/RSSMRA85M01H501U'
        codice-fiscale:
          type: string
          pattern: '^[A-Z]{6}[0-9]{2}[A-Z][0-9]{2}[A-Z][0-9]{3}[A-Z]$'
          example: 'RSSMRA85M01H501U'
        nome:
          type: string
          minLength: 1
          maxLength: 100
          example: 'Mario'
        cognome:
          type: string
          minLength: 1
          maxLength: 100
          example: 'Rossi'
        data-nascita:
          type: string
          format: date
          example: '1985-08-01'
        luogo-nascita:
          $ref: '#/components/schemas/Comune'
        residenza:
          $ref: '#/components/schemas/Indirizzo'
        cittadinanza:
          type: string
          description: Codice ISO 3166-1 alpha-2 della nazione
          pattern: '^[A-Z]{2}$'
          example: 'IT'
        contatti:
          type: array
          items:
            $ref: '#/components/schemas/Contatto'

components:
  schemas:
    Timestamp:
      type: string
      format: date-time
      description: Timestamp in formato ISO 8601
      example: '2024-02-10T14:30:00Z'
    
    CodiceFiscale:
      type: string
      pattern: '^[A-Z]{6}[0-9]{2}[A-Z][0-9]{2}[A-Z][0-9]{3}[A-Z]$'
      description: Codice fiscale italiano
      example: 'RSSMRA85M01H501U'
    
    PartitaIVA:
      type: string
      pattern: '^[0-9]{11}$'
      description: Partita IVA italiana
      example: '12345678901'
    
    IPA:
      type: string
      pattern: '^[a-z0-9_]+$'
      description: Codice IPA dell'ente
      example: 'comune_roma'

paths:
  /status:
    get:
      summary: Verifica stato del servizio
      description: Endpoint per monitoraggio e health check
      tags:
        - System
      responses:
        '200':
          description: Servizio operativo
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum: [OK, DEGRADED, DOWN]
                  version:
                    type: string
                  timestamp:
                    type: string
                    format: date-time
        '503':
          description: Servizio non disponibile

components:
  schemas:
    Documento:
      type: object
      description: |
        Rappresenta un documento amministrativo.
        Conforme al vocabolario DCAT-AP_IT.
      required:
        - id
        - titolo
        - tipo
      properties:
        id:
          type: string
          format: uuid
          description: Identificativo univoco del documento
          example: '550e8400-e29b-41d4-a716-446655440000'
        titolo:
          type: string
          minLength: 1
          maxLength: 500
          description: Titolo del documento
          example: 'Delibera di Giunta n. 123/2024'
        tipo:
          type: string
          description: Tipologia documento secondo classificazione AGID
          enum:
            - DELIBERA
            - DETERMINA
            - ORDINANZA
            - DECRETO
          example: DELIBERA
        data_protocollo:
          $ref: '#/components/schemas/Timestamp'
        numero_protocollo:
          type: string
          pattern: '^\d{4}/\d{7}$'
          description: Numero di protocollo nel formato ANNO/NUMERO
          example: '2024/0001234'

paths:
  /calcola-imposte:
    post:
      summary: Calcolo imposte
      operationId: calcolaImposte
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RichiestaCalcolo'
      responses:
        '200':
          description: Calcolo completato
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RisultatoCalcolo'
        '400':
          $ref: '#/components/responses/BadRequest'

paths:
  /elaborazioni:
    post:
      summary: Avvia elaborazione asincrona
      operationId: avviaElaborazione
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RichiestaElaborazione'
      responses:
        '202':
          description: Elaborazione avviata
          headers:
            Location:
              description: URL per verificare lo stato
              schema:
                type: string
                format: uri
          content:
            application/json:
              schema:
                type: object
                properties:
                  id_elaborazione:
                    type: string
                    format: uuid
                  stato:
                    type: string
                    enum: [IN_CORSO, COMPLETATA, ERRORE]
                  link_stato:
                    type: string
                    format: uri
  
  /elaborazioni/{id}:
    get:
      summary: Verifica stato elaborazione
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Stato elaborazione
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  stato:
                    type: string
                    enum: [IN_CORSO, COMPLETATA, ERRORE]
                  progresso:
                    type: integer
                    minimum: 0
                    maximum: 100
                  risultato:
                    description: Presente solo se stato=COMPLETATA
                    $ref: '#/components/schemas/RisultatoElaborazione'
                  errore:
                    description: Presente solo se stato=ERRORE
                    $ref: '#/components/schemas/Problem'

paths:
  /api-resource:
    get:
      responses:
        '200':
          headers:
            X-RateLimit-Limit:
              description: Numero massimo di richieste per finestra temporale
              schema:
                type: integer
              example: 1000
            X-RateLimit-Remaining:
              description: Richieste rimanenti nella finestra corrente
              schema:
                type: integer
              example: 750
            X-RateLimit-Reset:
              description: Timestamp Unix del reset del contatore
              schema:
                type: integer
              example: 1707577200

paths:
  /documenti/{id}:
    get:
      parameters:
        - name: Accept
          in: header
          schema:
            type: string
            enum:
              - application/json
              - application/xml
              - application/pdf
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Documento'
            application/xml:
              schema:
                $ref: '#/components/schemas/Documento'
            application/pdf:
              schema:
                type: string
                format: binary

# Da configurare a livello server, non nella specifica OpenAPI
# ma documentare i requisiti:
info:
  description: |
    ## Requisiti CORS
    L'API supporta CORS con le seguenti configurazioni:
    - Access-Control-Allow-Origin: domini autorizzati
    - Access-Control-Allow-Methods: GET, POST, PUT, DELETE
    - Access-Control-Allow-Headers: Authorization, Content-Type, X-Request-ID
    - Access-Control-Max-Age: 3600

openapi: 3.0.3
info:
  title: API [Nome Servizio]
  version: 1.0.0
  description: |
    Descrizione dettagliata dell'API.
    
    ## Scopo
    [Spiegare lo scopo dell'API]
    
    ## Funzionalità
    - Funzionalità 1
    - Funzionalità 2
    
    ## Documentazione
    - [Link documentazione estesa]
  contact:
    name: [Nome Ufficio]
    email: [email]@[ente].gov.it
    url: https://[ente].gov.it
  license:
    name: CC BY 4.0
    url: https://creativecommons.org/licenses/by/4.0/
  x-api-id: [identificativo-univoco]
  x-summary: [Descrizione breve max 80 caratteri]

servers:
  - url: https://api.[ente].gov.it/v1
    description: Produzione
  - url: https://api-test.[ente].gov.it/v1
    description: Test

tags:
  - name: [Categoria1]
    description: [Descrizione categoria]
    x-goal: [Obiettivo funzionale]

paths:
  /status:
    get:
      summary: Health check
      operationId: getStatus
      tags:
        - System
      responses:
        '200':
          description: Servizio operativo
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '503':
          description: Servizio non disponibile

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Token JWT per autenticazione

  schemas:
    Problem:
      type: object
      required:
        - status
        - title
      properties:
        type:
          type: string
          format: uri
        status:
          type: integer
          format: int32
        title:
          type: string
        detail:
          type: string
        instance:
          type: string
          format: uri

    StatusResponse:
      type: object
      properties:
        status:
          type: string
          enum: [OK, DEGRADED, DOWN]
        version:
          type: string
        timestamp:
          type: string
          format: date-time

  responses:
    BadRequest:
      description: Richiesta non valida
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    
    Unauthorized:
      description: Non autenticato
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    
    Forbidden:
      description: Non autorizzato
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    
    NotFound:
      description: Risorsa non trovata
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    
    TooManyRequests:
      description: Troppe richieste
      headers:
        X-RateLimit-Limit:
          schema:
            type: integer
        X-RateLimit-Remaining:
          schema:
            type: integer
        Retry-After:
          schema:
            type: integer
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    
    InternalServerError:
      description: Errore interno del server
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'

security:
  - bearerAuth: []

🎯 OBIETTIVO API
- Qual è lo scopo principale di questa API?
- Quali problemi risolve?

👥 STAKEHOLDER
- Chi userà questa API? (cittadini, imprese, altre PA)
- Quali permessi servono per accedere?

📋 CASI D'USO PRINCIPALI (3-5)
1. [Attore] vuole [azione] per [scopo]
2. ...

🗂️ RISORSE PRINCIPALI
- Risorsa 1: [nome] (es: Documenti)
  - GET: elenco con filtri
  - POST: creazione
  - GET /{id}: dettaglio
  - PUT /{id}: aggiornamento
  - DELETE /{id}: eliminazione

📊 DATI INPUT/OUTPUT
- Quali dati sono necessari in input?
- Quali dati vengono restituiti?
- Ci sono vincoli di validazione?

🔒 REQUISITI SICUREZZA
- Autenticazione: JWT / OAuth2 / mTLS?
- Autorizzazione: ruoli, ACL?
- Dati sensibili: quali e come proteggerli?

⚡ REQUISITI NON FUNZIONALI
- Volumi attesi: richieste/giorno?
- Tempi di risposta: sincrono (<1s) / asincrono?
- Rate limiting: necessario?
- Disponibilità richiesta: 99.9%?

# LOG - [Nome API]

## Metadata
- **File**: `nome-file.yaml`
- **Data generazione/modifica**: YYYY-MM-DD
- **Versione API**: X.Y.Z
- **Azione**: Creazione | Modifica | Arricchimento semantico

## Riepilogo Processo

### Fasi completate
- [ ] FASE 1: Progettazione (API Canvas)
- [ ] FASE 2: Generazione specifica OpenAPI
- [ ] FASE 2.5: Generazione esempi request/response
- [ ] FASE 3: Arricchimento semantico
- [ ] FASE 3.5: Validazione semantica via MCP
- [ ] FASE 4: Validazione oas-checker
- [ ] FASE 5: Iterazione e raffinamento

### Decisioni di design
[Elencare le scelte architetturali fatte, es. pattern sincrono vs asincrono,
schema di autenticazione scelto, struttura delle risorse]

## Report Semantico

### Ontologie utilizzate
| Prefisso | URI | Uso |
|----------|-----|-----|
| CPV | `https://w3id.org/italia/onto/CPV/` | Persone, documenti |
| CLV | `https://w3id.org/italia/onto/CLV/` | Indirizzi, luoghi |
| ... | ... | ... |

### Copertura semantica per schema
| Schema | Proprietà totali | Mappate | Gap | Copertura |
|--------|-----------------|---------|-----|-----------|
| Persona | 10 | 8 | 2 | 80% |
| Indirizzo | 7 | 5 | 2 | 71% |
| ... | ... | ... | ... | ... |

### Mappature verificate via MCP
| Proprietà | Mappatura | Verifica |
|-----------|-----------|----------|
| nome → CPV:givenName | domain: CPV:Person, range: xsd:string | OK |
| cap → ??? | CLV:postCode non esiste | GAP |
| ... | ... | ... |

### Gap semantici identificati
| Proprietà | Schema | Ontologia attesa | Stato | Suggerimento |
|-----------|--------|-----------------|-------|-------------|
| cap | Indirizzo | CLV | ASSENTE | Nessuna alternativa trovata |
| email | Persona | CPV | GAP | Fallback foaf:mbox |
| ... | ... | ... | ... | ... |

### Vocabolari controllati
| Campo enum | Vocabolario AgID | Stato |
|-----------|-----------------|-------|
| tipo-documento | [trovato/non trovato] | [dettaglio] |
| stato-civile | Non disponibile | Gap segnalato |

## Come Ampliare le Semantiche

### Aggiungere un nuovo schema con semantica

1. **Identificare il tipo ontologico**:

Se trovato → aggiungere `x-jsonld-type`
Se non trovato → documentare il gap nel LOG

2. **Mappare le proprietà**:

Verificare domain/range compatibili prima di inserire nel context

3. **Aggiungere il context JSON-LD**:
- Definire PRIMA i prefissi necessari
- Impostare `@vocab` sul namespace dominante
- Mappare con notazione compatta `prefisso:nome`

### Modificare una mappatura esistente

1. **Verificare la mappatura corrente** con MCP:

2. **Cercare alternative**:

3. **Aggiornare** il context nello schema YAML
4. **Aggiornare** questo LOG con la nuova mappatura e il motivo del cambio

### Aggiungere un vocabolario controllato

1. **Cercare vocabolari esistenti**:

2. Se trovato: referenziare con URI e codice `skos:notation`
3. Se non trovato: documentare il gap, proporre codifica locale

### Colmare un gap semantico

Per ogni gap elencato sopra, le opzioni sono:
1. **Cercare in ontologie alternative**: schema.org, Dublin Core, FOAF, W3C org
2. **Proporre estensione**: suggerire proprietà al repository
`https://github.com/italia/daf-ontologie-vocabolari-controllati`
3. **Usare mappatura approssimativa**: con nota esplicita nel description
4. **Creare URI custom**: `https://w3id.org/italia/onto/{Ontologia}/{Nome}`
(solo come ultima risorsa, documentando la proposta)

### Ontologie e tool MCP di riferimento

| Cosa cerco | Tool MCP da usare |
|-----------|------------------|
| Classe/tipo di un'entità | `search_concepts(keyword)` → `inspect_concept(uri)` |
| Proprietà di un'ontologia | `list_properties(ontologyUri)` |
| Dettaglio proprietà | `get_property_details(propertyUri)` |
| Vocabolario controllato | `list_vocabularies()` → `browse_vocabulary(schemeUri, keyword)` |
| Relazione tra concetti | `find_relations(sourceUri, targetUri)` |
| Lista ontologie disponibili | `list_ontologies()` → `explore_ontology(ontologyUri)` |
| Comuni/province | `list_municipalities(keyword)` / `list_provinces(keyword)` |

## Storico modifiche

| Data | Azione | Dettaglio |
|------|--------|----------|
| YYYY-MM-DD | Creazione | Generazione iniziale specifica |

api-spec.yaml
jsonld/
├── README.md           # Documentazione mappature e gap semantici
├── persona.json        # Risposta JSON standard
├── persona.jsonld      # Risposta JSON-LD con @context
├── documento.json
└── documento.jsonld

{
  "id": "https://api.example.gov.it/persone/RSSMRA85M01H501U",
  "codice-fiscale": "RSSMRA85M01H501U",
  "nome": "Mario",
  "cognome": "Rossi",
  "stato-civile": "CELIBE_NUBILE"
}

{
  "@context": {
    "@vocab": "https://w3id.org/italia/onto/CPV/",
    "@base": "https://api.example.gov.it/persone/",
    "CPV": "https://w3id.org/italia/onto/CPV/",
    "xsd": "http://www.w3.org/2001/XMLSchema#",
    "id": "@id",
    "codice-fiscale": { "@id": "CPV:taxCode", "@type": "xsd:string" },
    "nome": { "@id": "CPV:givenName", "@language": "it" },
    "cognome": { "@id": "CPV:familyName", "@language": "it" }
  },
  "@type": "CPV:Person",
  "id": "https://api.example.gov.it/persone/RSSMRA85M01H501U",
  "codice-fiscale": "RSSMRA85M01H501U",
  "nome": "Mario",
  "cognome": "Rossi"
}

# x-jsonld: nessuna corrispondenza ontologica (schema tecnico/infrastrutturale)
StatusResponse:
  type: object
  properties:
    status: {type: string}

# Creare venv se non esiste e installare pyld (una tantum)
test -d jsonld/.venv || (python3 -m venv jsonld/.venv && jsonld/.venv/bin/pip install -q pyld)

# Validazione batch di tutti i file .jsonld nella cartella
cd jsonld/ && .venv/bin/python3 -c "
from pyld import jsonld
import json, glob, sys
errors = 0
for f in sorted(glob.glob('*.jsonld')):
    try:
        with open(f) as fh:
            doc = json.load(fh)
        if '@context' not in doc:
            has_nested = any('@context' in v for v in doc.values() if isinstance(v, dict))
            if not has_nested:
                print(f'SKIP {f}: nessun @context (non e JSON-LD)')
                continue
        expanded = jsonld.expand(doc)
        n_triples = sum(len(node.keys()) - (1 if '@type' in node else 0) for node in expanded) if expanded else 0
        print(f'OK   {f} ({len(expanded)} nodi, ~{n_triples} proprieta espanse)')
    except json.JSONDecodeError as e:
        print(f'ERR  {f}: JSON non valido - {e}')
        errors += 1
    except Exception as e:
        print(f'ERR  {f}: {e}')
        errors += 1
sys.exit(1 if errors else 0)
"

OK   dettaglio-iscrizione.jsonld (1 nodi, ~2 proprieta espanse)
OK   iscrizione-albo.jsonld (2 nodi, ~6 proprieta espanse)
OK   professionista-sanitario.jsonld (1 nodi, ~4 proprieta espanse)