Difference between revisions of "PND repository specification"

From Pandora Wiki
Jump to: navigation, search
m (A little clarification on GET and HEAD)
(removed proposal link, that is a category)
 
(34 intermediate revisions by 5 users not shown)
Line 1: Line 1:
This is currently a work in progress. Version 2.0 will be finalized soon; please do not implement until then.
 
 
 
= Overview =
 
= Overview =
 
This is the specification for PND repository files. Such a file represents a PND repository, meaning a source to get PND files from, and should list applications that tracked PND files provide, along with URIs for related files.
 
This is the specification for PND repository files. Such a file represents a PND repository, meaning a source to get PND files from, and should list applications that tracked PND files provide, along with URIs for related files.
  
 
= Logistics =
 
= Logistics =
A PND repository file should be hosted in a known location that can be identified by an URI, and using a REST-enabled or read-only protocol. If the repository URI is using the HTTP protocol, a GET operation on the URI node should retrieve the repository, while a HEAD operation should retrieve header information, useful for client caching. Caching of repository files is encouraged, and a day is the recommended time interval for cache implementations. Client implementations may circumvent any cache specifications if it is deemed necessary to acquire the latest repository file, though. GZip compression over the HTTP protocol does not have to be supported.
+
A PND repository file should be hosted in a known location that can be identified by an URI, and using a REST-enabled or read-only protocol. If the repository URI is using the HTTP protocol, a GET operation on the URI node should retrieve the repository, while a HEAD operation should retrieve header information, useful for client caching; no other operations are supported. If an "updates" URI is given, it need only support GET requests. Caching of repository files is encouraged, and a day is the recommended time interval for cache implementations. Information from the "updates" URI should be added to this cache as necessary. Client implementations may circumvent any cache specifications if it is deemed necessary to acquire the latest complete repository file, though. GZip compression over the HTTP protocol does not have to be supported.
  
 
= Reference implementation =
 
