Get Hot New Stuff Specification

Josef Spillner


    
  

Revision 0.5


Table of Contents

Overview
A unified scheme for data sharing
Files and entities
Providers
Upload format
Download format
Data item categories
A. Formal documents
B. Change history

Overview

Desktop applications today are either working with data files or can be enhanced by them, or both. The interchange of those files between users of said applications is however not standardised. This specification covers a way to let users upload and download their data files and thus share them with each other.

A unified scheme for data sharing

Based on the existing GHNS ("Get Hot New Stuff") framework, which exists with implementations for KDE and SDL, and the XML format used for downloads of AGO (art.gnome.org), a unified, generic sharing framework is proposed to be implemented by all free desktops. Data sharing is made possible for generic internet transport protocols (like HTTP and FTP) and also for web services (SOAP, REST). The former method is called "traditional GHNS uploads/downloads" and for the download part also "GHNS feed", whereas the latter one is called DXS (Desktop Exchange Service), which has its own specification.

Note

Note that both traditional GHNS and DXS can be supported side-by-side. They are merely different interfaces to one and the same database, which runs as the backend for the GHNS content repository.

Uploading files works by sending the contents of a created file, a preview thereof in most cases, and some meta information to a service. Downloading works by reading meta information first, optionally retrieving the preview, and then receiving the selected contents. The feed which contains the meta information is a list of entries, each of which resemble their original upload meta information, plus some statistical information and probably some added translations.

Files and entities

All GHNS operations start with a provider file, which lists providers for data uploads, downloads or direct interaction. In most cases, each application will reference one unique provider file at the application maintainer's discretion, depending on what data types the application supports.

For uploads, a meta information file is created. Downloads make use of this information in aggregated form using download feeds.

Caching might help to optimise the access to the network resources. Specifically, the provider file, download feeds and preview images are subject to caching.

Providers

In order to find a place to host files and download files from, a directory service-like request is done first. This is implemented by a so-called provider resource, an XML file which lists all of the available providers with their attributes. The root XML tag for the providers file is ghnsproviders. The top-level XML tag for each provider is provider.

Provider child tags

The provider tag doesn't have any child tags.

Provider attributes

title

The name of the provider. Can be internationalised using the lang attribute. This is a mandatory tag, it cannot be omitted.

uploadurl

An URL to upload data to. This attribute is mutually exclusive with nouploadurl. It should refer to a remote directory, so that VFS implementations just need to copy over the required files. Examples for upload URL classes are FTP and WebDAV. Uploaded files might or might not be subject to going through a moderator queue, depending on the provider configuration.

downloadurl

An URL to download data from. This is the generic "GHNS feed" URL. There might however be separate feeds (variants) with differing contents. Three of them are recognised and may be given as additional attributes, with a higher priority than the pure downloadurl attribute in such a case: downloadurl-latest is a GHNS feed which contains the latest additions or updates to the database. downloadurl-score contains the entries with the highest score. downloadurl-downloads contains entries with the highest number of downloads so far.

icon

An icon to use in the download and/or upload dialogs. The value of this attribute can be an absolute URL, or it can be a symbolic name which is then resolved by the implementation to load an icon with a certain base name which fits the currently selected desktop icon style.

webaccess

An URL which allows for web access to the repository. This is usually the homepage of the provider and gives a web interface to the repository.

webservice

An URL which either replaces or gets used in addition to uploadurl and downloadurl in case the provider refers to a web service. Details about such services can be found in the DXS specification.

nouploadurl

This attribute is mutually exclusive with uploadurl. It is used whenever no automatic upload is possible, for example, if the provider is based on static files served via HTTP and there is no infrastructure for processing uploads automatically. Rather, if the nouploadurl attribute is given, the user might be redirected to a web page, or otherwise, no upload can happen at all and the user has to send the files by e-mail to the application author, for instance. Examples of URL classes include HTTP and E-Mail (mailto).

Not all of those attributes have to be given, it is however recommended to implement all of them to achieve a higher usability. In case a web service is used, the uploadurl and downloadurl URLs are replaced by a webservice URL, although the web service might also be offered in parallel. If the provider does not support direct uploads, even though uploads via the webservice are possible, then the nouploadurl tag should still be used.

See the 'Provider' file format in the appendix 'Formal Documents' for more details.

Upload format

Upload data includes information about authorship (author name and email), the data part itself (payload, preview and summary) as well as meta information: version, release date and licence. To upload data, the list of providers should be consulted to find out which providers have an upload attribute or a webservice. The root XML tag for the upload file is ghnsupload. The top-level XML tag for the entry is stuff.

Upload attributes

category

The category of this entry. This is an attribute instead of a child tag for faster lookup when traversing the XML tree structure. Have a look at the 'Categories' section to learn about valid values for this attribute. This is a mandatory tag, it cannot be omitted.

Upload child tags

name

The name of the entry. Can be internationalised using the lang attribute. This is a mandatory tag, it cannot be omitted.

author

The full name of the author. Can contain an email attribute to specify the author's email to be displayed in the download dialog, in case this information is not available in the site's registration system. Similarly, an im attribute might refer to instant messenger contact (like Jabber), and a homepage attribute is provided to be able to access the author's homepage. In any case it is recommended to only request such information in case the provider doesn't already have it in some form. This is especially true for content which was not created personally by the uploader. This is a mandatory tag, it cannot be omitted.

