Requirement Levels of AIRR Schema Fields#

Clarification of Terms#

  • The terms “MUST”, “MUST NOT”, “REQUIRED”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY” and “OPTIONAL” are to be interpreted as described in [RFC2119].

  • The terms “IF” and “ONLY IF” are are to be interpreted as sufficent and necessary requirement, respectively.

  • The term “NULL-LIKE” is an extension of the NULL term in SQL and its equivalents in other programming languages, referring to the absence of data in a field (i.e., the field is empty). NULL-LIKE additionally includes the following terms, which also define the reason why the information is missing. As these terms are expected to be provided as text, the field would not be NULL but nevertheless NULL-LIKE (i.e., it lacks biologically interpretable information).

    • not_applicable: There is no meaningful value for this field due to study design (e.g., sex for a phage library).

    • not_collected: Data for this field was not collected during the study.

    • missing: Data for field was collected, but is not available now.

Categories of AIRR Schema Fields#

  • Fields MUST be indicated by the x-airr:miairr property IF and ONLY IF the field or its content is governed by the MiAIRR data standard [Rubelt_2017].

  • The x-airr:miairr property MUST be assigned to one of the following three requirement levels:

    • essential: Information on this field MUST be provided and is considered critical for the meaningful interpretation of the data. Therefore the value of such a field MUST NOT be NULL-LIKE. Due to this strict requirement, this level is only assigned to a small set of fields. Importantly, fields are not elevated to this level based on the fact that the respective information should typically be available to the data generator. This was decided to simplify MiAIRR-compliant data annotation by third parties, who might perform this task based on publicly available information only.

    • important: Information for this field MUST be provided. However, the field MAY be assigned a NULL-LIKE value if the respective information is not available. The majority of fields governed by the MiAIRR data standard are assigned to this level.

    • defined: Information for this field MAY be provided. However, IF information matching the semantic definition of the field is provided, this field MUST be used for reporting.

Compliance with the MiAIRR Data Standard#

  • Compliance to the MiAIRR Data Standard is currently a binary state, i.e., a data either is or is not compliant, there are not “grades” of compliance. However, additional requirements for specific use cases might be defined in the future.

  • Data sets are considered MiAIRR-compliant ONLY IF all essential and important fields are reported.

  • Note that important fields with NULL-LIKE values MUST NOT be dropped from a data set.

  • Implementors of data entry interfaces SHOULD NOT set the default value of important fields to NULL-LIKE values, i.e., users should be required to actively select the values.