The keywords MUST, SHOULD and MAY (capitalized)

The documents that describe types and/or apps use the following language: (see also RFC2119: )

MUST = mandatory
This word means that the definition is an absolute requirement of the specification.

SHOULD = near-mandatory (but could be violated if absolutely needed)
This word means that the definition is highly recommended, but there may exist valid reasons in particular circumstances to ignore a particular item. However, the full implications must be understood and carefully weighed before choosing a different course.

MAY = optional
This word is used to define an optional feature of the specification.


  • “The details MUST contain a key fragment_length”: means that there will always be a key fragment_length in the details, and that its presence is absolutely necessary with no exceptions.

  • “The JSON details hash MAY contain a key called original_data, whose value is a link to a file containing the original data from which the object was created (e.g., a WIG file)”: means that the original_data key is optional, and there is no guarantee that the details will contain that key.

  • “For a level of resolution N, there SHOULD be no elements whose length (hi - lo) is less than N”: means that the norm is for no such elements to exist (but they could show up nonetheless).

Name conventions for types, details, columns and properties

Types are titlecased with no separation (with the exception of the “gri” type):

  • Reads
  • LetterReads
  • LetterMappings
  • ContigSet

Details and columns names are lowercase, separated with underscores:

  • original_contigset
  • read_groups
  • forward_coverage

Properties are written with their first letter capitalized, separated with spaces, in a form that the author thinks is appropriate for presentation:

  • Lane
  • Instrument model
  • Sample ID
  • Taxonomy ID

Last edited by Phil Sung, 2012-08-17 20:38:58