= Reference implementation =
The only current implementation is on [http://op.liquidfists.com/ milkshake's repo], with the [http://op.liquidfists.com/includes/getData.php repository file here].  Also available is code for [https://github.com/dflemstr/box the Box PND management system], though it only supports repository version 1.0, and is not currently being run anywhere.
+
The only current implementation is on [http://repo.openpandora.org/ milkshake's repo], with the [http://repo.openpandora.org/client/masterlist repository file here].  Also available is code for [https://github.com/dflemstr/box the Box PND management system], though it only supports repository version 1.0, and is not currently being run anywhere.
  
 
= Client implementations =
 
= Client implementations =
Line 25: Line 23:
 
//Will use the JSON common-denominator encoding (can be read as ASCII, ISO-8859-1 or UTF-8)
 
//Will use the JSON common-denominator encoding (can be read as ASCII, ISO-8859-1 or UTF-8)
 
//Unicode characters are escaped with "\uXXXX" as per the JSON standard.
 
//Unicode characters are escaped with "\uXXXX" as per the JSON standard.
 +
//URLs containing spaces and special characters should be urlencoded.
 
{
 
{
 
   //Information about the repository. (type: json-object)
 
   //Information about the repository. (type: json-object)
Line 30: Line 29:
  
 
     //User-friendly name of the repo to be shown to the user (type: json-string)
 
     //User-friendly name of the repo to be shown to the user (type: json-string)
     "name":       "The Box",
+
     "name": "milkshakes-repo",
  
 
     //Repository API version. (type: json-number, aka float)
 
     //Repository API version. (type: json-number, aka float)
 
     //
 
     //
 
     //A client may only open a repository file if it supports this version.
 
     //A client may only open a repository file if it supports this version.
     //All 2.X versions will be backwards compatible.  Valid 2.0 will also be valid 2.1 and beyond.
+
     //All 3.X versions will be backwards compatible.  Valid 3.0 will also be
     "version":    2.0
+
    //valid 3.1 and beyond.
 +
     "version": 3.0,
 +
 
 +
     //OPTIONAL: URI to provide access to a client API access.
 +
    //
 +
    //If included, this URI will allow access to do additional things like
 +
    //leave comments,rate applications etc. for that specific repository that
 +
    //supports it.
 +
    "client_api": "http://repo.openpandora.org/client",
 +
 
 +
    //OPTIONAL: URI to retrieve information only on new/updated packages.
 +
    //
 +
    //If included, this URI must contain the substring "%time%".  When used by
 +
    //a client, all instances of this substring must be replaced by the Unix
 +
    //time of the client's last update; i.e. the number of seconds elapsed
 +
    //since midnight Coordinated Universal Time (UTC) of January 1, 1970.
 +
    //
 +
    //When a client requests this data, it should receive data on only the
 +
    //packages that have changed since the given time.  This information should
 +
    //be given in a format identical to the complete repository.  All packages
 +
    //listed must include complete information, not just the information that
 +
    //changed.  Note that this will not include any information on packages
 +
    //that have been removed from the repository; therefore, clients should
 +
    //periodically obtain the full file in order to prevent removed packages
 +
    //from accumulating in their caches.
 +
    "updates": "http://repo.openpandora.org/client/masterlist?last_updated=%time%"
 
   },
 
   },
  
Line 45: Line 69:
 
     {
 
     {
 
       //The package's queryable id. (type: json-string, see PXML standard)
 
       //The package's queryable id. (type: json-string, see PXML standard)
       "id":       "sample-package",
+
       "id": "sample-package",
 +
 
 +
      //URI to the PND containing the application (type: json-string)
 +
      //
 +
      //URI accepts the following protocols:
 +
      //["http:", "https:", "ftp:", "data:", "file:"]
 +
      "uri": "http://repo.openpandora.org/client/download?id=sample-package",
  
 
       //The package version. (type: json-object)
 
       //The package version. (type: json-object)
Line 53: Line 83:
 
         "release": "0", //(type: json-string, with characters 0-9, a-z, A-Z, +, -)
 
         "release": "0", //(type: json-string, with characters 0-9, a-z, A-Z, +, -)
 
         "build":  "0", //(type: json-string, with characters 0-9, a-z, A-Z, +, -)
 
         "build":  "0", //(type: json-string, with characters 0-9, a-z, A-Z, +, -)
         "type":    "release" //OPTIONAL (type: json-string, "alpha", "beta", or "release")
+
         "type":    "release" //(type: json-string, "alpha", "beta", or "release")
 
       },
 
       },
  
       //OPTIONAL: Information on the package author. (type: json-object)
+
       //Package localizations. (type: json-array)
      "author": {
 
        "name":    "packagers name",        //OPTIONAL: Author's name (type: json-string)
 
        "website": "http://www.website.foo", //OPTIONAL: Author's website (type: json-string)
 
        "email":  "user@name.who"          //OPTIONAL: Author's email (type: json-string)
 
      },
 
 
 
      //Application localizations. (type: json-array)
 
 
       //
 
       //
 
       //A localization for "en_US" will always be present.
 
       //A localization for "en_US" will always be present.
Line 69: Line 92:
 
         //Application localization. (type: json-object)
 
         //Application localization. (type: json-object)
 
         //
 
         //
         //Key: Language of this localization. (type: json-string, matches: "[a-z][a-z](_[A-Z][A-Z])?")
+
         //Key: Language of this localization.
 +
        //(type: json-string, matches: "[a-z][a-z](_[A-Z][A-Z])?")
 
         //
 
         //
 
         //This is made up of two parts:
 
         //This is made up of two parts:
         // - The language part. This code is the lower-case, two-letter code as defined by ISO-639.
+
         // - The language part. This code is the lower-case, two-letter code as
         // - OPTIONAL: The country part. This code is the upper-case, two-letter code as defined by
+
        //  defined by ISO-639.
        //  ISO-3166, with an underscore as the prefix.
+
         // - OPTIONAL: The country part. This code is the upper-case, two-
 +
        //  letter code as defined by ISO-3166, with an underscore as the prefix.
 
         "en_US": {
 
         "en_US": {
           //The application title according to this localization. (type: json-string)
+
           //The package title according to this localization.
 +
          //(type: json-string)
 
           "title": "Sample Collection",
 
           "title": "Sample Collection",
  
           //The application description according to this localization. (type: json-string)
+
           //OPTIONAL: The package description according to this localization.
 +
          //(type: json-string)
 
           "description": "This is a really verbose package with a whole lot of stuff."
 
           "description": "This is a really verbose package with a whole lot of stuff."
 
         },
 
         },
Line 88: Line 115:
 
       },
 
       },
  
       //OPTIONAL: URI to the icon to representing this package. (type: json-string)
