Bozza per il formato GDXP (GAS Data Exchange Protocol) versione 1.0.

Questa pagina e' destinata ad esporre il materiale temporaneamente durante la discussione pubblica, una volta finalizzato qualcosa sara' da spostare in maniera permanente da qualche altra parte.

L'appello per la revisione di questo protocollo e' stato inviato alla mailing list CyberSocial il 13 agosto 2011, qui di seguito il testo integrale.

Fin dalla mia prima apparizione su questa mailing list iniziai a blaterare di un formato condiviso per l'esportazione e l'importazione dei dati da un gestionale GAS all'altro, qualcosa che permettesse interoperabilita' tra le diverse piattaforme e, conseguentemente, rendesse un po' piu' facile la vita ai nostri utenti. Finalmente, e' venuto il giorno di parlarne un poco piu' concretamente.

Qui -> http://trac.gasdotto.net/wiki/GDXPTodo ho piazzato temporaneamente la bozza del DTD per la versione 1.0 di quello che abbiamo chiamato GDXP, ovvero "GAS Data Exchange Protocol" (anche il nome puo' essere oggetto di revisione, ovviamente), affinche' tutti gli interessati possano muovere i propri commenti e le proprie correzioni.

Al momento gli intenti del formato sono limitati ai casi d'uso piu' comuni: esportazione ed importazione del listino di un fornitore (cosa che credo sia successo a tutti di sentirsi chiedere), ed esportazione ed importazione di un ordine aperto (per permettere la condivisione di uno stesso ordine tra piu' GAS). La differenza tra un utilizzo e l'altro sta solo nella presenza del nodo "orders" in coda al file: se c'e' si sta parlando di un ordine in cui sono compresi i prodotti elencati sopra, se non c'e' si sta parlando di un semplice listino.

Certamente la struttura proposta non e' la migliore possibile, ma ho insistito con colui che ne ha curato la definizione per sopprimere ogni pippa ed ogni possibile margine di ambiguita' apposta perche' il formato sia rapidamente e facilmente implementabile da chiunque senza sclero. Per ogni elemento descritto sono contemplati gli attributi piu' comuni (a parte un paio di eccezioni che francamente non so perche' siano state introdotte all'ultimo momento...): se ci sono cose che non supportate, o cose che supportate ma non sono previste, fatecelo sapere. Il piu' e' evitare di avere millemila attributi che supporta una singola piattaforma, ma attenerci ad un minimo comun denominatore condiviso tra tutti; se poi qualcuno vuole gestirsi i suoi propri attributi puo' usare la sezione "extraFields" appositamente introdotta per permettere l'estensione ed una sommaria personalizzazione del formato.

Sarebbe ottimo raggiungere un consenso entro meta' settembre, affinche' la release 1.0 sia finalizzata per permettere a tutti l'implementazione giusto in tempo per il rientro dalle ferie dei GAS. Se ci sara' interesse si potranno reiterare altre revisioni su una base temporale predefinita (ogni sei o dodici mesi): intanto vediamo in quanti aderiscono.

Per commenti, osservazioni, domande, critiche e richieste, rispondete qui in mailing list pubblica.

Bozza 0.3

<?xml version="1.0" encoding="UTF-8"?>
<!--
	Gas Data eXchange Protocol
-->
<!--
	Tag: gdxp
	Descrizione: root
	Attributi:
		- protocolVersion: versione del protocollo
		- creationDate: timestamp di creazione del file con precisione fino al secondo con formato YYYYMMDDHHmmss
		- applicationSignature: firma dell'applicazione che ha creato il file
	Figli: supplier
-->
<!ELEMENT gdxp supplier*>
	<!ATTLIST gdxp protocolVersion CDATA #REQUIRED>
	<!ATTLIST gdxp creationDate CDATA #REQUIRED>
	<!ATTLIST gdxp applicationSignature CDATA #REQUIRED>
	
	<!--
		Tag: supplier
		Descrizione: contiene i dati di anagrafica, prodotti/listini e
		ordini aperti per il singolo fornitore
		Figli: taxCode, vatNumber, name, address, contacts, note?, products, orders, extraFields
	-->
	<!ELEMENT supplier (taxCode, vatNumber, name, address, contacts, note?, products, orders, extraFields?)>
		<!--
			Tag: taxCode
			Descrizione: Codice fiscale
		-->
		<!ELEMENT taxCode (#CDATA)>

		<!--
			Tag: vatNumber
			Descrizione: Partita IVA
		-->
		<!ELEMENT vatNumber (#CDATA)>
		
		<!--
			Tag: name
			Descrizione: Nome/Ragione sociale del fornitore 
		-->
		<!ELEMENT name (#CDATA)>
		
		<!--
			Tag: address
			Descrizione: indirizzo del fornitore
			Figli: street, locality, zipCode, country
		-->
		<!ELEMENT address (street, locality, zipCode, country)>
			<!--
				Tag: street
				Descrizione: via e numero civico
			-->
			<!ELEMENT street (#CDATA)>

			<!--
				Tag: locality
				Descrizione: località/paese/città
			-->
			<!ELEMENT locality (#CDATA)>

			<!--
				Tag: zipCode
				Descrizione: codice postale
			-->
			<!ELEMENT zipCode (#CDATA)>

			<!--
				Tag: country
				Descrizione: nazione
			-->
			<!ELEMENT country (#CDATA)>
			
		<!--
			Tag: contacts
			Descrizione: contiene la lista dei contatti per quel fornitore
			Figli: contact
		-->
		<!ELEMENT contacts (contact*)>
		
			<!--
				Tag: contact 
				Descrizione: contatto/riferimento del fornitore
				Figli: primary, extraContact
			-->
			<!ELEMENT contact (primary, extraContact*)>
			
			<!--
				Tag: primary
				Descrizione: contatto principale direttamente legato alla
				ragione sociale del fornitore
				Figli: phoneNumber, faxNumber, emailAddress, webSite
			-->
			<!ELEMENT primary (phoneNumber, faxNumber?, emailAddress, webSite?)>
				<!--
					Tag: phoneNumber
					Descrizione: numero telefonico
				-->
				<!ELEMENT phoneNumber (#CDATA)>

				<!--
					Tag: faxNumber
					Descrizione: numero di fax
				-->
				<!ELEMENT faxNumber (#CDATA)>

				<!--
					Tag: emailAddress
					Descrizione: indirizzo di posta elettronica
				-->
				<!ELEMENT emailAddress (#CDATA)>

				<!--
					Tag: webSite
					Descrizione: indirizzo del sito web
				-->
				<!ELEMENT webSite (#CDATA)>

			<!--
				Tag: extraContact
				Descrizione: contatto per un riferimento del fornitore
				Figli: firstName, lastName, phoneNumber, mobileNumber, faxNumber, emailAddress
			-->
			<!ELEMENT extraContact (firstName, lastName, phoneNumber, mobileNumber, faxNumber?, emailAddress)>
				<!--
					Tag: firstName
					Descrizione: nome
				-->
				<!ELEMENT firstName (#CDATA)>

				<!--
					Tag: lastName
					Descrizione: cognome
				-->
				<!ELEMENT lastName (#CDATA)>

				<!--
					Tag: phoneNumber
					Descrizione: numero del telefono fisso
				-->
				<!ELEMENT phoneNumber (#CDATA)>

				<!--
					Tag: mobileNumber
					Descrizione: numero del telefono cellulare
				-->
				<!ELEMENT mobileNumber (#CDATA)>

				<!--
					Tag: faxNumber
					Descrizione: numero di fax
				-->
				<!ELEMENT faxNumber (#CDATA)>

				<!--
					Tag: emailAddress
					Descrizione: indirizzo di posta elettronica
				-->
				<!ELEMENT emailAddress (#CDATA)>

		<!--
			Tag: note
			Descrizione: Commenti e note (testo libero) relative al fornitore
		-->
		<!ELEMENT note (#CDATA)>
		
		<!--
			Tag: products
			Descrizione: lista dei prodotti/listino del fornitore
			Figli: product
		-->
		<!ELEMENT products (product*)>
		
			<!--
				Tag: product
				Descrizione: singolo prodotto
				Figli: sku, name, category, um, description, orderInfo, variants, extraFields
			-->
			<!ELEMENT product (sku?, name, category, um, description, orderInfo, variants?, extraFields?)>
				<!--
					Tag: sku
					Descrizione: codice prodotto del fornitore
				-->
				<!ELEMENT sku (#CDATA)>

				<!--
					Tag: name
					Descrizione: descrizione del prodotto
				-->
				<!ELEMENT name (#CDATA)>

				<!--
					Tag: category
					Descrizione: categoria di cui fa parte il prodotto
				-->
				<!ELEMENT category (#CDATA)>

				<!--
					Tag: um
					Descrizione: unità di misura
				-->
				<!ELEMENT um (#CDATA)>
				
				<!--
					Tag: description
					Descrizione: descrizione estesa del prodotto
				-->
				<!ELEMENT description (#CDATA)>
				
				<!--
					Tag: orderInfo
					Descrizione: informazioni relative al prodotto relative agli ordini
					Figli: packageQty, minQty, mulQty, maxQty, umPrice, shippingCost
				-->		
				<!ELEMENT orderInfo (packageQty?, minQty?, mulQty?, maxQty?, umPrice, shippingCost?)>
					<!--
						Tag: packageQty
						Descrizione: quantità per confezione
					-->
					<!ELEMENT packageQty (#CDATA)>

					<!--
						Tag: minQty
						Descrizione: quantità minima ordinabile
					-->
					<!ELEMENT minQty (#CDATA)>

					<!--
						Tag: mulQty
						Descrizione: quantità multipla di ordine
					-->
					<!ELEMENT mulQty (#CDATA)>

					<!--
						Tag: maxQty
						Descrizione: quantità massima totale ordinabile
					-->
					<!ELEMENT maxQty (#CDATA)>

					<!--
						Tag: umPrice
						Descrizione: prezzo per unità di misura
					-->
					<!ELEMENT umPrice (#CDATA)>

					<!--
						Tag: shippingCost
						Descrizione: costo di trasporto per unità di misura
					-->
					<!ELEMENT shippingCost (#CDATA)>

				<!--
					Tag: variants
					Descrizione: lista delle varianti
					Figli: variant
				-->
				<!ELEMENT variants (variant)>

					<!--
						Tag: variant
						Descrizione: rapprensenta la singola variante per il prodorro
						Attributi:
						 - name: nome della variante
						Figli: value
					-->
					<!ELEMENT variant (value+)>
						<!ATTLIST variant name CDATA #REQUIRED>

						<!--
							Tag: value
							Descrizione: singolo valore che può assumere la variante
						-->
						<!ELEMENT value (#CDATA)>

				<!--
					Tag: extraFields
					Descrizione: lista dei campi non direttamente previsti dal protocollo
					Figli: extraField
				-->		
				<!ELEMENT extraFields (extraField)>

					<!--
						Tag: extraField
						Descrizione: campo non previsto dal protocollo
						Attributi:
						 - name: il nome del campo
					-->
					<!ELEMENT extraField (#CDATA)>
						<!ATTLIST extraField name CDATA #REQUIRED>

		<!--
			Tag: orders
			Descrizione: lista degli ordini
			Figli: order
		-->
		<!ELEMENT orders (order*)>

			<!--
				Tag: order
				Descrizione: dati relativi al singolo ordine
				Figli: openDate, closeDate, deliveryDate, extraFields
			-->
			<!ELEMENT order (openDate, closeDate, deliveryDate?, extraFields?)>
				<!--
					Tag: openDate
					Descrizione: data di apertura dell'ordine
				-->
				<!ELEMENT openDate (#CDATA)>

				<!--
					Tag: closeDate
					Descrizione: data di chiusura dell'ordine
				-->
				<!ELEMENT closeDate (#CDATA)>

				<!--
					Tag: deliveryDate
					Descrizione: data prevista di consegna
				-->
				<!ELEMENT deliveryDate (#CDATA)>

				<!--
					Tag: extraFields
					Descrizione: lista dei campi non direttamente previsti dal protocollo
					Figli: extraField
				-->		
				<!ELEMENT extraFields (extraField)>
				
					<!--
						Tag: extraField
						Descrizione: campo non previsto dal protocollo
						Attributi:
						 - name: il nome del campo
					-->
					<!ELEMENT extraField (#CDATA)>
						<!ATTLIST extraField name CDATA #REQUIRED>

		<!--
			Tag: extraFields
			Descrizione: lista dei campi non direttamente previsti dal protocollo
			Figli: extraField
		-->
		<!ELEMENT extraFields (extraField)>

			<!--
				Tag: extraField
				Descrizione: campo non previsto dal protocollo
				Attributi:
				 - name: il nome del campo
			-->
			<!ELEMENT extraField (#CDATA)>
				<!ATTLIST extraField name CDATA #REQUIRED>

Changelog

• 0.3

  • campo "note" opzionale

• 0.2

  • gran parte degli attributi sono stati mutati in elementi
  • soppressi i campi packagePrice e discounts
  • resi facoltativi i campi faxNumber, webSite, sku, packageQty, minQty, mulQty, maxQty, shippingCost, deliveryDate

• 0.1.1

  • aggiunto elemento "extraField" sia in "supplier" che in "order"
  • rinominato "accountancyVATNumber" in "vatNumber"

• 0.1

  • versione iniziale

Punti Aperti

• per i prodotti

  • introdurre l'attributo "pezzatura"
  • introdurre l'attributo "sovraprezzo"
  • introdurre l'attributo "prezzo variabile" (per i prodotti a peso)
  • introdurre l'attributo "dimensione confezione"

• per gli ordini

  • permettere di inserire piu' ordini per uno stesso fornitore all'interno dello stesso file