{
  "$id": "https://schema.rtemis.org/a3/v1/schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "A3",
  "description": "Amino Acid Annotation (A3) format — structured annotation of amino acid sequences.",
  "type": "object",
  "properties": {
    "$schema": {
      "description": "JSON Schema URI for this A3 document.",
      "type": "string",
      "const": "https://schema.rtemis.org/a3/v1/schema.json"
    },
    "a3_version": {
      "description": "A3 specification version.",
      "type": "string",
      "const": "1.0.0"
    },
    "sequence": {
      "description": "Amino acid sequence in uppercase single-letter code. '*' denotes a stop codon.",
      "type": "string",
      "minLength": 2,
      "pattern": "^[A-Z*]+$"
    },
    "annotations": {
      "type": "object",
      "properties": {
        "site": {
          "description": "Named sets of individual residue positions.",
          "type": "object",
          "propertyNames": { "minLength": 1 },
          "additionalProperties": { "$ref": "#/$defs/positionAnnotationEntry" }
        },
        "region": {
          "description": "Named sets of contiguous sequence spans.",
          "type": "object",
          "propertyNames": { "minLength": 1 },
          "additionalProperties": { "$ref": "#/$defs/rangeAnnotationEntry" }
        },
        "ptm": {
          "description": "Post-translational modifications (positions or ranges).",
          "type": "object",
          "propertyNames": { "minLength": 1 },
          "additionalProperties": { "$ref": "#/$defs/mixedAnnotationEntry" }
        },
        "processing": {
          "description": "Signal peptides, cleavage sites, maturation events (positions or ranges).",
          "type": "object",
          "propertyNames": { "minLength": 1 },
          "additionalProperties": { "$ref": "#/$defs/mixedAnnotationEntry" }
        },
        "variant": {
          "description": "Ordered list of sequence variant records.",
          "type": "array",
          "items": { "$ref": "#/$defs/variantRecord" }
        }
      },
      "required": ["site", "region", "ptm", "processing", "variant"],
      "additionalProperties": false
    },
    "metadata": {
      "description": "Protein metadata.",
      "type": "object",
      "properties": {
        "uniprot_id": {
          "description": "UniProt accession (6- or 10-character format, optional isoform suffix).",
          "type": "string",
          "pattern": "^[A-NR-Z][0-9][A-Z][A-Z0-9]{2}[0-9]([A-Z][A-Z0-9]{2}[0-9])?(-[0-9]+)?$"
        },
        "description": {
          "description": "Human-readable protein description.",
          "type": "string"
        },
        "reference": {
          "description": "Citation or URL.",
          "type": "string"
        },
        "organism": {
          "description": "Species name.",
          "type": "string"
        }
      },
      "additionalProperties": false
    }
  },
  "required": ["sequence", "annotations", "metadata", "a3_version"],
  "additionalProperties": false,
  "$defs": {
    "position": {
      "description": "1-based residue position.",
      "type": "integer",
      "minimum": 1
    },
    "range": {
      "description": "Inclusive [start, end] range pair.",
      "type": "array",
      "items": { "type": "integer", "minimum": 1 },
      "minItems": 2,
      "maxItems": 2
    },
    "positionIndex": {
      "description": "Ordered array of 1-based residue positions.",
      "type": "array",
      "items": { "$ref": "#/$defs/position" },
      "minItems": 1,
      "uniqueItems": true
    },
    "rangeIndex": {
      "description": "Ordered array of [start, end] range pairs.",
      "type": "array",
      "items": { "$ref": "#/$defs/range" },
      "minItems": 1,
      "uniqueItems": true
    },
    "mixedIndex": {
      "description": "Either an array of positions or a homogeneous array of [start, end] range pairs.",
      "anyOf": [
        { "$ref": "#/$defs/positionIndex" },
        { "$ref": "#/$defs/rangeIndex" }
      ]
    },
    "positionAnnotationEntry": {
      "type": "object",
      "properties": {
        "index": { "$ref": "#/$defs/positionIndex" },
        "type": { "type": "string" }
      },
      "required": ["index"],
      "additionalProperties": false
    },
    "rangeAnnotationEntry": {
      "type": "object",
      "properties": {
        "index": { "$ref": "#/$defs/rangeIndex" },
        "type": { "type": "string" }
      },
      "required": ["index"],
      "additionalProperties": false
    },
    "mixedAnnotationEntry": {
      "type": "object",
      "properties": {
        "index": { "$ref": "#/$defs/mixedIndex" },
        "type": { "type": "string" }
      },
      "required": ["index"],
      "additionalProperties": false
    },
    "variantRecord": {
      "description": "Sequence variant record. 'position' is required; all other fields are open.",
      "type": "object",
      "properties": {
        "position": { "$ref": "#/$defs/position" }
      },
      "required": ["position"]
    }
  }
}