+
       //OPTIONAL: Any additional textual information on this package.
 +
      //(type: json-string)
 
       //
 
       //
       //URI accepts the following protocols: ["http:", "https:", "ftp:", "data:", "file:"]
+
       //This was added to carry the "Additional info" that can be written by
       //(Image of type: image/png, size: Preferrably square, 64x64.)
+
      //application uploaders to milkshake's repo.  This can be adapted to
       "icon":     "http://dflemstr.dyndns.org:8088/file/image/WPL5JKWK0PTODSWK.png"
+
       //carry any human-readable textual information that the repository
 +
      //maintainer finds useful.
 +
       "info": "Version 1.0: Made more verbose",
  
       //URI to the PND containing the application (type: json-string)
+
       //OPTIONAL: The filesize of the PND file, in bytes (type: int)
      //
+
       "size": 137282,
      //URI accepts the following protocols: ["http:", "https:", "ftp:", "data:", "file:"]
 
       "uri":       "http://dflemstr.dyndns.org:8088/file/package/WPL5JKWK0PTODSWK.pnd",
 
  
       //The MD5 hash of the PND file, encoded as a hexadecimal value. (type: json-string)
+
       //OPTIONAL: The MD5 hash of the PND file, encoded as a hexadecimal value.
 +
      //(type: json-string)
 
       "md5":      "d3de733c68b55538bb9c9ff46699c154",
 
       "md5":      "d3de733c68b55538bb9c9ff46699c154",
  
       //OPTIONAL: The application vendor. (type: json-string)
+
       //OPTIONAL: The Unix time at which the PND was added/modified. (type: int)
      //
+
       "modified-time": 1306600048,
      //This is e.g. the uploader of the file, or the company, etc.
 
      //This is useful for networks-of-trust, e.g. an auto-update app might ask the user before
 
      //upgrading an app with a new version from a different vendor.
 
      "vendor":    "dflemstr",
 
 
 
      //OPTIONAL: People who have verified this package's safety. (type: json-array)
 
       //
 
      //This extends the networks-of-trust concept through other users of the repository.
 
      //This should list usernames of people who have tested the application and verified
 
      //it to be safe.  The client can trust the package if the client trusts any of these
 
      //users.  If the repository only allows approval by a small group of trusted admins,
 
      //then having any names listed in here should imply that the package is fully trusted.
 
      "approved": [
 
        "Tempel"
 
      ]
 
  
 
       //OPTIONAL: The overall rating given to this package.
 
       //OPTIONAL: The overall rating given to this package.
 
       //(type: int, in range 0-100 inclusive)
 
       //(type: int, in range 0-100 inclusive)
       "rating": 87
+
       "rating": 87,
  
       //OPTIONAL: List of applications contained in this package. (type: json-array)
