tolto catalog, aggiunto esempi, completato entity

panorama.yaml

@@ -10,7 +10,7 @@ info:
     name: API Support
     email: support@panorama.edisonnext.it
 
-  version: 0.9.1
+  version: 0.9.2
   
   license:
     name: © 2025 - 2030 Copyright Edison Next Spa. All rights reserved
@@ -32,10 +32,10 @@ security:
 #  - url: <Here development API server>
 #    description: Development API server
 tags:
+  - name: Data Source
+    description: operations for data sources
   - name: Type
     description: operations for data types
-  - name: Data Catalog
-    description: operations for data catalogs
   - name: Entity Browse
     description: operations to browse entities and their state
   - name: Entity
@@ -115,21 +115,10 @@ paths:
       summary: Elimina un Tipo (senza istanze di elementi) esistente (admin only)
       tags: [Type]
 
-  /catalog:
+  /source:
     get:
-      summary: Restituisce i Cataloghi disponibili
-      tags: [Data Catalog]
-      operationId: getCatalogs
-      parameters:
-        - name: sources
-          in: query
-          description: Sources to filter by
-          required: false
-          explode: true
-          schema:
-            type: array
-            items:
-              type: string
+      summary: Restituisce le fonti dati disponibili
+      tags: [Data Source]
       responses:
         '200':
           description: successful operation
@@ -138,90 +127,30 @@ paths:
               schema:
                 type: array
                 items:
-                  $ref: '#/components/schemas/Catalog'
+                  $ref: '#/components/schemas/Source'
+
     post:
-      summary: Crea un nuovo Catalogo Dati (admin only)
-      tags: [Data Catalog]
+      summary: Aggiunge una Fonte Dati (admin only)
+      tags: [Data Source]
       requestBody:
         required: true
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/Catalog'
+              $ref: '#/components/schemas/Source'
       responses:
         '201':
-          description: Catalogo creato
-
-  /catalog/{id}:
-    get:
-      summary: Restituisce un singolo Catalogo Dati
-      tags: [Data Catalog]
-      parameters:
-        - in: path
-          name: id
-          required: true
-          schema:
-            type: string
-      responses:
-        '200':
-          description: Catalogo trovato
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Catalog'
-        '404':
-          description: Catalogo non trovato
-
-    put:
-      summary: Modifica un Catalogo esistente (admin only)
-      tags: [Data Catalog]
-      parameters:
-        - in: path
-          name: id
-          required: true
-          schema:
-            type: string
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/Catalog'
-      responses:
-        '200':
-          description: Catalogo aggiornato
-
-    delete:
-      summary: Elimina un catalogo vuoto esistente (admin only)
-      tags: [Data Catalog]
-
-  /source:
-    get:
-      summary: Restituisce le fonti dati disponibili
-      tags: [Data Catalog]
-      responses:
-        '200':
-          description: successful operation
-          content:
-            application/json:
-              schema:
-                type: array
-                items:
-                  $ref: '#/components/schemas/Source'
-
-    post:
-      summary: Aggiunge una Fonte Dati (admin only)
-      tags: [Data Catalog]
+          description: Fonte Dati creata
 
   /source/{id}:
 
     put:
       summary: Modifica una sorgente dati esistente (admin only)
-      tags: [Data Catalog]
+      tags: [Data Source]
 
     delete:
       summary: Elimina una sorgente dati (vuota) esistente (admin only)
-      tags: [Data Catalog]
+      tags: [Data Source]
 
   /terminology:
     get:
@@ -458,6 +387,8 @@ components:
           type: string
           format: uri
           description: Identificativo univoco della Nomenclatura (terminology)
+          examples: 
+            - http://dati.beniculturali.it/cis
         name:
           type: string
           description: Nome canonico della Nomenclatura
@@ -470,6 +401,11 @@ components:
           description: Link alla documentazione della Nomenclatura
           examples: 
             - 'https://schema.gov.it/'
+        subject:
+          type: string
+          description: Soggetto titolare del Tipo
+          examples:
+            - 'Ministero per i Beni e le Attività Culturali'
         uri:
           type: string
           format: uri
@@ -486,24 +422,41 @@ components:
           type: string
           format: uri
           description: Identificativo univoco del Tipo di Entità
+          examples:
+            - http://dati.beniculturali.it/cis/CulturalInstituteOrSite
         name:
           type: string
           description: Nome canonico del Tipo di Entità
+          examples:
+            - Istituti e Luoghi Della Cultura Italiani (musei, biblioteche, cinema, ecc)
+        native:
+          type: boolean
+          description: Se il Tipo è nativo di piattaforma o importato
+          default: false
         stateType:
-          $ref: '#/components/schemas/Type'
+          $ref: '#/components/schemas/State'
         syntax:
           type: string
           format: json
           description: Definizione (JSON-LD) della sintassi del Tipo di Entità
         terminology:
           $ref: '#/components/schemas/Terminology'
+          examples:
+            - http://dati.beniculturali.it/cis
+        uri:
+          type: string
+          format: uri
+          description: URI autoritativo del Tipo (se non nativo)
+          examples: 
+            - http://dati.beniculturali.it/cis/CulturalInstituteOrSite
 
     State:
       type: object
       description: Definisce una possibile rappresentazione della situazione attuale nel «divenire» delle Entità di un certo Tipo
       examples: 
-        - ElectronicDeviceState - Acceso o Spento
-        - StatoSemaforo - Rosso, Giallo, Verde, Lampeggiante, Spento
+        - Aperto o Chiuso
+        - Acceso o Spento
+        - (StatoSemaforo) Rosso, Giallo, Verde, Lampeggiante, Spento
         - TemperaturaAmbiente - la temperatura attuale di un ambiente in gradi centigradi
       properties:
         id:
