docs: add RelativeAllele example and normalization rules

docs/source/concepts/MolecularVariation/RelativeAllele.rst

@@ -7,3 +7,55 @@ Definition and Information Model
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 
 .. include::  ../../def/vrs/RelativeAllele.rst
+
+Example
+@@@@@@@
+
+There are several :ref:`splice-adjacent-examples` with more details.
+Below is an example of a splice acceptor downstream relative allele.
+
+.. code-block:: json
+
+    {
+      "type": "RelativeAllele",
+      "relativeLocation": {
+        "baseSequenceLocation": {
+          "type": "SequenceLocation",
+          "sequenceReference": {
+            "type": "SequenceReference",
+            "id": "NC_000010.11",
+            "refgetAccession": "SQ.ss8r_wB0-b9r44TQTMmVTI92884QvBiB"
+          },
+          "start": 95387120,
+          "end": 95387121
+        },
+        "mappedSequenceLocation": {
+          "sequenceReference": {
+            "type": "SequenceReference",
+            "id": "NM_001034954.3",
+            "refgetAccession": "SQ.SDt4gIJa8ChOmuI3te-3gpbJExmt1dHX"
+          },
+          "anchor": 1543,
+          "anchorOrientation": "right",
+          "offsetStart": -2837,
+          "offsetEnd": -2836
+        }
+      },
+      "mappedState": {
+        "type": "LiteralSequenceExpression",
+        "sequence": "G"
+      },
+      "baseState": {
+        "type": "LiteralSequenceExpression",
+        "sequence": "C"
+      }
+    }
+
+Implementation Guidance
+@@@@@@@@@@@@@@@@@@@@@@@
+
+Normalization
+#############
+
+The ``RelativeAllele`` also includes conventions for variant normalization (see :ref:`relative-allele-normalization`) that allows for compact and
+uniform representation of relative allele variants.

docs/source/conventions/normalization.rst

@@ -225,3 +225,67 @@ is definitional and must be specified using a :ref:`TraversalBlock`.
    depending on orientation.** In the top example, a 100-base sequence is deleted and
    replaced by a 1000-base inverted sequence. In the bottom example, a 100-base inverted
    sequence is inserted, and a 1000-base sequence is duplicated.
+
+
+
+.. _relative-allele-normalization:
+
+Relative Allele Normalization
+@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
+.. admonition:: New in v2.1
+
+   The relativeAllele class was added in v2.1 to describe alleles relative to a mapped sequence
+   from a base sequence alignment.
+
+:ref:`RelativeAllele` normalization differs fundamentally from Allele normalization. Allele normalization
+applies fully-justified expansion to resolve positional ambiguity for indels on a single reference
+sequence. In contrast, a RelativeAllele's location is anchored to a specific alignment boundary
+between two sequences. The anchor and offsets are structurally constrained by the transcript-to-genome
+mapping and are not subject to the same kind of positional ambiguity that fully-justified normalization
+addresses.
+
+Therefore, Allele-style fully-justified normalization MUST NOT be applied to a :ref:`RelativeAllele` —
+doing so could shift the `baseSequenceLocation` away from the position that corresponds to the `anchor + offset`
+mapping, breaking the semantic relationship between the two sequences.
+
+When normalizing a :ref:`RelativeAllele`, the following rules apply:
+
+0. **Preconditions.** Start with an unnormalized RelativeAllele containing a `relativeLocation`
+   (with `baseSequenceLocation` and `mappedSequenceLocation`), a `baseState`, and a `mappedState`.
+
+#. **Normalize nested identifiable objects.** All nested identifiable objects (e.g., SequenceLocation,
+   SequenceReference) MUST be expressed using GA4GH Computed Identifiers, consistent with the general
+   VRS computed identifier requirements.
+
+#. **Normalize the baseSequenceLocation as a SequenceLocation.** The `baseSequenceLocation` is a standard
+   VRS SequenceLocation and MUST be normalized according to SequenceLocation normalization rules
+   (e.g., ensuring refgetAccession is used). However, its `start` and `end` coordinates MUST NOT be altered
+   by Allele-style fully-justified expansion — they represent the resolved genomic position derived from
+   the anchor + offset mapping.
+
+#. **Validate state consistency.** The `baseState` and `mappedState` MUST be consistent with each other given
+   the strand orientation implied by the transcript-to-genome alignment. Specifically:
+
+   * If the mapped sequence is on the positive strand relative to the base sequence, `baseState` and `mappedState`
+     MUST be identical.
+   * If the mapped sequence is on the negative strand (reverse complement), `baseState` MUST be the reverse complement
+     of `mappedState`.
+
+If states are inconsistent, implementations SHOULD raise an error rather than silently correcting, since the
+inconsistency may indicate a data entry error.
+
+4. **Validate offset consistency.** The interval defined by `offsetStart` and `offsetEnd` MUST satisfy `offsetEnd
+   - offsetStart` equal to `end - start` of the `baseSequenceLocation`. That is, the length of the interval on the
+   mapped sequence must equal the length of the interval on the base sequence. Implementations SHOULD raise an
+   error if this constraint is violated.
+
+#. **Return the normalized RelativeAllele.** Construct and return a new RelativeAllele with all nested objects
+   expressed using computed identifiers.
+
+**What is NOT normalized**
+
+* **Anchor position** (`anchor`): Definitional. Determined by the exon boundary in the transcript alignment. Not subject to adjustment.
+* **Anchor orientation** (`anchorOrientation`): Definitional. Determined by splice context (left for donor, right for acceptor).
+* **Offsets** (`offsetStart`, `offsetEnd`): Definitional. Determined by the HGVS offset from the exon boundary.
+* **Base/mapped state sequences** : Not subject to trimming or expansion. The states represent the allele as expressed on their respective sequences and must remain paired.

docs/source/examples/SpliceVariants/index.rst

@@ -1,3 +1,5 @@
+.. _splice-adjacent-examples:
+
 Splice-Adjacent HGVS Variant Examples
 =====================================