JSON Schema#

About#

Instead of representing mzPAF as a single string, it can alternatively be expressed as a JSON object. This format is more compatible for inter-program communication, especially through web APIs. You can find the JSON schema for mzPAF on GitHub via the following link:

https://raw.githubusercontent.com/HUPO-PSI/mzPAF/main/specification/annotation-schema.json

Replace main in the URL with the desired version tag to access the schema for a particular version.

Examples#

{
    "$schema": "https://raw.githubusercontent.com/HUPO-PSI/mzPAF/master/specification/annotation-schema.json",
    "adducts": ["M+NH4"],
    "analyte_reference": 1,
    "charge": 2,
    "confidence": 0.5,
    "isotope": 1,
    "mass_error": {
        "value": -0.2,
        "unit": "ppm"
    },
    "molecule_description": {
        "position": 7,
        "series": "y",
        "series_label": "peptide"
    },
    "neutral_losses": ["-H2O"]
}

{
    "$schema": "https://raw.githubusercontent.com/HUPO-PSI/mzPAF/master/specification/annotation-schema.json",
    "neutral_losses": ["-H2O"],
    "isotope": 0,
    "adducts": [],
    "charge": 1,
    "analyte_reference": 1,
    "mass_error": {
        "value": 14.4,
        "unit": "ppm"
    },
    "confidence": null,
    "molecule_description": {
        "series_label": "internal",
        "start_position": 5,
        "end_position": 8
    }
  }

{
    "$schema": "https://raw.githubusercontent.com/HUPO-PSI/mzPAF/master/specification/annotation-schema.json",
    "neutral_losses": [],
    "isotope": 0,
    "adducts": [],
    "charge": 1,
    "analyte_reference": 1,
    "mass_error": {
        "value": -1.7,
        "unit": "ppm"
    },
    "confidence": null,
    "molecule_description": {
        "series_label": "precursor"
    }
}

Full schema documentation#

Properties#

analyte_reference: Label of analyte to which this annotation belongs. Default: null.
- One of
  - integer
  - null
molecule_description (object, required): Description of the molecule or molecule fragment that this peak is annotated with.
- One of
  - : Refer to #/definitions/peptide.
  - : Refer to #/definitions/internal.
  - : Refer to #/definitions/precursor.
  - : Refer to #/definitions/immonium.
  - : Refer to #/definitions/reference.
  - : Refer to #/definitions/named_compound.
  - : Refer to #/definitions/formula.
  - : Refer to #/definitions/smiles.
  - : Refer to #/definitions/unannotated.
neutral_losses (array): Any additional gains or losses of chemical groups defined by formula or by name; multiple may be specified. Default: [].
- Items (string)
isotope: An isotopic peak offset from the monoisotopic peak. Default: [].
- Any of
  - integer
  - array
    - Items
      - Any of
        
        integer
        
        : Refer to #/definitions/isotope_specification.
adducts (array): The charge carrier(s) for the given annotation. Default: [].
- Items (string)
charge (integer): The charge state of the ion generating this peak; this value is unsigned. Minimum: 1. Default: 1.
mass_error: Error between observed and theoretical mass. Default: null.
- One of
  - null
  - : Refer to #/definitions/mass_error.
confidence: Number defining confidence in peak annotation. Default: null.
- One of
  - number
  - null

Definitions#

series_label (string): Type of ion being described, specifies the required molecule description keys. Must be one of: ["peptide", "internal", "precursor", "immonium", "reference", "named_compound", "formula", "smiles", "unannotated"].
mass_error (object): Error between observed and theoretical mass.
- value (number, required): Mass error value.
- unit (string, required): Mass error unit. Must be one of: ["ppm", "Da"]. Default: "Da".
peptide (object): Canonical peptide fragment ion. Cannot contain additional properties.
- series_label: Must be one of: ["peptide"]. Refer to #/definitions/series_label.
- series (string, required): The peptide ion series this ion belongs to. Must be one of: ["b", "y", "a", "x", "c", "z", "d", "v", "w", "da", "db", "wa", "wb"].
- position (integer, required): The position from the appropriate terminal along the peptide this ion was fragmented at (starting with 1). Minimum: 1.
- sequence: A ProForma 2.0 formatted peptidoform sequence describing the ion, which may be useful for contaminants or de novo sequencing.
  - One of
    - string
    - null
internal (object): Internal fragment ion. Cannot contain additional properties.
- series_label: Must be one of: ["internal"]. Refer to #/definitions/series_label.
- start_position (integer, required): N-terminal amino acid residue of the fragment in the original peptide sequence (beginning with 1, counting from the N-terminus). Minimum: 1.
- end_position (integer, required): C-terminal amino acid residue of the fragment in the original peptide sequence (beginning with 1, counting from the N-terminus). Minimum: 1.
- sequence: A ProForma 2.0 formatted peptidoform sequence describing the ion, which may be useful for contaminants or de novo sequencing.
  - One of
    - string
    - null
precursor (object): Precursor ion. Cannot contain additional properties.
- series_label: Must be one of: ["precursor"]. Refer to #/definitions/series_label.
immonium (object): Immonium ion. Cannot contain additional properties.
- series_label: Must be one of: ["immonium"]. Refer to #/definitions/series_label.
- amino_acid (string, required): One-letter code of the amino acid represented by this immonium ion. Length must be equal to 1.
- modification (string): An optional modification that may be attached to this immonium ion.
reference (object): Reference ion. Cannot contain additional properties.
- series_label: Must be one of: ["reference"]. Refer to #/definitions/series_label.
- reference (string, required): The name of a reference molecule or ion defined in a registry.
named_compound (object): named compound ion. Cannot contain additional properties.
- series_label: Must be one of: ["named_compound"]. Refer to #/definitions/series_label.
- compound_name (string, required): The name of the named compound ion being marked.
formula (object): Ion described by chemical formula. Cannot contain additional properties.
- series_label: Must be one of: ["formula"]. Refer to #/definitions/series_label.
- formula (string, required): The elemental formula of the ion being marked.
smiles (object): Ion described by SMILES molecular structure. Cannot contain additional properties.
- series_label: Must be one of: ["smiles"]. Refer to #/definitions/series_label.
- smiles (string, required): The SMILES definition of the ion being marked.
unannotated (object): Unannotated ion. Cannot contain additional properties.
- series_label: Must be one of: ["unannotated"]. Refer to #/definitions/series_label.
- unannotated_label ([‘string’, ‘null’], required): A user-specified numeral label for an unannotated peak.
isotope_specification (object): A defined isotopic variant of another peak. Cannot contain additional properties.
- isotope (integer, required): The number of times this isotope occurs in the chemical composition of the ion.
- variant
  - One of
    - : Refer to #/definitions/element_isotopic_variant.
    - : Refer to #/definitions/average_isotopic_variant.
    - null
element_isotopic_variant (object)
- nucleon_count (integer, required): The number of nucleons this isotope differs in with respect to the monoisotopic isotopologue.
- element (string, required): The name of element the isotopologue comes from.
average_isotopic_variant (object): Cannot contain additional properties.
- averaged (boolean, required): Whether or not the isotopic peak is defined as the “average” isotopomer of the known chemical composition.