@@ -513,29 +466,56 @@ components:
         name:
           type: string
           description: Nome canonico del Tipo di Stato
+        uom:
+          type: string
+          description: Unità di misura (per grandezze scalari)
         kind:
           type: string
           description: La tipologia elementare del Tipo di Stato (grandezza con unità di misura, stringa, eccetera)
+          examples:
+            - Enumeration
+            - Number
+            - String
 
     Entity:
       type: object
-      description: rappresenta un generico oggetto urbano, è di uno specifico tipo, afferisce a un catalogo, ha uno stato dinamico, è dotato di proprietà type-specific, è tipicamente geo-localizzabile
-      required: [id, type, state, createdDate, updatedDate]
+      description: rappresenta un generico oggetto urbano, è di uno specifico Tipo, afferisce a una Sorgente Dati, ha uno Stato dinamico, è dotato di proprietà type-specific, può avere un Device associato, è tipicamente geo-localizzabile
+      required: [id, type, source, createdDate, updatedDate]
       properties:
         id:
           type: string
-          format: uri
-          description: URI univoco dell’Entità sulla piattaforma
+          description: ID univoco dell'Entità sulla piattaforma
+        name:
+          type: string
+          description: Nome canonico dell'Entità sulla piattaforma
+          examples:
+            - Antiquarium e Acquedotto romano di Trieste
+        geometry:
+          type: object
+          description: Coordinate geografiche dell'Entità
+          properties:
+            lat:
+              type: Number
+              description: Latitudine dell'Entità
+              examples: [45.61809]
+            long:
+              type: Number
+              description: Longitudine dell'Entità
+              examples: [13.827805]
         type:
           $ref: '#/components/schemas/Type'
         parent:
           $ref: '#/components/schemas/Entity'
+        source:
+          $ref: '#/components/schemas/Source'
         externalId:
           type: string
-          description: Identificativo dell’Entità nel sistema sorgente
+          description: Identificativo dell'Entità nel sistema sorgente
+          examples:
+            - http://dati.beniculturali.it/mibact/luoghi/resource/CISNameInTime/20738
         state:
           type: object
-          description: Stato dell’entità
+          description: Stato dell'entità
           properties:
             value:
               type: string
@@ -559,6 +539,8 @@ components:
           type: object
           description: Attributi personalizzati in base al tipo di entità
           additionalProperties: true
+          examples: 
+            - { chiusura: 'Lunedì|Giovedì|Domenica' }
         deviceId:
           description: Device associato all'entità
           $ref: '#/components/schemas/Device'
@@ -569,7 +551,7 @@ components:
         updatedDate:
           type: string
           format: date-time
-          description: Data e ora dell’ultima modifica all'entità, escluse le modifiche di stato (timestamp ISO 8601)
+          description: Data e ora dell'ultima modifica all'entità, escluse le modifiche di stato (timestamp ISO 8601)
 
     Source:
       type: object
@@ -579,9 +561,19 @@ components:
           type: string
           format: uri
           description: ID univoco della Fonte Dati
+          examples: 
+            - 'fvg_ispfor_tsgo'
+            - 'fvg_ispfor'
         name:
           type: string
           description: Nome canonico della Fonte Dati
+          examples:
+            - 'Ministero per i Beni e le Attività Culturali'
+            - 'Vincolo idrogeologico. L. 3267/1923 Comune di Trieste'
+            - 'Ispettorati forestali'
+            - 'Recupero energetico di biogas da digestione anaerobica o da discarica R1 (BDAD)'
+            - 'Area golenale'
+            - 'Copertura 2019 della banda larga in Italia secondo i criteri di rilevazione DESI 2020'
         internal:
           type: boolean
           description: Indica se la fonte dati è nativa della piattaforma o meno
@@ -589,23 +581,20 @@ components:
         organization:
           type: string
           description: Organizzazione di riferimento (ovvero soggetto alimentante) per la Fonte Dati
-      required: [id, name, organization, internal]
-
-    Catalog:
-      type: object
-      description: Catalogo Dati (Data Catalog) fornito da una Fonte Dati
-      properties:
-        id:
+          examples:
+            - 'Ministero per i Beni e le Attività Culturali'
+            - 'Regione Autonoma Friuli Venezia Giulia - ISPETTORATO FORESTALE DI TRIESTE E GORIZIA'
+            - 'RAFVG - DC Risorse agroalimentari, forestali e ittiche - Area foreste e territorio'
+            - 'Regione Autonoma Friuli Venezia Giulia - SERVIZIO DISCIPLINA GESTIONE RIFIUTI E SITI INQUINATI'
+            - 'Regione Autonoma Friuli Venezia Giulia - SERVIZIO GEOLOGICO'
+            - 'Autorità per le Garanzie nelle Comunicazioni - AGCOM'
+        processor:
           type: string
-          format: uri
-          description: ID univoco del Catalogo Dati
-        name:
-          type: string
-          description: Nome canonico del Catalogo Dati
-        source:
-          description: Fonte Dati di afferenza
-          $ref: '#/components/schemas/Source'
-      required: [id, name, source]
+          description: Organizzazione che gestisce tecnicamente la Fonte Dati
+          examples: 
+            - 'Insiel S.p.A.'
+            - 'Regione autonoma Friuli Venezia Giulia'
+      required: [id, name, organization, internal]
 
     Device:
       type: object