Questa versione: 0.9.1
Ultima versione: 0.9.2
Versione Precedente: 0.9
Autori: FabioVitali, SilvioPeroni, FrancescoPoggi
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 originario 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.1 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. In particolare, 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, descrittori e narratori 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 è indicato:
È possibile richiedere ad un particolare aggregatore, identificato da un URL, dei dati coerentemente a dei parametri specificati come input dal descrittore.
Metodo: GET
URL: http://ltw12xx.web.cs.unibo.it/<aggregatore>/<key>/<comp>/<value>[/<sorting>/<sortingKey>]?
dove:
http://ltw12xx.web.cs.unibo.it/<aggregatore> è l'URL dell'aggregatore da consultare; xx 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).<value> è il valore da confrontare per la chiave specificata.<sorting> specifica di ordinare i risultati in modo ascendente (quando specificato a ASC) o discendente (se specificato a DESC).<sortingKey> è la chiave secondo il quale ordinare i risultati (vedi sezione 6)ATTENZIONE: Ogni gruppo deve effettuare l'implementazione della lettura dell'URL in modo da accettare i parametri case insensitive , ad esempio EQ, eQ, Eq, eq ecc.
E' ritenuta necessaria l'implementazione dei seguenti confronti (key COMP value):
Esempio: http://ltw1234.web.cs.unibo.it/servizi-unibo/category/CONTAINS/Dipartimento/ASC/name 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, ordinando i risultati in maniera crescente secondo la chiave name (nome).
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 PUBLIC "http://vitali.web.cs.unibo.it/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="cs" 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: 8:30-20:00, Sat: 8:30-12:30</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://ltw12xx.web.cs.unibo.it/<descr>/<aggregatore1>[/<aggregatore_i>]*/[params/[<param/>]+]*
dove:
http://ltw12xx.web.cs.unibo.it/<descr> è l'URL del descrittore; xx e' il codice del gruppo<aggregatore1> e' l'identificativo dell'aggregatore contenente i dati su cui si effettuera' l'elaborazione<aggregatore_i> sono gli identificativi 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 funzionareEsempio: http://ltw1234.web.cs.unibo.it/vicino-a/farmacie-e-supermercati/farmacie-bologna/params/28.847607/57.084961/farmacia/10 chiede al descrittore di restituire le 10 farmacie più vicine alla locazione (data dalla latitudine e longitudine) specificata, considerando i dati gestiti dagli aggregatori dei cataloghi farmacie-e-supermercati
e 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
Header: Content-type: <mime-type> ; =charset=UTF-8=
dove:
<mime-tipe> è uno a scelta tra text/turtle | text/csv | application/json | application/xml | text/plain Body (con text/turtle formato restituito):
@prefix : <http://ltwxxxx.web.cs.unibo.it/resource/> . @prefix time: <http://www.w3.org/2006/time#> . @prefix vcard: <http://www.w3.org/2006/vcard/ns#> . @prefix lode: <http://linkedevents.org/ontology/> . :farmacia-comunale a vcard:VCard ; vcard:category "Farmacia" , "Luogo pubblico" ; vcard:fn "Farmacia Comunale Centrale" ; vcard:extended-address "Piazza Maggiore 6, 40121, Bologna, Italy" ; vcard:latitude "28.847607" ; vcard:longitude "57.084961" ; time:opening "Mon, Tue, Wed, Thu, Fri, Sat, Sun: 8:00-20:30" . ...
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 ALMENO 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 PUBLIC "http://vitali.web.cs.unibo.it/TechWeb12/DTDs/catalogo.dtd"?>
<catalogo id="ltw12XX" gruppo="Thank you for coding">
<aggregatori>
<aggregatore id="ltw12XX-farmacie-supermercati" title="Farmacie e Supermercati di Bologna" url="http://ltw12XX.web.cs.unibo.it/ltw12XX-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://ltw12XX.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 ltw12XX-$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, 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 (univoci) dei cataloghi e i relativi URL in cui essi risiedono:
<?xml version="1.0" encoding="UTF-8"?>
<?DOCTYPE PUBLIC "http://vitali.web.cs.unibo.it/TechWeb12/DTDs/metaCatalogo.dtd"?>
<metaCatalogo>
<catalogo id="ltw12XX" gruppo="Thank you for coding" url="http://ltw12XX.web.cs.unibo.it/catalogo" />
<catalogo ... />
...
</metaCatalogo>
L'id di ogni catalogo, all'interno del meta-catalogo, DEVE (chiaramente) essere univoco.
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.
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:
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 cinque 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:
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
"cs","Dipartimento,Università","Dipartimento di Scienze dell'Informazione","Mura Anteo Zamboni 7 , 40127 , Bologna , Italy","28.847607","57.084961", "Mon, Tue, Wed, Thu, Fri: 8:30-20:00 , Sat: 8:30-12:30","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:
{
"data": {
"sup0001": {
"category": ["Supermarket"],
"name": "Plenty Market",
"address": "Via Farini, 30 - Bologna BO",
"lat": "44.491637",
"lg":"11.348056",
"tel": "051 236113",
"opening": "Mon, Tue, Wed, Thu, Fri, Sat: 0900-2030. Sun: 0930-1400 1630-1930.",
"closing": "1 Jan, 6 Jan, P, LA, 25 Apr, 1 May, 2 Jun, 15 Aug, 1 Nov, 8 Dec, 25 Dec, 26 Dec: ."
}
}
"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 PUBLIC "http://vitali.web.cs.unibo.it/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="cs" 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: 8:30-20:00 , Sat: 8:30-12:30</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: 8:30-20:00" , "Sat: 8:30-12:30"
; 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" .