licence

A verbose name or acronym of the licence. The actual licence definition itself is given as a link in the licenceurl attribute, which should refer to a web page or text file.

summary

A description of the content. Can be internationalised using the lang attribute. This is a mandatory tag, it cannot be omitted.

changes

In case of subsequent uploads, it is useful especially for data files to describe what has changed. Can be internationalised using the lang attribute.

version

The version number for the content. Can be an arbitrary string. Note that whenever server-side versioning is activated, this number might be overridden and thus not appear in the resulting download feed. This is a mandatory tag, it cannot be omitted.

releasedate

An ISO-8601-Extended formatted date string which corresponds to the date of the release.

preview

The name of an image file which can be used to preview the content. For the upload, this should not refer to a URL, but instead assume that the preview file be local. The file name might be rewritten on the server, and will subsequently be transformed into a URL. Can be internationalised using the lang attribute.

payload

The name of the content file itself. For the upload, this should not refer to a URL, but instead assume that the payload file be local. The file name might be rewritten on the server, and will subsequently be transformed into a URL. Can be internationalised using the lang attribute. This is a mandatory tag, it cannot be omitted.

options

Arbitrary options can be passed in this tag. For instance, wallpaper downloads might specify the image dimensions here.

Note

This tag is under consideration.

Attributes include mimetype to specifiy e.g. the MIME type of icons in an icon set package, and resolution to specify the resolution of icons and images.

checksum

To prevent malworking files from data corruption, a checksum can be calculated before uploading the payload file. After the download, this checksum is checked. This tag should contain a type attribute to denote the checkum type (e.g. 'md5', 'sha1').

signature

Payload can be digitally signed before uploading it. This tag contains an email tag which denotes the email address of the OpenPGP key used here.

Note

The signature handling is not yet finally decided.

See the 'Download' file format in the appendix 'Formal Documents' for more details.

Download format

In the download specification both the meta data given by the author of the contribution and the data aggregated by the web server is contained. One such file may list one or more items. Therefore, in addition to the upload fields, some additions are used for downloads. Some of the fields also have a slightly different semantics, in particular the preview and payload tag. The root XML tag for the download file is ghnsdownload. The top-level XML tag for all the entries is stuff.

Download child tags (in addition to upload child tags)

downloads

Download count of the content. This number should be the absolute number for all versions.

rating

The rating is a value between 0 and 100, with 0 meaning lowest and 100 meaning highest level of appreciation.

See the 'Download' file format in the appendix 'Formal Documents' for more details.

Data item categories

Every data item is assigned a specific category, which is the category attribute in the stuff tag of each entry. How those categories are related to MIME types will be shown here.

Categories are meant to be human-visible distinct groups of entries. Categories are either based on generalised MIME types or, where this is not possible, on the application name. Categories are introduced by the application author. For example, 'icon' might refer to both PNG and SVG icons, if the application (or the desktop) can handle both transparently and hence there should be no difference visible to the GHNS user.

Note

There could be a separate document listing all known categories for higher interoperability.

Note

If the options tag for entries is not used, maybe such options could be added to categories? But this will lead to inferiour user experience.

A. Formal documents

The exact file formats are described using XML Schema Definition (XSD). Alternative formats like Relax-NG and example files might be made available in addition to this specification.

B. Change history

Revision 0.5, 07 February 2007, Josef Spillner. 

  • More information about the various files is given. The provider noupload tag was removed since it was redundant in the presence of the nouploadurl attribute. The release tag in the meta information was removed since it was never really used. The author and licence tags were clarified, removing the need to list licences explicitly in this document. Categories and options were clarified as well, although some changes will certainly be due again. The spelling of the GHNS specification was changed to be more consistent and now uses British English everywhere, since the spelling of the XML tags and attributes within GHNS files already adheres to this. The use of XSD is now the default, obsoleting all DTD files.

Revision 0.4, 26 February 2006, Josef Spillner. 

  • The 'checksum' and 'signature' tags have been added for both ghnsupload and ghnsdownload transfers. In addition, a new tag 'changes' can now be used similarly to the summary tag, except that it will list only what has changed from the previous version. This tag should not be filled in for the first submission. Mandatory tags are now described as such in this specification.

Revision 0.3, 17 December 2005, Josef Spillner. 

  • Replacing 'Version' with 'Revision' in the change history. The 'noupload' and 'nouploadurl' parameters are now documented. The 'uploadurl' and 'downloadurl' attributes were fixed, and a second example in the file 'providers.xml' has been added to clarify the usage of the cases with and without upload support. Some more information about GHNS and DXS has been added to the introduction. The 'downloadurl-*' variants have been added to this specification. Category now replaces the previous 'type' information.

Revision 0.2, 02 July 2005, Josef Spillner. 

  • Merge of the feature sets and description of more or less all available features.

Revision 0.1, 29 April 2005, Josef Spillner. 

  • Initial draft specification. Takes into account the existing software and practice from KNewStuff and art.gnome.org.