Feature Request: Add JSON Schema Description for AlphaMissense JSON Files

[berntpopp]

Description

To improve the usability and interoperability of the AlphaMissense JSON files, I propose adding a JSON schema description that follows schema.org standards. This will provide a clear definition of the structure, data types, and constraints for the JSON files, making it easier for developers to validate and use the data.

Requirements

1. Create a JSON Schema:

   • Define the structure of the AlphaMissense JSON files using a JSON schema.
   • Ensure that the schema includes all fields, such as uniprot_id, variants, and statistics.
   • Make the schema schema.org compatible, ensuring that common fields follow their standard definitions where applicable.

2. Documentation:

   • Add documentation that explains how to use the JSON schema to validate the AlphaMissense JSON files.
   • Include examples showing how to validate a JSON file against the schema.

3. Placement:

   • Place the JSON schema in a sensible location within the repository (e.g., a new schema/ directory or inside the scores/json/ directory).
   • Ensure that the repository README includes a reference to the JSON schema, along with usage instructions.

Benefits

• Standardization: Using schema.org will make the data more interoperable and easier to integrate with other systems.
• Validation: The schema will enable users to validate their JSON files, ensuring the correctness of the data.
• Documentation: Clear documentation will help developers understand the structure and expected content of the JSON files.

Example

Here is a basic outline of the JSON schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "AlphaMissense JSON Schema",
  "description": "Schema for AlphaMissense variant data",
  "type": "object",
  "properties": {
    "uniprot_id": {
      "type": "string",
      "description": "The UniProt ID of the protein"
    },
    "variants": {
      "type": "object",
      "additionalProperties": {
        "type": "object",
        "properties": {
          "am_pathogenicity": {
            "type": "number",
            "description": "AlphaMissense pathogenicity score"
          },
          "am_class": {
            "type": "string",
            "description": "AlphaMissense classification"
          }
        }
      }
    },
    "statistics": {
      "type": "object",
      "properties": {
        "total_variants": {
          "type": "integer",
          "description": "Total number of variants"
        },
        "am_class_counts": {
          "type": "object",
          "additionalProperties": {
            "type": "integer"
          }
        },
        "am_pathogenicity_stats": {
          "type": "object",
          "properties": {
            "average": { "type": "number" },
            "min": { "type": "number" },
            "max": { "type": "number" },
            "median": { "type": "number" },
            "quantile_25": { "type": "number" },
            "quantile_75": { "type": "number" }
          }
        },
        "protein_length": {
          "type": "integer",
          "description": "Length of the protein"
        },
        "creation_date": {
          "type": "string",
          "format": "date-time",
          "description": "Creation date of the JSON file"
        },
        "source_file": {
          "type": "string",
          "description": "Source file of the data"
        }
      }
    }
  },
  "required": ["uniprot_id", "variants", "statistics"]
}

Next Steps

• Define the full schema, ensuring it aligns with schema.org standards.
• Add the schema file to the repository and update the documentation accordingly.
• Test the schema with existing JSON files to ensure compatibility.

References

• [JSON Schema Official Documentation](https://json-schema.org/