+
       //OPTIONAL: Information on the package author. (type: json-object)
       "applications": [
+
       "author": {
         //Application (type: json-object)
+
         "name": "packagers name", //OPTIONAL: Author's name (type: json-string)
         {
+
         "website": "http://www.website.foo", //OPTIONAL: Author's website (type: json-string)
          //The following fields - id, version, author, localizations, and icon - have
+
        "email": "user@name.who" //OPTIONAL: Author's email (type: json-string)
          //the same meaning, types, and restrictions as the corresponding package fields
+
      },
          //given above.
 
  
          "id": "sample-app1",
+
      //OPTIONAL: The application vendor. (type: json-string)
 +
      //
 +
      //This is e.g. the uploader of the file, or the company, etc.
 +
      //This is useful for networks-of-trust, e.g. an auto-update app might ask
 +
      //the user before upgrading an app with a new version from a different vendor.
 +
      "vendor": "Ivanovic",
  
          "version": {
+
      //OPTIONAL: URI to the icon to representing this package. (type: json-string)
            "major": "1",
+
      //
            "minor": "18",
+
      //URI accepts the following protocols:
            "release": "0",
+
      //["http:", "https:", "ftp:", "data:", "file:"]
            "build": "0",
+
      //(Image of type: image/png, size: Preferrably square, 64x64.)
            "type": "alpha"
+
      "icon": "http://repo.openpandora.org/files/pnd/sample-package/icon.png",
          },
 
  
          //OPTIONAL
+
      //OPTIONAL: A list of URIs to application preview pictures.
          "author": {
+
      //(type: json-array)
            "name": "the authors name",
+
      "previewpics": [
            "website": "http://www.openpandora.org"
+
        "http://repo.openpandora.org/files/pnd/sample-package/screen1.png",
            "email": "author@openpandora.org"
+
        "http://repo.openpandora.org/files/pnd/sample-package/screen2.png"
          },
 
 
 
          "localizations": {
 
            "en_US": {
 
              "title": "Sample Application 1",
 
              "description": "A really lenghty description for the application."
 
            },
 
            "de_DE": {
 
              "title": "Beispiel Anwendung 1",
 
              "description": "Die Beschreibung einer Beispielanwendung."
 
            }
 
          },
 
 
 
          //OPTIONAL
 
          "icon": "http://dflemstr.dyndns.org:8088/file/image/FDKXL9LD1200GHG.png",
 
 
 
          //OPTIONAL: A list of URIs to application preview pictures. (type: json-array)
 
          "previewpics": [
 
            //Image URI (type: json-string)
 
            //
 
            //URI accepts the following protocols: ["http:", "https:", "ftp:", "data:", "file:"]
 
            //(Image of type: image/png)
 
            "http://dflemstr.dyndns.org:8088/file/image/IFLWQK32043ISNT.png",
 
            "http://dflemstr.dyndns.org:8088/file/image/LGOI32DOE032DNG.png"
 
          ],
 
 
 
          //OPTIONAL: The licenses under which this application is made available. (type: json-array)
 
          "licenses": [
 
            //Short license identifier. (type: json-string)
 
            //
 
            //There are currently no conventions here on how to uniquely identify a
 
            //license (eg. GPL2 or GPLv2).  Therefore, a client should not rely on any
 
            //specific conventions.
 
            "GPL2"
 
          ],
 
 
 
          //OPTIONAL: The URIs at which source code for the application and included libraries can be
 
          //found (type: json-array)
 
          //Need not be direct download links.
 
          "source": [
 
            "git://git.openpandora.org/special_project"
 
          ],
 
 
 
          //OPTIONAL: Application categories. (type: json-array)
 
          //Note that subcategories are listed directly alongside main categories, as
 
          //they would appear in a .desktop file.
 
          "categories": [
 
            //Category. (type: json-string)
 
            //See http://standards.freedesktop.org/menu-spec/latest/apa.html for a list of valid categories.
 
            "Game",
 
            "System",
 
            "Emulator"
 
          ]
 
        }
 
 
       ],
 
       ],
  
       //OPTIONAL: These four fields - previewpics, licenses, source, and categories -
+
       //OPTIONAL: The licenses under which this application is made available.
      //should only be included if the "applications" array is not. In a PXML, this data
+
       //(type: json-array)
       //only appears on a per-app basis, not per-package.  Therefore, a repository should
 
      //only include these if it does not have information on individual applications.
 
      //If a repository includes these fields both here and in the applications array,
 
      //clients should ignore these fields in favour of those in the applications array.
 
      "previewpics": [
 
        "http://dflemstr.dyndns.org:8088/file/image/IFLWQK32043ISNT.png",
 
        "http://dflemstr.dyndns.org:8088/file/image/LGOI32DOE032DNG.png"
 
      ],
 
 
       "licenses": [
 
       "licenses": [
 
         "GPL"
 
         "GPL"
 
       ],
 
       ],
 +
 +
      //OPTIONAL: The URIs at which source code for the application and
 +
      //included libraries can be found (type: json-array)
 +
      //
 +
      //Need not be direct download links.
 
       "source": [
 
       "source": [
 
         "git://git.openpandora.org/special_project"
 
         "git://git.openpandora.org/special_project"
 
       ],
 
       ],
 +
 +
      //OPTIONAL: Application categories. (type: json-array)
 +
      //
 +
      //Note that subcategories are listed directly alongside main categories, as
 +
      //they would appear in a .desktop file.
 +
      //See http://standards.freedesktop.org/menu-spec/latest/apa.html for a
 +
      //list of valid categories.
 
       "categories": [
 
       "categories": [
            "Game",
+
        "Game",
            "System",
+
        "System",
            "Emulator"
+
        "Emulator",
 +
        "StrategyGame"
 
       ]
 
       ]
  
