PND repository specification

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, it should be possible to perform GET and HEAD operations on the URI node. 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, and is discouraged.

Reference implementation

There is currently only one piece of software that provides repository files, namely the Box PND management system.

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: (Comments added for clarification; JSON files may normally never contain comments)

//NOTE: Fields marked with "OPTIONAL" may be null or missing.

//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.
{
  //Information about the repository. (type: json-object)
  "repository": {

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

    //Repository API version. (type: json-number, aka float)
    //
    //A client may only open a repository file if it supports this version.
    //(implementations need not be backwards-compatible)
    "version":     1.0
  },

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

    //Application (type: json-object)
    {
      //The application's queryable id. (type: json-string, see PXML standard)
      "id":        "viceVIC.pickle",

      //The application version. (type: json-object)
      "version": {
        "major":   2, //(type: int, must be >= 0)
        "minor":   2, //(type: int, must be >= 0)
        "release": 0, //(type: int, must be >= 0)
        "build":   0  //(type: int, must be >= 0)
      },

      //OPTIONAL: The application author. (type: json-string)
      "author":   "Ported by Pickle",

      //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.
      //If the "vendor" is missing, it should be safe to assume that the package comes from a
      //fully trusted vendor.
      "vendor":    "dflemstr",

      //URI to the PND containing the application (type: json-string)
      //
      //URI accepts the following protocols: ["http:", "https:", "ftp:", "data:", "file:"]
      "uri":       "http://dflemstr.dyndns.org:8088/file/package/WPL5JKWK0PTODSWK.pnd",

      //Application 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 application title according to this localization (type: json-string)
          "title": "Vice xVIC",

          //The application description according to this localization. (type: json-string)
          "description": "A VIC Emulator."
        }
      },

      //Application categories. (type: json-array)
      "categories": [
        //Category. (type: json-string)
        //
        //See http://standards.freedesktop.org/menu-spec/latest/apa.html for a list of valid categories.
        "Game"
      ],

      //OPTIONAL: URI to the icon to show to the user (type: json-string)
      //
      //URI accepts the following protocols: ["http:", "https:", "ftp:", "data:", "file:"]
      //(Image of type: image/png, size: The largest side is 64 pixels, e.g. 64x64, 64x46, 32x64. Preferrably square.)
      "icon":     "http://dflemstr.dyndns.org:8088/file/image/WPL5JKWK0PTODSWK.png",
    }
  ]
}