Questa versione: 0.9.5
Ultima versione: 0.9.5
Versione Precedente: 0.9.4
Autori: FabioVitali, SilvioPeroni, FrancescoPoggi
Contributor: Working Group LTW 2011/2012
Questo protocollo nasce all’interno del progetto Meta Market del corso di Tecnologie Web 2011/2012. L'obiettivo del progetto è di un motore per la creazione di rappresentazioni visuali e comprensibili di collezioni di dati numerici. Il protocollo si compone in realtà di due protocolli diversi: Descrittore-Aggregatore (DA) e Narratore-Descrittore (ND). L’architettura Meta Market prevede infatti tre componenti principali: aggregatori (per rispondere a richieste inerentemente ai dati crudi da essi gestiti), descrittori (per l'elaborazione sofisticata dei dati forniti dagli aggregatori) e narratori per la presentazione dei dati ricevuti dai descrittori. Ogni narratore comunica coi descrittori tramite il protocollo ND, mentre ogni descrittore comunica con gli aggregatori tramite il protocollo DA.
Questo documento è un aggiornamento del protocollo Meta Market originariamente redatto da FabioVitali?, SilvioPeroni? e FrancescoPoggi?. Deve essere utilizzato come materiale di riferimento per il progetto Meta Market per garantire l’interoperabilità fra i gruppi. Questo documento è la versione 0.9.5 del protocollo ed è soggetto a modifiche da parte dei Working Group organizzati secondo le regole del W3C (http://www.w3.org/Consortium/Process/). I WG potranno emettere i documenti di riferimento aggiornati, numerati e versionati, che verranno usati per le specifiche di interoperabilità. Il changelog di ogni versione e' in fondo a questa pagina.
Metamarket è composto da un data base di strutture commerciali e non, presentato all'utente sotto forma di tabella, cartina geografica o altre rappresentazioni visuali. Ad esempio, il database può descrivere:
Inoltre, grazie ad una interfaccia via browser, l'utente può filtrare i risultati visualizzati:
E ha la possibilita' di segnalare divergenze tra orari pubblicati e realtà.
Ogni gruppo ha l'obbligo di implementare almeno due aggregatori, due narratori e descrittori per 12 crediti. Per ogni gruppo, gli aggregatori e i descrittori hanno degli identificativi ben precisi e sono reperibili in determinati URL. Tutte le informazioni su aggregatori e descrittori sono pubblicate online sotto forma di catalogo (vedi sezione 5).
DA è un protocollo HTTP che regola la comunicazione tra un descrittore e un aggregatore. Di seguito sono descritte tutte le possibili richieste previste. Le richieste sono progettate secondo l'architettura REST.
Per ogni richiesta sono indicati:
È possibile richiedere ad un particolare aggregatore, identificato da un URL, dei dati coerentemente a dei parametri specificati come input dal descrittore.
Metodo: GET
Header:
URL: http://ltwxxxx.web.cs.unibo.it/<aggregatore>[/<key>/<comp>/<value>]
dove:
http://ltwxxxx.web.cs.unibo.it/<aggregatore> è l'URL dell'aggregatore da consultare; xxxx e' il codice del gruppo.<key> è una delle chiavi definite nel modello dei dati (vedi sezione 6).<comp> è un confrontatore a scelta tra LT (minore di), GT (maggiore di), LE (minore o uguale a), GE (maggiore o uguale a), EQ (uguale a), NE (diverso da), CONTAINS (contiene) e NCONTAINS (non contiene).<value> è il valore da confrontare per la chiave specificata. Nel caso di date DEVE essere in uno dei formati validi previsti (vedi sezione 6).NOTA
key, comp e value), l'aggregatore DEVE restituire l'intero documento senza applicare alcun filtro.
ATTENZIONE
E' ritenuta NECESSARIA e OBBLIGATORIA l'implementazione dei seguenti confronti (come tripla "key COMP value"):
EQ/NE/CONTAINS value (confronto tra stringhe)EQ/NE/CONTAINS/NCONTAINS value (confronto tra stringhe)EQ/NE/GT/LT/GE/LE value (confronto tra stringhe numeriche)CONTAINS value (confronto tra stringhe)EQ/NE/CONTAINS/NCONTAINS value (confronto tra stringhe)CONTAINS/NCONTAINS value (confronto tra stringhe, il match degli intervalli di orari spetta al descrittore) http://ltw1234.web.cs.unibo.it/servizi-unibo/category/CONTAINS/Dipartimento chiede all'aggregatore disponibile all'URL http://ltw1234.web.cs.unibo.it/servizi-unibo/ di restituire tutte e sole le locazioni, raccolte dall'aggregatore che si occupa dei servizi per gli studenti dell'Universita' di Bologna, che sono dipartimenti (ovvero che all'interno dell'elemento "category" contengono il valore "Dipartimento".
Header: Accept: text/plain, text/turtle, text/csv, application/json, application/xml
Body: vuoto
Header: Content-type: <mime-type>; charset=UTF-8
dove:
<mime-tipe> è uno a scelta tra text/turtle | text/plain | text/csv | application/json | application/xml a seconda del formato di cui dispone l'aggregatore.Body: (esempio con application/xml come formato restituito)
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE locations SYSTEM "http://vitali.web.cs.unibo.it/twiki/pub/TechWeb12/DTDs/locations.dtd">
<locations>
<metadata>
<creator>Fabio Vitali</creator>
<created>2011-09-10</created>
<version>1.1</version>
<source>http://cs.unibo.it</source>
<valid>2011-12-31</valid>
</metadata>
<location id="uni001" lat="28.847607" long="57.084961">
<category>Dipartimento, Università</category>
<name>Dipartimento di Scienze dell'Informazione</name>
<address>Mura Anteo Zamboni 7, 40127, Bologna, Italy</address>
<opening>Mon, Tue, Wed, Thu, Fri: 0830-2000. Sat: 0830-1230.</opening>
<closing>04/10/2011 , 25/12/2011: .</closing>
</location>
<location ...>
...
</location>
...
</locations>
ND è un protocollo HTTP che regola la comunicazione tra un narratore e un descrittore. Di seguito sono descritte tutte le possibili richieste previste. Le richieste sono progettate secondo l'architettura REST.
Per ogni richiesta è indicato:
È possibile richiedere, ad un particolare descrittore identificato da un URL, dei dati coerentemente a dei parametri specificati come input dal narratore.
Metodo: GET
URL: http://ltwxxxx.web.cs.unibo.it/<descr>[/<aggregatore1>[/<aggregatore_i>]*]/[params/[<param>/]+]?
dove:
http://ltwxxxx.web.cs.unibo.it/<descr> è l'URL del descrittore; xx e' il codice del gruppo<aggregatore1> e' l'identificativo (opzionale) dell'aggregatore contenente i dati su cui si effettuera' l'elaborazione<aggregatore_i> sono gli identificativi (opzionali) di altri aggregatori aggiuntivi nel caso in cui il descrittore debba attingere a dati contenuti in più aggregatori contemporaneamente (descrittori parametrici)<param/> sono dei parametri opzionali eventualmente richiesti dal descrittore per funzionareNOTA
http://ltw1134.web.cs.unibo.it/vicino-a/ltw1140-farmacie-bologna/params/28.847607/57.084961/10 chiede al descrittore vicino-a di restituire le 10 farmacie più vicine alla locazione (data dalla latitudine e longitudine) specificata, considerando i dati gestiti dall'aggregatore con id ltw-1140-farmacie-bologna
.
Header: Accept: <mime-type>
dove:
<mime-tipe> è uno a scelta tra text/turtle | text/csv | application/json | application/xml per restituire un formato strutturato oppure text/plain per restituire un formato letteraleBody: vuoto
NOTA
Header: Content-type: <mime-type>; charset=UTF-8
dove:
<mime-tipe> è il formato accettato dal narratore tra text/turtle | text/csv | application/json | application/xml | text/plain Body: (esempio con text/turtle formato restituito):
@prefix : <http://www.essepuntato.it/resource/> .
@prefix vcard: <http://www.w3.org/2006/vcard/ns#> .
@prefix cs: <http://cs.unibo.it/ontology/> .
@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix metadata: <http://vitali.web.cs.unibo.it/twiki/pub/TechWeb12/DataSource2/posteBO2011.ttl> .
metadata:metadata
dcterms:creator "Working Group LTW 2011/2012"
; dcterms:created "2011-12-20"^^xsd:date
; dcterms:version "1.2"
; dcterms:valid "2011-02-21"^^xsd:date
; dcterms:source "http://www.aziendedibologna.it/poste_bologna_e_provincia.htm".
:pt0001
vcard:category "Poste e Telegrafi"
; vcard:fn "Ufficio Bologna 1"
; vcard:extended-address "Via Cairoli 9, Bologna BO, Italy"
; vcard:latitude "44.504192"
; vcard:longitude "11.338661"
; vcard:tel "051 243425"
; vcard:fax "051 244459"
; cs:opening "Mon, Tue, Wed, Thu, Fri: 0800-1330. Sat: 0800-1230."
; cs:closing "01-01, 01-06, P, LA, 04-25, 05-01, 06-02, 08-15, 11-01, 12-08, 12-25, 12-26: .".
...
Nel caso in cui una richiesta generi un errore, gli aggregatori/descrittori DEVONO rispondere utilizzando gli appropriati codici HTTP 4xx e 5xx. I descrittori/narratori DEVONO gestire ogni codice d'errore in maniera appropriata.
E' OBBLIGATORIO contemplare (ovvero generarli sia nell'header sia, tramite una descrizione, nel body) i seguenti errori (con relativi codici HTTP):
In aggiunta ai codici d'errore HTTP, il contenuto fornito dal server deve fornire più indicazioni possibili sull'errore generato e fornire suggerimenti su come risolverlo (se possibile). I servizi sono liberi di usare qualsiasi tipo di dato per il contenuto restituito, tenendo comunque in considerazione la richiesta originaria del client (fornite nell'header Accept o in altro modo).
Ogni gruppo partecipante deve pubblicare, in una locazione facilmente raggiungibile tramite un URL, un documento XML, detto catalogo, contenente informazioni riguardo gli aggregatori e i descrittori sviluppati, validato con l'apposito DTD. Ad esempio:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE catalogo SYSTEM "http://vitali.web.cs.unibo.it/twiki/pub/TechWeb12/DTDs/catalogo.dtd">
<catalogo id="ltw1130" gruppo="Thank you for coding">
<aggregatori>
<aggregatore id="ltw1130-farmacie-supermercati" title="Farmacie e Supermercati di Bologna" url="http://ltw1130.web.cs.unibo.it/farmacie-supermercati/">Dati riguardo le maggiori farmacie e supermercati di Bologna città, con locazioni, indirizzi e orari di apertura.
</aggregatore>
<aggregatore>
...
</aggregatore>
</aggregatori>
<descrittori>
<descrittore url="http://ltw1130.web.cs.unibo.it/vicino-a" desc="Restituisce i luoghi più vicini al punto specificato">
<params>
<param name="latitude" required="yes">La latitudine di partenza</param>
<param name="longitude" required="yes">La longitudine di partenza</param>
<param name="category" required="yes">La categoria di luogo da ricercare. Usare '*' se si vogliono considerare tutte le categorie.</param>
<param name="number of result" required="no">Parametro opzionale, in cui specificare il massimo numero di risultati che si vuol ricevere in risposta.</param>
</params>
</descrittore>
<descrittore>
...
</descrittore>
...
</descrittori>
</catalogo>
L'id di ogni aggregatore, all'interno del catalogo di ogni gruppo, DEVE essere univoco (rispetto a tutti gli id utilizzati dagli altri gruppi). A tale scopo ogni identificativo di aggregatore DEVE essere nella forma ltwXXXX-$NOME_AGG ovvero avere, come prefisso, l'identificativo del gruppo. Ogni aggregatore DEVE integrare un attributo "title" in cui e' presente una stringa, molto sintetica (visualizzabile in un menu a scomparsa), che descriva il tipo di dati gestito (3-4 parole).
Inoltre, tutti i cataloghi di tutti i gruppi devono essere registrati in un ulteriore file XML chiamato meta-catalogo, il cui URL deve essere chiaramente indicato in queste specifiche. Nel meta-catalogo si trovano gli identificativi (chiaramente univoci) dei cataloghi e i relativi URL in cui essi risiedono:
URL PROVVISORIO (verrà convertito in un allegato XML)
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE metaCatalogo SYSTEM "http://vitali.web.cs.unibo.it/twiki/pub/TechWeb12/DTDs/metaCatalogo.dtd">
<metaCatalogo>
<catalogo id="ltw1130" gruppo="Thank you for coding" url="http://ltw1130.web.cs.unibo.it/catalogo" />
<catalogo ... />
...
</metaCatalogo>
In questa sezione viene descritto il modello dei dati da utilizzare per restituire i risultati alle richieste fatte verso l'aggregatore o verso un descrittore.
ATTENZIONE
I dati da gestire devono riguardare luoghi (fisici o virtuali), devono essere geolocalizzabili e devono avere specificati degli orari di apertura e di chiusura. Conseguentemente, i campi che devono essere gestiti sono:
Oltre a questi dati è possibile integrare due tipologie di dati FACOLTATIVE (che potrebbero risultare utili in molti casi di narrazione)
ATTENZIONE: TUTTI gli insiemi di dati letterali (come le categorie o i contatti), date ESCLUSE (che devono seguire la specifica sintassi) DEVONO essere separati dal carattere "virgola (,)
Gli intervalli di orari settimanali DEVONO rispettare questa sintassi: [PATTERN]: [TIME_1],[TIME_2],...,[TIME_N]. dove [PATTERN] e' una sequenza di giorni settimanali (Mon, Tue ecc.) o date (2011-12-24, 06-28 ecc.) e [TIME_N] e' un intervallo di orari (indicati come HHMM-HHMM formato 24h) separati da virgola (0830-1630, 1730-1900 ecc.) . Ad esempio: "Mon, Tue, Wed, ..., Sun: 0830-1930." oppure "2011-12-24: 0830-1900, 2200-2300"). Gli intervalli che NON riportano orari (ad es. "Mon: .") sono da considerarsi giorni o date di CHIUSURA. In caso di apertura 24/24h e' comunque necessario indicare la sequenza o il range di giorni/date specificando, come intervallo di orari, 0000-2400.
DEFINIZIONE FORMALE:
AGGIORNAMENTO
NOTA
Informazioni sui vari documenti in cui sono salvati i dati, come quelle riguardanti la freschezza, la versione, l'intervallo di validità e le informazioni per il riaccesso ai dati aggiornati. In particolare:
Le informazioni introdotte nelle sezioni precedenti possono essere espresse in quattro diversi formati: Comma-Separated Values (CSV), JSON, XML e Turtle.
Di seguito vengono descritti tutti i formati e vengono proposti relativi esempi inerentemente alla seguente descrizione: nel documento, creato da Fabio Vitali il 10 settembre 2011 e modificato l'ultima volta da Silvio peroni il 12 ottobre 2011, sono inserite informazioni riguardo gli orari di apertura del Dipartimento di Scienze dell'Informazione dell'Università di Bologna.
Il formato CSV (http://tools.ietf.org/html/rfc4180) è formato da un header, che indica i nomi dei vari campi, che è seguito da un numero arbitrario di record (ovvero righe) contenenti i vari dati. I campi possibili per questo formato sono:
Facoltativi:
Bisogna prestare particolarmente attenzione a includere eventuali campi che richiedono la non interpretazione della virgola, come separatore, tra doppi apici ("").
ID,CATEGORY,NAME,ADDRESS,LAT,LONG,OPENING,CLOSING,CREATOR,CREATED,VERSION,SOURCE,VALID
"uni001","Dipartimento,Università","Dipartimento di Scienze dell'Informazione","Mura Anteo Zamboni 7 , 40127 , Bologna , Italy","28.847607","57.084961", "Mon, Tue, Wed, Thu, Fri: 0830-2000 , Sat: 0830-1230","04/10/2011 , 25/12/2011","Fabio Vitali","10/09/2011","1.1","http://cs.unibo.it","31/12/2011"
Il formato JSON (http://tools.ietf.org/html/rfc4627) permette di definire oggetti per specificare le varie informazioni. Le chiavi dei vari oggetti da utilizzare per le informazioni da gestire sono:
Facoltativi:
{
"locations": {
"sup0001": {
"category": ["Supermarket"],
"name": "Plenty Market",
"address": "Via Farini, 30 - Bologna BO",
"lat": "44.491637",
"long":"11.348056",
"tel": "051 236113",
"opening": "Mon, Tue, Wed, Thu, Fri, Sat: 0900-2030. Sun: 0930-1400, 1630-1930.",
"closing": "01-01, 06-06, P, LA, 04-25: ."
}
},
"metadata" : {
"creator" : "Fabio Vitali",
"created" : "27/11/2011",
"version" : "1.0",
"source" : "http://vitali.web.cs.unibo.it/TechWeb12/Formati",
"valid" : "31/12/2011"
}
}
Il formato XML (http://www.w3.org/XML/) permette di descrivere i dati attraverso elementi e attributi di markup. Il vocabolario e i content model degli elementi e attributi del formato devono essere esplicitamente definiti dal working group sotto forma di grammatica (DTD, RelaxNG? o XML Schema) in modo da evitare possibili ambiguità.
Ogni documento in formato XML deve iniziare con l'elemento locations. Tutte le informazioni vanno gestite con i seguenti elementi:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE locations SYSTEM "http://vitali.web.cs.unibo.it/twiki/pub/TechWeb12/DTDs/locations.dtd">
<locations>
<metadata>
<creator>Fabio Vitali</creator>
<created>10/09/2011</created>
<version>1.1</version>
<source>http://cs.unibo.it</source>
<valid>31/12/2011</valid>
</metadata>
<location id="uni001" lat="28.847607" long="57.084961">
<category>Dipartimento, Università</category>
<name>Dipartimento di Scienze dell'Informazione</name>
<address>Mura Anteo Zamboni 7, 40127, Bologna, Italy</address>
<opening>Mon, Tue, Wed, Thu, Fri: 0830-2000. Sat: 0830-1230.</opening>
<closing>04/10/2011 , 25/12/2011: .</closing>
</location>
</locations>
Il formato Turtle (http://www.w3.org/TR/turtle/) permette di descrivere i dati per il Semantic Web, in modo che possano essere facilmente integrati all'interno del Linked Data. I dati devono essere descritti nel rispetto di specifiche ontologie, in particolare:
Tutte le informazioni vanno gestite con le seguenti risorse:
@prefix : <http://ltwxxxx.web.cs.unibo.it/resource/> .
@prefix vcard: <http://www.w3.org/2006/vcard/ns#> .
@prefix time: <http://www.w3.org/2006/time#> .
@prefix dcterms: <http://purl.org/dc/terms/> .
@base <http://ltwxxxx.web.cs.unibo.it/result> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
:cs
a vcard:Vcard
vcard:category "Dipartimento" , "Università"
; vcard:fn "Dipartimento di Scienze dell'Informazione"
; vcard:extended-address "Mura Anteo Zamboni 7, 40127, Bologna, Italy"
; vcard:latitude "28.847607"
; vcard:longitude "57.084961"
; time:opening "Mon, Tue, Wed, Thu, Fri: 0830-2000" , "Sat: 0830-1230"
; time:closing "04/10/2011" , "25/12/2011" .
<>
dcterms:creator "Fabio Vitali"
; dcterms:created "2011-09-10"^^xsd:date
; dcterms:description "1.1"
; dcterms:valid "2011-12-31"^^xsd:date
; dcterms:source "http://cs.unibo.it" .