Line 229: Line 197:
 
}
 
}
 
</source>
 
</source>
 
see other [[proposals]]
 
 
  
 
[[Category:PND]]
 
[[Category:PND]]
 +
[[Category:Ideas and proposals]]
 +
[[Category:Community]]

Latest revision as of 20:11, 25 October 2013

Overview

This is the specification for PND repository files. Such a file represents a PND repository, meaning a source to get PND files from, and should list applications that tracked PND files provide, along with URIs for related files.

Logistics

A PND repository file should be hosted in a known location that can be identified by an URI, and using a REST-enabled or read-only protocol. If the repository URI is using the HTTP protocol, a GET operation on the URI node should retrieve the repository, while a HEAD operation should retrieve header information, useful for client caching; no other operations are supported. If an "updates" URI is given, it need only support GET requests. Caching of repository files is encouraged, and a day is the recommended time interval for cache implementations. Information from the "updates" URI should be added to this cache as necessary. Client implementations may circumvent any cache specifications if it is deemed necessary to acquire the latest complete repository file, though. GZip compression over the HTTP protocol does not have to be supported.

Reference implementation

The only current implementation is on milkshake's repo, with the repository file here. Also available is code for the Box PND management system, though it only supports repository version 1.0, and is not currently being run anywhere.

Client implementations

Clients should store lists of URIs to repository files and download files from these URIs on demand, respecting cache metadata. They may use HEAD requests on HTTP repository URIs to get information about expiry times that the repository files may have. It should NOT be possible to perform head operations on actual downloadable files, however; repository URI references should be immutable, and a tracked URI must always point to the same data.

Format

The repository file should be in a text/json format, as described below.

  • All fields marked with "OPTIONAL" may be missing.
  • All other fields must be present with appropriate data. There are very few, so it shouldn't be hard.
  • Additional unofficial fields may be added by repository maintainers; these fields should use keys formed as "x-reponame-field" so as to avoid conflicts with other repositories or future spec versions.

(Comments added for clarification; JSON files may normally never contain comments)

