Sketch metadata specification

TODO: merge into howto/etch_a_sketch.md

Each sketch must include a JSON file named sketch.json, which contains all the information about the sketch.

Top-level attributes in sketch.json:

Element	Type	Required	Description
manifest	Hash of hashes	Yes	List of files included in the sketch, in the form of a hash indexed by filename. Only files declared in the manifest will be copied when installing a sketch. The manifest hash must contain at least one of: desc (string): file description version (string): file version documentation (boolean): if set to true, the file is considered as documentation, which means it will be shown in the sketch listing produced by the --list option. perm (int): permissions the file should have when installed in octal format. module (boolean): if set to true, the file is considered to be a module and something special happens. comment (string): a comment about the file.
metadata	Hash	Yes	Sketch-specific metadata. See below for the full description of all the metadata fields.
entry_point	String	Yes	The name of the .cf file in which the entry bundle for the sketch is defined. This file must contain an agent bundle with an arbitrary name X, and another agent bundle with the name meta_X (this is, the main bundle name prepended with meta_). The entry point can also be set to null. In this case the sketch is considered as a "library sketch", which will be loaded but not explicitly executed.
interface	Array	Yes	List of files from the sketch that need to be loaded in the CFEngine inputs attribute for the sketch to be functional. This list should include at least the entry_point file, but may include others as needed.
Others	Any	No	Any other attributes may be included, but will not be explicitly used by cf-sketch.

The following table lists all attributes that can be included in the metadata element:

Element	Type	Required	Description
name	String	Yes	Name of the sketch. It can be a simple name (e.g. "sketchname") or include a double-colon-separated namespace (e.g. "NS::sketchname"). All components of the name will be converted to directories when installing the sketch, so for example, "NS::sketchname" will be installed under <basedir>/NS/sketchname/".
version	String	Yes	Sketch version number. It is interpreted as a string for comparison purposes (lexicographical sorting instead of numerical sorting)
license	String	Yes	Name of the open-source license under which the sketch is released. For maximum flexibility, we strongly encourage you to use a permissive license such as MIT, BSD or Apache. The default license for all the sketches in the Design Center is MIT.
tags	Array of strings	Yes	You can assign arbitrary sets of tags to sketches, for identification or classification purposes. All CFEngine-provided sketches have the "cfdc" tag assigned.
authors	Array of strings	Yes	The names of the authors of the sketch.
depends	Hash	Yes	Dependencies of the sketch, expressed as a hash indexed by dependency name. The dependencies can be any of: cfengine: minimum version of CFEngine needed by this sketch. Value must be a hash with at least one element named version, containing the CFEngine version needed. os: list of operating system types supported by this sketch. Each value in the list is matched against the output of the uname -s command. If any of them match, the sketch is installed. This can be overriden using the `--force` option to cf-sketch. Any other string is interpreted as a sketch name, and its value as a hash that must contain at least the version element. cf-sketch will verify that the correct version of any dependencies are installed.
Others	Any	No	Any additional elements included in the metadata hash will not be used by cf-sketch itself, but will be made available to the sketch bundle (together with all the mandatory metadata attributes) during execution as variables of the form $($(prefix)sketch_<attribute>). For example, the sketch name is stored in variable $($(prefix)sketch_name).