Index Specification

Introduction

The index file specification is a canonical specification. By this we mean that it is very strict, has no aliases for field names, does not use YAML tags to designate value type and, with the exception of omitting fields if they have no value, each index file has the exact same structure. The significant advantage of this approach is that no intermediate API is required to utilize a project's metadata.

Fields

Revision

The revision of the index specification is always the year in which the current specification was finalized. Currently that year is 2013.

revision: 2103

If the specification changes and the year is updated, the Indexer API has the functionality to automatically update old specifications to new. But the convenience API of latest version of Indexer always and only supports the latest specification. This helps ensure everyone stays up to date.

Name

The "unix" name of the package. It must be a single word.

name: hello_world

Version

The Version must follow (or at very nearly follow) the semver specification (http://semver.org/).

version: 1.0.0

Codename

The Codename is a arbitraty name given to the particular version.

codename: Lucy Loo

Date

Date is the date the .ruby file was generated. For packages of the project this will be essentially the date a package was released. The format is standard ISO UTC. It can also have an optional HH::MM::SS timestamp.

date: 2011-06-02

Created

Created is the date the project was began. The format is standard ISO UTC. It can also have an optional HH::MM::SS timestamp.

created: 2011-05-29

Title

The title is a single line string.

title: Hello World

Summary

Summary is a one-line summary description of the project.

summary: Say hello to the world!

Description

Description is a multi-line detailed description of the project.

description:
  Hello World allows anyone to  say hello to the world.
  It's fun to do and easy to use.

Authors

Authors list the various primary persons involved in the project. These may be founders, developers or anyone the plays an active role.

authors:
  - name: Thomas T. Thomas
    email: [email protected]
    website: http://tommy.net
    roles: [development]

Suite

The package belongs to a suite of packages, then it can be designated with the suite field. This is somtimes identical to organization.

suite: SpecWorks

Companies / Organizations

The companies field specifies a list of companies or organizations with which the project is assocciated.

companies:
  - name: Spec, Inc.
    email: [email protected]
    website: http://spec.com
    roles: [sponser]

Copyright

The copyrights field is a list of copyright notices broken up into year, holder and optionally license. Each copyright holder may have an associated license for their portion of contribution to a project. The names of license should official spdx.org labels.

copyrights:
  - year: 2012
    holder: Thomas T. Thomas
    license: MIT
  - year: 2010
    holder: James J. James, Jr.

Requirements

Requirements are the packages on which this package depends. Often, referred to as dependencies we have chosen instead the use the term requirements becuase that is what the package actually does with them --it requires them.

requirements:
  - name: facets
    version: 2.9+
  - name: indexer
    version: 1.0.0
    development: true
    groups: [build]

External requirements, that is to say, requirements outside the scope of the typical package manage system, can be designated via the external field.

  - name: libxml
    version: 2.1.0+
    external: true

Arbitrary requirements outside the scope of package management whatsoever, such as "fast graphics card", should not be included here but left as a documentation detail for end users.

Conflicts

Conflicts is a list of projects which have known issues operating in the same process as the present project. The name and optionally a version constraint can be given.

conflicts:
  - name: badmojo
    version: 0+

Alternatives

Alternatives is a list of similar projects that more or less do the same thing as this package. A good example are Ruby markdown parsers redcarpet, rdiscount and BlueCloth. The list might also include projects this project usurps, providing the same functionality and generally the same, or nearly the same, API. A good example is Erubis which is intended to serve as a replacement for ERB.

alternatives:
  - rdiscount
  - BlueCloth

Resources

Resources is a list of universal resource indicators, plus type and label information to describe them.

resources:
  - uri: http://foo.net
    type: homepage
    label: Website
  - uri: http://foot.net/docs
    type: doc
    label: Documentation

One important thing to note about resources is that only the first 3 to 4 characters of the type are typically used to distinguish types. In other words, any resource type that begins with the letters doc is considered a documentation link. Likewise for home in homepage and the like.

Repositories

Repositories is a mapping of repository type to universal resource locator for the package repository.

repositories:
  - uri: http://github.com/fooworks/hello_world.git
    name: upstream
    scm: git

Install Message

The post install message.

install_message: |
  Thanks for installing Hello World!

Load Path

The load_path field provides a list of paths within the project that the load system should search for scripts. This is a rather Ruby oriented field.

load_path:
  - lib

Additional Information

The index specification is open and allows for extraneous metadata to be added in the first and second tier of mappings. This allows any additional data to be included that the specification does not define.

  need: good example

These entries can be strings, numbers, sequence or mappings. Their meaning and format is strictly a function of the consuming application. These should be used sparingly however to protect against name clashes with other uses.