//Repository file. (type: json-object)
//
//Will use the JSON common-denominator encoding (can be read as ASCII, ISO-8859-1 or UTF-8)
//Unicode characters are escaped with "\uXXXX" as per the JSON standard.
//URLs containing spaces and special characters should be urlencoded.
{
  //Information about the repository. (type: json-object)
  "repository": {

    //User-friendly name of the repo to be shown to the user (type: json-string)
    "name": "milkshakes-repo",

    //Repository API version. (type: json-number, aka float)
    //
    //A client may only open a repository file if it supports this version.
    //All 3.X versions will be backwards compatible.  Valid 3.0 will also be
    //valid 3.1 and beyond.
    "version": 3.0,

    //OPTIONAL: URI to provide access to a client API access.
    //
    //If included, this URI will allow access to do additional things like
    //leave comments,rate applications etc. for that specific repository that
    //supports it.
    "client_api": "http://repo.openpandora.org/client",

    //OPTIONAL: URI to retrieve information only on new/updated packages.
    //
    //If included, this URI must contain the substring "%time%".  When used by
    //a client, all instances of this substring must be replaced by the Unix
    //time of the client's last update; i.e. the number of seconds elapsed
    //since midnight Coordinated Universal Time (UTC) of January 1, 1970.
    //
    //When a client requests this data, it should receive data on only the
    //packages that have changed since the given time.  This information should
    //be given in a format identical to the complete repository.  All packages
    //listed must include complete information, not just the information that
    //changed.  Note that this will not include any information on packages
    //that have been removed from the repository; therefore, clients should
    //periodically obtain the full file in order to prevent removed packages
    //from accumulating in their caches.
    "updates": "http://repo.openpandora.org/client/masterlist?last_updated=%time%"
  },

  //Information about the PND packages in the repo. (type: json-array)
  "packages": [

    //Package (type: json-object)
    {
      //The package's queryable id. (type: json-string, see PXML standard)
      "id": "sample-package",

      //URI to the PND containing the application (type: json-string)
      //
      //URI accepts the following protocols:
      //["http:", "https:", "ftp:", "data:", "file:"]
      "uri": "http://repo.openpandora.org/client/download?id=sample-package",

      //The package version. (type: json-object)
      "version": {
        "major":   "1", //(type: json-string, with characters 0-9, a-z, A-Z, +, -)
        "minor":   "0", //(type: json-string, with characters 0-9, a-z, A-Z, +, -)
        "release": "0", //(type: json-string, with characters 0-9, a-z, A-Z, +, -)
        "build":   "0", //(type: json-string, with characters 0-9, a-z, A-Z, +, -)
        "type":    "release" //(type: json-string, "alpha", "beta", or "release")
      },

      //Package localizations. (type: json-array)
      //
      //A localization for "en_US" will always be present.
      "localizations": {
        //Application localization. (type: json-object)
        //
        //Key: Language of this localization.
        //(type: json-string, matches: "[a-z][a-z](_[A-Z][A-Z])?")
        //
        //This is made up of two parts:
        // - The language part. This code is the lower-case, two-letter code as
        //   defined by ISO-639.
        // - OPTIONAL: The country part. This code is the upper-case, two-
        //   letter code as defined by ISO-3166, with an underscore as the prefix.
        "en_US": {
          //The package title according to this localization.
          //(type: json-string)
          "title": "Sample Collection",

          //OPTIONAL: The package description according to this localization.
          //(type: json-string)
          "description": "This is a really verbose package with a whole lot of stuff."
        },
        "de_DE": {
          "title": "Beispiel Sammlung",
          "description": "Die gleiche Beschreibung wie oben, nur auf deutsch."
        }
      },

      //OPTIONAL: Any additional textual information on this package.
      //(type: json-string)
      //
      //This was added to carry the "Additional info" that can be written by
      //application uploaders to milkshake's repo.  This can be adapted to
      //carry any human-readable textual information that the repository
      //maintainer finds useful.
      "info": "Version 1.0: Made more verbose",

      //OPTIONAL: The filesize of the PND file, in bytes (type: int)
      "size": 137282,

      //OPTIONAL: The MD5 hash of the PND file, encoded as a hexadecimal value.
      //(type: json-string)
      "md5":      "d3de733c68b55538bb9c9ff46699c154",

      //OPTIONAL: The Unix time at which the PND was added/modified. (type: int)
      "modified-time": 1306600048,

      //OPTIONAL: The overall rating given to this package.
      //(type: int, in range 0-100 inclusive)
      "rating": 87,

      //OPTIONAL: Information on the package author. (type: json-object)
      "author": {
        "name": "packagers name", //OPTIONAL: Author's name (type: json-string)
        "website": "http://www.website.foo", //OPTIONAL: Author's website (type: json-string)
        "email": "user@name.who" //OPTIONAL: Author's email (type: json-string)
      },

      //OPTIONAL: The application vendor. (type: json-string)
      //
      //This is e.g. the uploader of the file, or the company, etc.
      //This is useful for networks-of-trust, e.g. an auto-update app might ask
      //the user before upgrading an app with a new version from a different vendor.
      "vendor": "Ivanovic",

      //OPTIONAL: URI to the icon to representing this package. (type: json-string)
      //
      //URI accepts the following protocols:
      //["http:", "https:", "ftp:", "data:", "file:"]
      //(Image of type: image/png, size: Preferrably square, 64x64.)
      "icon": "http://repo.openpandora.org/files/pnd/sample-package/icon.png",

      //OPTIONAL: A list of URIs to application preview pictures.
      //(type: json-array)
      "previewpics": [
        "http://repo.openpandora.org/files/pnd/sample-package/screen1.png",
        "http://repo.openpandora.org/files/pnd/sample-package/screen2.png"
      ],

      //OPTIONAL: The licenses under which this application is made available.
      //(type: json-array)
      "licenses": [
        "GPL"
      ],

      //OPTIONAL: The URIs at which source code for the application and
      //included libraries can be found (type: json-array)
      //
      //Need not be direct download links.
      "source": [
        "git://git.openpandora.org/special_project"
      ],

      //OPTIONAL: Application categories. (type: json-array)
      //
      //Note that subcategories are listed directly alongside main categories, as
      //they would appear in a .desktop file.
      //See http://standards.freedesktop.org/menu-spec/latest/apa.html for a
      //list of valid categories.
      "categories": [
        "Game",
        "System",
        "Emulator",
        "StrategyGame"
      ]

    }
  ]
}