Querying the CTAN Database with JSON – Package

The information about a single package can be obtained under the URL like

http://www.ctan.org/json/1.0/pkg/tex

The last element in the URL is the key of the package as used by CTAN. Those keys are also listed in the list of packages.

The result is a JSON object as in the following listing (with line breaking and indentation for improved readability):

{"id":"tex",
 "name":"TeX",
 "caption":"A sophisticated typesetting engine",
 "authors":[{"id":"knuth","active":true}],
 "copyright":[{"owner":"D. E. Knuth","year":"1982"}],
 "license":"knuth",
 "version":{"number":"3.14159265","date":"2014-01-07"},
 "descriptions":[{"description":"TeX is a typesetting system that incorporates a macro processor.\nA TeX source document specifies or incorporates a number of macro\ndefinitions that instruct the TeX engine how to typeset the\ndocument.  The TeX engine also uses font metrics generated by\nMetafont, or by any of several other\nmechanisms that incorporate fonts from other sources into an\nenvironment suitable for TeX.\n\nTeX has been, and continues, a basis and an inspiration for\nseveral other programs, including e-TeX\nand PDFTeX.\n\nThe distribution includes the source of Knuth’s\nTeX book; this source is there to read, as an\nexample of writing TeX — it should not be processed\nwithout Knuth’s direct permission."],
                  "lang":null}],
 "ctan":{"path":"/systems/knuth/dist/tex",
         "file":true},
 "miktex":"miktex-tex-bin-2.9",
 "texlive":"tex",
 "topics":["engine"]}   

The entry object has several attributes:

id

This attribute contains the unique id of the package. This attribute is mandatory.

name

The entry has the mandatory attribute <name>. The name contains the print representation of the package name.

caption

The entry has the mandatory attribute <caption>. The caption contains a short description of the package.

authors

The entry has the attribute authors which contains a list of authors. The author is a object which has several attributes:

id

This attribute contains the id of the author. This attribute is mandatory.

givenname

This attribute contains the given name. It is optional and can be empty.

familyname

This attribute is the family name. It is optional and can be empty.

copyright

The entry can have a list-valued attribute copyright. It carries the information about the copyright. This list contains objects which have several attributes:

owner

This attribute contains the name of the copyright holder. This attribute is mandatory.

year

This attribute contains the year or years of the copyright. This attribute is mandatory.

license

The entry can have an attribute license. The value can be either a string or a list of strings with keys of licenses.

version

The entry has the attribute version. It carries the information about the version of the package. This object has several attributes:

number

This attribute contains the version number.

date

This attribute contains the version date.

At least one of number or date have to be given. Otherwise the tag is suppressed.

descriptions

The entry has a list of description objects. It may have attributes:

description

This attribute contains the longer description of the package. It may include HTML markup.

lang

This attribute contains the ISO code for the language of the description. Alternately it may be null to indicate the default language, i.e. English.

<ref>

An inner tag of <description> is <ref>. It is used to reference a package. The tag may have an attribute:

refid

This attribute contains the reference.

documentation

The entry has the list attribute documentation. The list elements indicate references to documentation. The objects may have attributes:

lang

This attribute contains the ISO code for the language of the description.

details

This attribute contains the (English) text describing this documentation item.

href

This attribute contains a reference to the documentation. The prefix ctan: indicates a reference to a directory on CTAN. If the parameter keep-url is true then this attribute contains always a valid URL without the ctan: prefix.

ctan

The entry has the optional attribute ctan. It carries the location of the package in the CTAN tree. This JSON object has several attributes:

path

This attribute contains the relative path of the package in the CTAN tree. This attribute is mandatory.

file

This attribute contains the indicator that this package consists of a single file only. This is in contrast to a whole package directory. This attribute is optional and defaults to false.

install

The entry has the optional attribute install. It carries the location of the package on CTAN in form of an installable TDS-compliant zip archive. This JSON object has several attributes:

path

This attribute contains path relative to the CTAN directory /install. This attribute is mandatory.

miktex

The entry has the optional attribute miktex. It carries the name of the package in MiKTeX. This JSON object has several attributes:

location

This attribute contains name of the package in MiKTeX. This attribute is mandatory.

texlive

The entry has the optional attribute texlive. It carries the name of the package in TeX Live. This JSON object has several attributes:

location

This attribute contains name of the package in TeX Live. This attribute is mandatory.

index

The entry has the optional attribute index. If present then it contains a list of extra terms to be indexed for the search.

topics

The entry has the optional attribute topics. If present then it contains a list of topics keys for this entry.

home

The entry has the optional attribute home. If present then it contains the URL of the home page of the package.

Expanding Author Information

The author information is contained as id referencing an entry in the authors file. If the parameter author-name can be set to true to include the first name and family name of the author as well. Example:

http://www.ctan.org/json/1.0/pkg/tex?author-name=true

Selecting Fields

Sometimes it might be desirable to get some of the fields only. This can be accomplished with the parameter drop. It takes a comma separated list of fields to drop. Example:

http://www.ctan.org/json/1.0/pkg/tex?drop=documentation,description

The following fields are recognized in the drop list:

author, caption, copyright, ctan, description, documentation, home, index, install, miktex, name, texlive, topic, version