Skip to content

VRS models

Represent variations, sequence locations, and sequence states with VRS models.

GA4GH VRS models

This module should not be imported directly.

Instead, users should use one of the following:

  • from ga4gh.vrs import models, and refer to models with the abbreviated name, e.g., models.Allele (recommended)

  • import ga4gh.vrs, and refer to models using the fully-qualified module name, e.g., ga4gh.vrs.models.Allele

VrsType

Bases: str, Enum

Define VRS Types

LEN_EXPR class-attribute instance-attribute

LEN_EXPR = 'LengthExpression'

REF_LEN_EXPR class-attribute instance-attribute

REF_LEN_EXPR = 'ReferenceLengthExpression'

LIT_SEQ_EXPR class-attribute instance-attribute

LIT_SEQ_EXPR = 'LiteralSequenceExpression'

SEQ_REF class-attribute instance-attribute

SEQ_REF = 'SequenceReference'

SEQ_LOC class-attribute instance-attribute

SEQ_LOC = 'SequenceLocation'

SEQ_OFFSET_LOCATION class-attribute instance-attribute

SEQ_OFFSET_LOCATION = 'SequenceOffsetLocation'

RELATIVE_SEQ_LOC class-attribute instance-attribute

RELATIVE_SEQ_LOC = 'RelativeSequenceLocation'

ALLELE class-attribute instance-attribute

ALLELE = 'Allele'

RELATIVE_ALLELE class-attribute instance-attribute

RELATIVE_ALLELE = 'RelativeAllele'

CIS_PHASED_BLOCK class-attribute instance-attribute

CIS_PHASED_BLOCK = 'CisPhasedBlock'

ADJACENCY class-attribute instance-attribute

ADJACENCY = 'Adjacency'

TERMINUS class-attribute instance-attribute

TERMINUS = 'Terminus'

TRAVERSAL_BLOCK class-attribute instance-attribute

TRAVERSAL_BLOCK = 'TraversalBlock'

DERIVATIVE_MOL class-attribute instance-attribute

DERIVATIVE_MOL = 'DerivativeMolecule'

CN_COUNT class-attribute instance-attribute

CN_COUNT = 'CopyNumberCount'

CN_CHANGE class-attribute instance-attribute

CN_CHANGE = 'CopyNumberChange'

Orientation

Bases: str, Enum

The orientation of the molecular variation component.

FORWARD class-attribute instance-attribute

FORWARD = 'forward'

REVERSE_COMPLEMENT class-attribute instance-attribute

REVERSE_COMPLEMENT = 'reverse_complement'

ResidueAlphabet

Bases: str, Enum

The interpretation of the character codes referred to by the refget accession, where "aa" specifies an amino acid character set, and "na" specifies a nucleic acid character set.

AA class-attribute instance-attribute

AA = 'aa'

NA class-attribute instance-attribute

NA = 'na'

MoleculeType

Bases: str, Enum

Molecule types as defined by RefSeq <https://www.ncbi.nlm.nih.gov/books/NBK21091/>_ (see Table 1).

GENOMIC class-attribute instance-attribute

GENOMIC = 'genomic'

RNA class-attribute instance-attribute

RNA = 'RNA'

MRNA class-attribute instance-attribute

MRNA = 'mRNA'

PROTEIN class-attribute instance-attribute

PROTEIN = 'protein'

CopyChange

Bases: str, Enum

MUST use one of the defined enumerations that are based on the corresponding EFO ontological terms for copy number variation.

See Implementation Guidance for more details.

COMPLETE_GENOMIC_LOSS class-attribute instance-attribute

COMPLETE_GENOMIC_LOSS = 'complete genomic loss'

HIGH_LEVEL_LOSS class-attribute instance-attribute

HIGH_LEVEL_LOSS = 'high-level loss'

LOW_LEVEL_LOSS class-attribute instance-attribute

LOW_LEVEL_LOSS = 'low-level loss'

LOSS class-attribute instance-attribute

LOSS = 'loss'

REGIONAL_BASE_PLOIDY class-attribute instance-attribute

REGIONAL_BASE_PLOIDY = 'regional base ploidy'

GAIN class-attribute instance-attribute

GAIN = 'gain'

LOW_LEVEL_GAIN class-attribute instance-attribute

LOW_LEVEL_GAIN = 'low-level gain'

HIGH_LEVEL_GAIN class-attribute instance-attribute

HIGH_LEVEL_GAIN = 'high-level gain'

Syntax

Bases: str, Enum

The syntax used to describe the variation. The value should be one of the supported syntaxes.

HGVS_C class-attribute instance-attribute

HGVS_C = 'hgvs.c'

HGVS_P class-attribute instance-attribute

HGVS_P = 'hgvs.p'

HGVS_G class-attribute instance-attribute

HGVS_G = 'hgvs.g'

HGVS_M class-attribute instance-attribute

HGVS_M = 'hgvs.m'

HGVS_N class-attribute instance-attribute

HGVS_N = 'hgvs.n'

HGVS_R class-attribute instance-attribute

HGVS_R = 'hgvs.r'

HGVS_ISCN class-attribute instance-attribute

HGVS_ISCN = 'iscn'

GNOMAD class-attribute instance-attribute

GNOMAD = 'gnomad'

SPDI class-attribute instance-attribute

SPDI = 'spdi'

AnchorOrientation

Bases: str, Enum

Indicates which side of a discontinuous anchor on the sequenceReference is used as the reference point for interpreting offsetStart/offsetEnd.

The anchor is an inter-residue coordinate on the sequenceReference. When that anchor corresponds to a boundary whose realization on a base sequence yields two distinct locations (e.g., an exon junction), this property disambiguates which anchor side on the sequenceReference is intended. left denotes the side immediately preceding the anchor in sequenceReference coordinate order; right denotes the side immediately following the anchor in sequenceReference coordinate order.

LEFT class-attribute instance-attribute

LEFT = 'left'

RIGHT class-attribute instance-attribute

RIGHT = 'right'

VRSMetadataMixin

Bases: GKMMetadataMixin

Provide metadata for a concrete VRS model.

schema_id classmethod

schema_id() -> str

Return the canonical JSON Schema identifier for the model.

Returns:

Type Description
str

Canonical schema URI.

maturity classmethod

maturity() -> Maturity

Return the GKM maturity level for the model.

Returns:

Type Description
Maturity

Declared maturity level.

apply_schema_metadata classmethod

apply_schema_metadata(
    schema: dict[str, Any],
) -> dict[str, Any]

Add GKM metadata to a generated JSON Schema.

Parameters:

Name Type Description Default
schema dict[str, Any]

Generated JSON Schema to mutate in place.

required

Returns:

Type Description
dict[str, Any]

The annotated JSON Schema.

model_json_schema classmethod

model_json_schema(
    by_alias: bool = True,
    ref_template: str = "#/$defs/{model}",
    schema_generator: type[
        GenerateJsonSchema
    ] = GenerateJsonSchema,
    mode: JsonSchemaMode = "validation",
    *,
    union_format: Literal[
        "any_of", "primitive_type_array"
    ] = "any_of",
) -> dict[str, Any]

Generate JSON Schema with GKM metadata.

Default values follow Pydantic defaults.

Parameters:

Name Type Description Default
by_alias bool

Whether to use field aliases.

True
ref_template str

Template for schema references.

'#/$defs/{model}'
schema_generator type[GenerateJsonSchema]

Pydantic schema generator class.

GenerateJsonSchema
mode JsonSchemaMode

Pydantic schema generation mode.

'validation'
union_format Literal['any_of', 'primitive_type_array']

How to represent unions; ignored on Pydantic versions older than 2.12.

'any_of'

Returns:

Type Description
dict[str, Any]

JSON Schema annotated with GKM metadata.

Ga4ghIdentifiableObject

Bases: VRSMetadataMixin, _ValueObject

A contextual value object for which a GA4GH computed identifier can be created.

All GA4GH Identifiable Objects may have computed digests from the VRS Computed Identifier algorithm.

type instance-attribute

type: str

digest class-attribute instance-attribute

digest: (
    Annotated[
        str,
        StringConstraints(pattern="^[0-9A-Za-z_\\-]{32}$"),
    ]
    | None
) = Field(
    default=None,
    description="A sha512t24u digest created using the VRS Computed Identifier algorithm.",
)

id class-attribute instance-attribute

id: str | None = Field(
    default=None,
    description="The 'logical' identifier of the Entity in the system of record, e.g. a UUID.  This 'id' is unique within a given system, but may or may not be globally unique outside the system. It is used within a system to reference an object from another.",
)

name class-attribute instance-attribute

name: str | None = Field(
    default=None,
    description="A primary name for the entity.",
)

description class-attribute instance-attribute

description: str | None = Field(
    default=None,
    description="A free-text description of the Entity.",
)

aliases class-attribute instance-attribute

aliases: list[str] | None = Field(
    default=None,
    description="Alternative name(s) for the Entity.",
)

extensions class-attribute instance-attribute

extensions: list[Extension] | None = Field(
    default=None,
    description="A list of extensions to the Entity, that allow for capture of information not directly supported by elements defined in the model.",
)

ga4gh

Bases: ga4gh

Define GA4GH serialization metadata for this model.

prefix instance-attribute

prefix: str

inherent instance-attribute

inherent: list[str]

__lt__

__lt__(other: Ga4ghIdentifiableObject) -> bool

Compare objects by their computed digests.

Parameters:

Name Type Description Default
other Ga4ghIdentifiableObject

Object to compare.

required

Returns:

Type Description
bool

Whether this digest sorts before the other digest.

is_ga4gh_identifiable staticmethod

is_ga4gh_identifiable() -> bool

Report whether this class supports GA4GH computed identifiers.

Returns:

Type Description
bool

Whether instances are identifiable.

has_valid_ga4gh_id

has_valid_ga4gh_id() -> bool | str | None

Check the existing identifier against the GA4GH identifier pattern.

Returns:

Type Description
bool | str | None

Match status, or the unset or empty identifier.

compute_digest

compute_digest(
    store: bool = True,
    as_version: PrevVrsVersion | None = None,
) -> str

Compute a sha512t24u digest, created using the VRS Computed Identifier algorithm.

Stores the digest in the object if store is True.

If as_version is provided, other parameters are ignored and a digest is returned following the conventions of the VRS version indicated by as_version.

Parameters:

Name Type Description Default
store bool

Save the computed digest on the object.

True
as_version PrevVrsVersion | None

Optional prior VRS version for serialization.

None

Returns:

Type Description
str

Computed digest.

Raises:

Type Description
AttributeError

If prior-version serialization is unsupported.

get_or_create_ga4gh_identifier

get_or_create_ga4gh_identifier(
    in_place: str = "default",
    recompute: bool = False,
    as_version: PrevVrsVersion | None = None,
) -> str

Get a GA4GH computed identifier and optionally update the object ID.

This function has three options for in_place editing of vro.id:

  • 'default': the standard identifier update behavior for GA4GH identifiable objects, this mode will update the vro.id field only when it is None
  • 'always': this will update the vro.id field any time the identifier is computed
  • 'never': the vro.id field will not be edited in-place, even when empty

recompute applies when this call computes an identifier. A valid existing ID returned by the default policy bypasses digest computation. An invalid existing ID is replaced in the return value, but is only stored with the always policy.

If as_version is provided, other parameters are ignored and an identifier is returned following the conventions of the VRS version indicated by as_version.

Parameters:

Name Type Description Default
in_place str

ID update policy: default, always, or never.

'default'
recompute bool

Recompute an existing digest.

False
as_version PrevVrsVersion | None

Optional prior VRS version.

None

Returns:

Type Description
str

GA4GH computed identifier.

Raises:

Type Description
ValueError

If the update policy is invalid.

compute_ga4gh_identifier

compute_ga4gh_identifier(
    recompute: bool = False,
    as_version: PrevVrsVersion | None = None,
) -> str

Return a GA4GH Computed Identifier.

If as_version is provided, other parameters are ignored and a computed identifier is returned following the conventions of the VRS version indicated by as_version.

Parameters:

Name Type Description Default
recompute bool

Recompute an existing digest.

False
as_version PrevVrsVersion | None

Optional prior VRS version.

None

Returns:

Type Description
str

GA4GH computed identifier.

get_or_create_digest

get_or_create_digest(recompute: bool = False) -> str

Return the cached digest, computing and storing it when needed.

Parameters:

Name Type Description Default
recompute bool

Recompute an existing digest when true.

False

Returns:

Type Description
str

Existing or newly computed digest.

schema_id classmethod

schema_id() -> str

Return the canonical JSON Schema identifier for the model.

Returns:

Type Description
str

Canonical schema URI.

maturity classmethod

maturity() -> Maturity

Return the GKM maturity level for the model.

Returns:

Type Description
Maturity

Declared maturity level.

apply_schema_metadata classmethod

apply_schema_metadata(
    schema: dict[str, Any],
) -> dict[str, Any]

Add GKM metadata to a generated JSON Schema.

Parameters:

Name Type Description Default
schema dict[str, Any]

Generated JSON Schema to mutate in place.

required

Returns:

Type Description
dict[str, Any]

The annotated JSON Schema.

model_json_schema classmethod

model_json_schema(
    by_alias: bool = True,
    ref_template: str = "#/$defs/{model}",
    schema_generator: type[
        GenerateJsonSchema
    ] = GenerateJsonSchema,
    mode: JsonSchemaMode = "validation",
    *,
    union_format: Literal[
        "any_of", "primitive_type_array"
    ] = "any_of",
) -> dict[str, Any]

Generate JSON Schema with GKM metadata.

Default values follow Pydantic defaults.

Parameters:

Name Type Description Default
by_alias bool

Whether to use field aliases.

True
ref_template str

Template for schema references.

'#/$defs/{model}'
schema_generator type[GenerateJsonSchema]

Pydantic schema generator class.

GenerateJsonSchema
mode JsonSchemaMode

Pydantic schema generation mode.

'validation'
union_format Literal['any_of', 'primitive_type_array']

How to represent unions; ignored on Pydantic versions older than 2.12.

'any_of'

Returns:

Type Description
dict[str, Any]

JSON Schema annotated with GKM metadata.

__hash__

__hash__() -> int

Hash the canonical JSON representation.

Returns:

Type Description
int

Hash of the serialized value.

ga4gh_serialize

ga4gh_serialize() -> dict

Serialize inherent fields for GA4GH digest computation.

Returns:

Type Description
dict

Mapping of inherent fields to serialized values.

Expression

Bases: VRSMetadataMixin, Element, BaseModelForbidExtra

Representation of a variation by a specified nomenclature or syntax for a Variation object.

Common examples of expressions for the description of molecular variation include the HGVS and ISCN nomenclatures.

model_config class-attribute instance-attribute

model_config = ConfigDict(use_enum_values=True)

syntax class-attribute instance-attribute

syntax: Syntax = Field(
    ...,
    description="The syntax used to describe the variation. The value should be one of the supported syntaxes.",
)

value class-attribute instance-attribute

value: str = Field(
    ...,
    description="The expression of the variation in the specified syntax. The value should be a valid expression in the specified syntax.",
)

syntax_version class-attribute instance-attribute

syntax_version: str | None = Field(
    default=None,
    description="The version of the syntax used to describe the variation. This is particularly important for HGVS expressions, as the syntax has evolved over time.",
)

id class-attribute instance-attribute

id: str | None = Field(
    default=None,
    description="The 'logical' identifier of the data element in the system of record, e.g. a UUID.  This 'id' is unique within a given system, but may or may not be globally unique outside the system. It is used within a system to reference an object from another.",
)

extensions class-attribute instance-attribute

extensions: list[Extension] | None = Field(
    default=None,
    description="A list of extensions to the Entity, that allow for capture of information not directly supported by elements defined in the model.",
)

schema_id classmethod

schema_id() -> str

Return the canonical JSON Schema identifier for the model.

Returns:

Type Description
str

Canonical schema URI.

maturity classmethod

maturity() -> Maturity

Return the GKM maturity level for the model.

Returns:

Type Description
Maturity

Declared maturity level.

apply_schema_metadata classmethod

apply_schema_metadata(
    schema: dict[str, Any],
) -> dict[str, Any]

Add GKM metadata to a generated JSON Schema.

Parameters:

Name Type Description Default
schema dict[str, Any]

Generated JSON Schema to mutate in place.

required

Returns:

Type Description
dict[str, Any]

The annotated JSON Schema.

model_json_schema classmethod

model_json_schema(
    by_alias: bool = True,
    ref_template: str = "#/$defs/{model}",
    schema_generator: type[
        GenerateJsonSchema
    ] = GenerateJsonSchema,
    mode: JsonSchemaMode = "validation",
    *,
    union_format: Literal[
        "any_of", "primitive_type_array"
    ] = "any_of",
) -> dict[str, Any]

Generate JSON Schema with GKM metadata.

Default values follow Pydantic defaults.

Parameters:

Name Type Description Default
by_alias bool

Whether to use field aliases.

True
ref_template str

Template for schema references.

'#/$defs/{model}'
schema_generator type[GenerateJsonSchema]

Pydantic schema generator class.

GenerateJsonSchema
mode JsonSchemaMode

Pydantic schema generation mode.

'validation'
union_format Literal['any_of', 'primitive_type_array']

How to represent unions; ignored on Pydantic versions older than 2.12.

'any_of'

Returns:

Type Description
dict[str, Any]

JSON Schema annotated with GKM metadata.

get_extensions_by_name

get_extensions_by_name(name: str) -> list[Extension]

Fetch all contained extension exactly matching the provided name

Parameters:

Name Type Description Default
name str

name of extension to fetch

required

Returns:

Type Description
list[Extension]

a list of all matching extensions, empty if no matches found (or if instance contains no extensions)

Range

Bases: VRSMetadataMixin, RootModel

An inclusive range of values bounded by one or more integers.

root class-attribute instance-attribute

root: list[int | None] = Field(
    ...,
    json_schema_extra={
        "description": "An inclusive range of values bounded by one or more integers."
    },
    max_length=2,
    min_length=2,
)

validate_range

validate_range(v: list[int | None]) -> list[int | None]

Validate range values

Parameters:

Name Type Description Default
v list[int | None]

Root value

required

Returns:

Type Description
list[int | None]

Inclusive range

Raises:

Type Description
ValueError

If root does not include at least one integer or if the first element in root is greater than the second element in root

schema_id classmethod

schema_id() -> str

Return the canonical JSON Schema identifier for the model.

Returns:

Type Description
str

Canonical schema URI.

maturity classmethod

maturity() -> Maturity

Return the GKM maturity level for the model.

Returns:

Type Description
Maturity

Declared maturity level.

apply_schema_metadata classmethod

apply_schema_metadata(
    schema: dict[str, Any],
) -> dict[str, Any]

Add GKM metadata to a generated JSON Schema.

Parameters:

Name Type Description Default
schema dict[str, Any]

Generated JSON Schema to mutate in place.

required

Returns:

Type Description
dict[str, Any]

The annotated JSON Schema.

model_json_schema classmethod

model_json_schema(
    by_alias: bool = True,
    ref_template: str = "#/$defs/{model}",
    schema_generator: type[
        GenerateJsonSchema
    ] = GenerateJsonSchema,
    mode: JsonSchemaMode = "validation",
    *,
    union_format: Literal[
        "any_of", "primitive_type_array"
    ] = "any_of",
) -> dict[str, Any]

Generate JSON Schema with GKM metadata.

Default values follow Pydantic defaults.

Parameters:

Name Type Description Default
by_alias bool

Whether to use field aliases.

True
ref_template str

Template for schema references.

'#/$defs/{model}'
schema_generator type[GenerateJsonSchema]

Pydantic schema generator class.

GenerateJsonSchema
mode JsonSchemaMode

Pydantic schema generation mode.

'validation'
union_format Literal['any_of', 'primitive_type_array']

How to represent unions; ignored on Pydantic versions older than 2.12.

'any_of'

Returns:

Type Description
dict[str, Any]

JSON Schema annotated with GKM metadata.

residue

Bases: VRSMetadataMixin, RootModel

A character representing a specific residue (i.e., molecular species) or groupings of these ("ambiguity codes"), using one-letter IUPAC abbreviations <https://en.wikipedia.org/wiki/International_Union_of_Pure_and_Applied_Chemistry#Amino_acid_and_nucleotide_base_codes>_ for nucleic acids and amino acids.

root class-attribute instance-attribute

root: Annotated[
    str, StringConstraints(pattern="[A-Z*\\-]")
] = Field(
    ...,
    json_schema_extra={
        "description": 'A character representing a specific residue (i.e., molecular species) or groupings of these ("ambiguity codes"), using [one-letter IUPAC abbreviations](https://en.wikipedia.org/wiki/International_Union_of_Pure_and_Applied_Chemistry#Amino_acid_and_nucleotide_base_codes) for nucleic acids and amino acids.'
    },
)

schema_id classmethod

schema_id() -> str

Return the canonical JSON Schema identifier for the model.

Returns:

Type Description
str

Canonical schema URI.

maturity classmethod

maturity() -> Maturity

Return the GKM maturity level for the model.

Returns:

Type Description
Maturity

Declared maturity level.

apply_schema_metadata classmethod

apply_schema_metadata(
    schema: dict[str, Any],
) -> dict[str, Any]

Add GKM metadata to a generated JSON Schema.

Parameters:

Name Type Description Default
schema dict[str, Any]

Generated JSON Schema to mutate in place.

required

Returns:

Type Description
dict[str, Any]

The annotated JSON Schema.

model_json_schema classmethod

model_json_schema(
    by_alias: bool = True,
    ref_template: str = "#/$defs/{model}",
    schema_generator: type[
        GenerateJsonSchema
    ] = GenerateJsonSchema,
    mode: JsonSchemaMode = "validation",
    *,
    union_format: Literal[
        "any_of", "primitive_type_array"
    ] = "any_of",
) -> dict[str, Any]

Generate JSON Schema with GKM metadata.

Default values follow Pydantic defaults.

Parameters:

Name Type Description Default
by_alias bool

Whether to use field aliases.

True
ref_template str

Template for schema references.

'#/$defs/{model}'
schema_generator type[GenerateJsonSchema]

Pydantic schema generator class.

GenerateJsonSchema
mode JsonSchemaMode

Pydantic schema generation mode.

'validation'
union_format Literal['any_of', 'primitive_type_array']

How to represent unions; ignored on Pydantic versions older than 2.12.

'any_of'

Returns:

Type Description
dict[str, Any]

JSON Schema annotated with GKM metadata.

sequenceString

Bases: VRSMetadataMixin, RootModel

A character string of Residues that represents a biological sequence using the conventional sequence order (5'-to-3' for nucleic acid sequences, and amino-to-carboxyl for amino acid sequences).

IUPAC ambiguity codes are permitted in Sequence Strings.

root class-attribute instance-attribute

root: Annotated[
    str, StringConstraints(pattern="^[A-Z*\\-]*$")
] = Field(
    ...,
    json_schema_extra={
        "description": "A character string of Residues that represents a biological sequence using the conventional sequence order (5'-to-3' for nucleic acid sequences, and amino-to-carboxyl for amino acid sequences). IUPAC ambiguity codes are permitted in Sequence Strings."
    },
)

schema_id classmethod

schema_id() -> str

Return the canonical JSON Schema identifier for the model.

Returns:

Type Description
str

Canonical schema URI.

maturity classmethod

maturity() -> Maturity

Return the GKM maturity level for the model.

Returns:

Type Description
Maturity

Declared maturity level.

apply_schema_metadata classmethod

apply_schema_metadata(
    schema: dict[str, Any],
) -> dict[str, Any]

Add GKM metadata to a generated JSON Schema.

Parameters:

Name Type Description Default
schema dict[str, Any]

Generated JSON Schema to mutate in place.

required

Returns:

Type Description
dict[str, Any]

The annotated JSON Schema.

model_json_schema classmethod

model_json_schema(
    by_alias: bool = True,
    ref_template: str = "#/$defs/{model}",
    schema_generator: type[
        GenerateJsonSchema
    ] = GenerateJsonSchema,
    mode: JsonSchemaMode = "validation",
    *,
    union_format: Literal[
        "any_of", "primitive_type_array"
    ] = "any_of",
) -> dict[str, Any]

Generate JSON Schema with GKM metadata.

Default values follow Pydantic defaults.

Parameters:

Name Type Description Default
by_alias bool

Whether to use field aliases.

True
ref_template str

Template for schema references.

'#/$defs/{model}'
schema_generator type[GenerateJsonSchema]

Pydantic schema generator class.

GenerateJsonSchema
mode JsonSchemaMode

Pydantic schema generation mode.

'validation'
union_format Literal['any_of', 'primitive_type_array']

How to represent unions; ignored on Pydantic versions older than 2.12.

'any_of'

Returns:

Type Description
dict[str, Any]

JSON Schema annotated with GKM metadata.

LengthExpression

Bases: VRSMetadataMixin, _ValueObject, BaseModelForbidExtra

A sequence expressed only by its length.

type class-attribute instance-attribute

type: Literal["LengthExpression"] = Field(
    default=VrsType.LEN_EXPR.value,
    description=f'MUST be "{VrsType.LEN_EXPR.value}"',
)

length class-attribute instance-attribute

length: Range | int | None = Field(
    default=None, description="The length of the sequence."
)

model_config class-attribute instance-attribute

model_config = ConfigDict(extra='forbid')

id class-attribute instance-attribute

id: str | None = Field(
    default=None,
    description="The 'logical' identifier of the Entity in the system of record, e.g. a UUID.  This 'id' is unique within a given system, but may or may not be globally unique outside the system. It is used within a system to reference an object from another.",
)

name class-attribute instance-attribute

name: str | None = Field(
    default=None,
    description="A primary name for the entity.",
)

description class-attribute instance-attribute

description: str | None = Field(
    default=None,
    description="A free-text description of the Entity.",
)

aliases class-attribute instance-attribute

aliases: list[str] | None = Field(
    default=None,
    description="Alternative name(s) for the Entity.",
)

extensions class-attribute instance-attribute

extensions: list[Extension] | None = Field(
    default=None,
    description="A list of extensions to the Entity, that allow for capture of information not directly supported by elements defined in the model.",
)

ga4gh

Bases: ga4gh

Define GA4GH serialization metadata for this model.

inherent class-attribute instance-attribute

inherent = ['length', 'type']

schema_id classmethod

schema_id() -> str

Return the canonical JSON Schema identifier for the model.

Returns:

Type Description
str

Canonical schema URI.

maturity classmethod

maturity() -> Maturity

Return the GKM maturity level for the model.

Returns:

Type Description
Maturity

Declared maturity level.

apply_schema_metadata classmethod

apply_schema_metadata(
    schema: dict[str, Any],
) -> dict[str, Any]

Add GKM metadata to a generated JSON Schema.

Parameters:

Name Type Description Default
schema dict[str, Any]

Generated JSON Schema to mutate in place.

required

Returns:

Type Description
dict[str, Any]

The annotated JSON Schema.

model_json_schema classmethod

model_json_schema(
    by_alias: bool = True,
    ref_template: str = "#/$defs/{model}",
    schema_generator: type[
        GenerateJsonSchema
    ] = GenerateJsonSchema,
    mode: JsonSchemaMode = "validation",
    *,
    union_format: Literal[
        "any_of", "primitive_type_array"
    ] = "any_of",
) -> dict[str, Any]

Generate JSON Schema with GKM metadata.

Default values follow Pydantic defaults.

Parameters:

Name Type Description Default
by_alias bool

Whether to use field aliases.

True
ref_template str

Template for schema references.

'#/$defs/{model}'
schema_generator type[GenerateJsonSchema]

Pydantic schema generator class.

GenerateJsonSchema
mode JsonSchemaMode

Pydantic schema generation mode.

'validation'
union_format Literal['any_of', 'primitive_type_array']

How to represent unions; ignored on Pydantic versions older than 2.12.

'any_of'

Returns:

Type Description
dict[str, Any]

JSON Schema annotated with GKM metadata.

__hash__

__hash__() -> int

Hash the canonical JSON representation.

Returns:

Type Description
int

Hash of the serialized value.

ga4gh_serialize

ga4gh_serialize() -> dict

Serialize inherent fields for GA4GH digest computation.

Returns:

Type Description
dict

Mapping of inherent fields to serialized values.

is_ga4gh_identifiable staticmethod

is_ga4gh_identifiable() -> bool

Report whether this class supports GA4GH computed identifiers.

Returns:

Type Description
bool

Whether instances are identifiable.

ReferenceLengthExpression

Bases: VRSMetadataMixin, _ValueObject, BaseModelForbidExtra

An expression of a length of a sequence from a repeating reference.

type class-attribute instance-attribute

type: Literal["ReferenceLengthExpression"] = Field(
    default=VrsType.REF_LEN_EXPR.value,
    description=f'MUST be "{VrsType.REF_LEN_EXPR.value}"',
)

length class-attribute instance-attribute

length: Range | int = Field(
    ...,
    description="The number of residues in the expressed sequence.",
)

sequence class-attribute instance-attribute

sequence: sequenceString | None = Field(
    default=None,
    description="the literal sequence encoded by the Reference Length Expression.",
)

repeatSubunitLength class-attribute instance-attribute

repeatSubunitLength: int = Field(
    ...,
    description="The number of residues in the repeat subunit.",
)

model_config class-attribute instance-attribute

model_config = ConfigDict(extra='forbid')

id class-attribute instance-attribute

id: str | None = Field(
    default=None,
    description="The 'logical' identifier of the Entity in the system of record, e.g. a UUID.  This 'id' is unique within a given system, but may or may not be globally unique outside the system. It is used within a system to reference an object from another.",
)

name class-attribute instance-attribute

name: str | None = Field(
    default=None,
    description="A primary name for the entity.",
)

description class-attribute instance-attribute

description: str | None = Field(
    default=None,
    description="A free-text description of the Entity.",
)

aliases class-attribute instance-attribute

aliases: list[str] | None = Field(
    default=None,
    description="Alternative name(s) for the Entity.",
)

extensions class-attribute instance-attribute

extensions: list[Extension] | None = Field(
    default=None,
    description="A list of extensions to the Entity, that allow for capture of information not directly supported by elements defined in the model.",
)

ga4gh

Bases: ga4gh

Define GA4GH serialization metadata for this model.

inherent class-attribute instance-attribute

inherent = ['length', 'repeatSubunitLength', 'type']

schema_id classmethod

schema_id() -> str

Return the canonical JSON Schema identifier for the model.

Returns:

Type Description
str

Canonical schema URI.

maturity classmethod

maturity() -> Maturity

Return the GKM maturity level for the model.

Returns:

Type Description
Maturity

Declared maturity level.

apply_schema_metadata classmethod

apply_schema_metadata(
    schema: dict[str, Any],
) -> dict[str, Any]

Add GKM metadata to a generated JSON Schema.

Parameters:

Name Type Description Default
schema dict[str, Any]

Generated JSON Schema to mutate in place.

required

Returns:

Type Description
dict[str, Any]

The annotated JSON Schema.

model_json_schema classmethod

model_json_schema(
    by_alias: bool = True,
    ref_template: str = "#/$defs/{model}",
    schema_generator: type[
        GenerateJsonSchema
    ] = GenerateJsonSchema,
    mode: JsonSchemaMode = "validation",
    *,
    union_format: Literal[
        "any_of", "primitive_type_array"
    ] = "any_of",
) -> dict[str, Any]

Generate JSON Schema with GKM metadata.

Default values follow Pydantic defaults.

Parameters:

Name Type Description Default
by_alias bool

Whether to use field aliases.

True
ref_template str

Template for schema references.

'#/$defs/{model}'
schema_generator type[GenerateJsonSchema]

Pydantic schema generator class.

GenerateJsonSchema
mode JsonSchemaMode

Pydantic schema generation mode.

'validation'
union_format Literal['any_of', 'primitive_type_array']

How to represent unions; ignored on Pydantic versions older than 2.12.

'any_of'

Returns:

Type Description
dict[str, Any]

JSON Schema annotated with GKM metadata.

__hash__

__hash__() -> int

Hash the canonical JSON representation.

Returns:

Type Description
int

Hash of the serialized value.

ga4gh_serialize

ga4gh_serialize() -> dict

Serialize inherent fields for GA4GH digest computation.

Returns:

Type Description
dict

Mapping of inherent fields to serialized values.

is_ga4gh_identifiable staticmethod

is_ga4gh_identifiable() -> bool

Report whether this class supports GA4GH computed identifiers.

Returns:

Type Description
bool

Whether instances are identifiable.

LiteralSequenceExpression

Bases: VRSMetadataMixin, _ValueObject, BaseModelForbidExtra

An explicit expression of a Sequence.

type class-attribute instance-attribute

type: Literal["LiteralSequenceExpression"] = Field(
    default=VrsType.LIT_SEQ_EXPR.value,
    description=f'MUST be "{VrsType.LIT_SEQ_EXPR.value}"',
)

sequence class-attribute instance-attribute

sequence: sequenceString = Field(
    ..., description="the literal sequence"
)

model_config class-attribute instance-attribute

model_config = ConfigDict(extra='forbid')

id class-attribute instance-attribute

id: str | None = Field(
    default=None,
    description="The 'logical' identifier of the Entity in the system of record, e.g. a UUID.  This 'id' is unique within a given system, but may or may not be globally unique outside the system. It is used within a system to reference an object from another.",
)

name class-attribute instance-attribute

name: str | None = Field(
    default=None,
    description="A primary name for the entity.",
)

description class-attribute instance-attribute

description: str | None = Field(
    default=None,
    description="A free-text description of the Entity.",
)

aliases class-attribute instance-attribute

aliases: list[str] | None = Field(
    default=None,
    description="Alternative name(s) for the Entity.",
)

extensions class-attribute instance-attribute

extensions: list[Extension] | None = Field(
    default=None,
    description="A list of extensions to the Entity, that allow for capture of information not directly supported by elements defined in the model.",
)

ga4gh

Bases: ga4gh

Define GA4GH serialization metadata for this model.

inherent class-attribute instance-attribute

inherent = ['sequence', 'type']

schema_id classmethod

schema_id() -> str

Return the canonical JSON Schema identifier for the model.

Returns:

Type Description
str

Canonical schema URI.

maturity classmethod

maturity() -> Maturity

Return the GKM maturity level for the model.

Returns:

Type Description
Maturity

Declared maturity level.

apply_schema_metadata classmethod

apply_schema_metadata(
    schema: dict[str, Any],
) -> dict[str, Any]

Add GKM metadata to a generated JSON Schema.

Parameters:

Name Type Description Default
schema dict[str, Any]

Generated JSON Schema to mutate in place.

required

Returns:

Type Description
dict[str, Any]

The annotated JSON Schema.

model_json_schema classmethod

model_json_schema(
    by_alias: bool = True,
    ref_template: str = "#/$defs/{model}",
    schema_generator: type[
        GenerateJsonSchema
    ] = GenerateJsonSchema,
    mode: JsonSchemaMode = "validation",
    *,
    union_format: Literal[
        "any_of", "primitive_type_array"
    ] = "any_of",
) -> dict[str, Any]

Generate JSON Schema with GKM metadata.

Default values follow Pydantic defaults.

Parameters:

Name Type Description Default
by_alias bool

Whether to use field aliases.

True
ref_template str

Template for schema references.

'#/$defs/{model}'
schema_generator type[GenerateJsonSchema]

Pydantic schema generator class.

GenerateJsonSchema
mode JsonSchemaMode

Pydantic schema generation mode.

'validation'
union_format Literal['any_of', 'primitive_type_array']

How to represent unions; ignored on Pydantic versions older than 2.12.

'any_of'

Returns:

Type Description
dict[str, Any]

JSON Schema annotated with GKM metadata.

__hash__

__hash__() -> int

Hash the canonical JSON representation.

Returns:

Type Description
int

Hash of the serialized value.

ga4gh_serialize

ga4gh_serialize() -> dict

Serialize inherent fields for GA4GH digest computation.

Returns:

Type Description
dict

Mapping of inherent fields to serialized values.

is_ga4gh_identifiable staticmethod

is_ga4gh_identifiable() -> bool

Report whether this class supports GA4GH computed identifiers.

Returns:

Type Description
bool

Whether instances are identifiable.

SequenceReference

Bases: VRSMetadataMixin, _ValueObject, BaseModelForbidExtra

A sequence of nucleic or amino acid character codes.

model_config class-attribute instance-attribute

model_config = ConfigDict(use_enum_values=True)

type class-attribute instance-attribute

type: Literal["SequenceReference"] = Field(
    default=VrsType.SEQ_REF.value,
    description=f'MUST be "{VrsType.SEQ_REF.value}"',
)

refgetAccession class-attribute instance-attribute

refgetAccession: Annotated[
    str,
    StringConstraints(pattern="^SQ.[0-9A-Za-z_\\-]{32}$"),
] = Field(
    ...,
    description="A [GA4GH RefGet](http://samtools.github.io/hts-specs/refget.html) identifier for the referenced sequence, using the sha512t24u digest.",
)

residueAlphabet class-attribute instance-attribute

residueAlphabet: ResidueAlphabet | None = Field(
    default=None,
    description='The interpretation of the character codes referred to by the refget accession, where "aa" specifies an amino acid character set, and "na" specifies a nucleic acid character set.',
)

circular class-attribute instance-attribute

circular: bool | None = Field(
    default=None,
    description="A boolean indicating whether the molecule represented by the sequence is circular (true) or linear (false).",
)

sequence class-attribute instance-attribute

sequence: sequenceString | None = Field(
    default=None,
    description="A sequenceString that is a literal representation of the referenced sequence.",
)

moleculeType class-attribute instance-attribute

moleculeType: MoleculeType | None = Field(
    default=None,
    description="Molecule types as [defined by RefSeq](https://www.ncbi.nlm.nih.gov/books/NBK21091/) (see Table 1). MUST be one of 'genomic', 'RNA', 'mRNA', or 'protein'.",
)

id class-attribute instance-attribute

id: str | None = Field(
    default=None,
    description="The 'logical' identifier of the Entity in the system of record, e.g. a UUID.  This 'id' is unique within a given system, but may or may not be globally unique outside the system. It is used within a system to reference an object from another.",
)

name class-attribute instance-attribute

name: str | None = Field(
    default=None,
    description="A primary name for the entity.",
)

description class-attribute instance-attribute

description: str | None = Field(
    default=None,
    description="A free-text description of the Entity.",
)

aliases class-attribute instance-attribute

aliases: list[str] | None = Field(
    default=None,
    description="Alternative name(s) for the Entity.",
)

extensions class-attribute instance-attribute

extensions: list[Extension] | None = Field(
    default=None,
    description="A list of extensions to the Entity, that allow for capture of information not directly supported by elements defined in the model.",
)

ga4gh

Bases: ga4gh

Define GA4GH serialization metadata for this model.

inherent class-attribute instance-attribute

inherent = ['refgetAccession', 'type']

schema_id classmethod

schema_id() -> str

Return the canonical JSON Schema identifier for the model.

Returns:

Type Description
str

Canonical schema URI.

maturity classmethod

maturity() -> Maturity

Return the GKM maturity level for the model.

Returns:

Type Description
Maturity

Declared maturity level.

apply_schema_metadata classmethod

apply_schema_metadata(
    schema: dict[str, Any],
) -> dict[str, Any]

Add GKM metadata to a generated JSON Schema.

Parameters:

Name Type Description Default
schema dict[str, Any]

Generated JSON Schema to mutate in place.

required

Returns:

Type Description
dict[str, Any]

The annotated JSON Schema.

model_json_schema classmethod

model_json_schema(
    by_alias: bool = True,
    ref_template: str = "#/$defs/{model}",
    schema_generator: type[
        GenerateJsonSchema
    ] = GenerateJsonSchema,
    mode: JsonSchemaMode = "validation",
    *,
    union_format: Literal[
        "any_of", "primitive_type_array"
    ] = "any_of",
) -> dict[str, Any]

Generate JSON Schema with GKM metadata.

Default values follow Pydantic defaults.

Parameters:

Name Type Description Default
by_alias bool

Whether to use field aliases.

True
ref_template str

Template for schema references.

'#/$defs/{model}'
schema_generator type[GenerateJsonSchema]

Pydantic schema generator class.

GenerateJsonSchema
mode JsonSchemaMode

Pydantic schema generation mode.

'validation'
union_format Literal['any_of', 'primitive_type_array']

How to represent unions; ignored on Pydantic versions older than 2.12.

'any_of'

Returns:

Type Description
dict[str, Any]

JSON Schema annotated with GKM metadata.

__hash__

__hash__() -> int

Hash the canonical JSON representation.

Returns:

Type Description
int

Hash of the serialized value.

ga4gh_serialize

ga4gh_serialize() -> dict

Serialize inherent fields for GA4GH digest computation.

Returns:

Type Description
dict

Mapping of inherent fields to serialized values.

is_ga4gh_identifiable staticmethod

is_ga4gh_identifiable() -> bool

Report whether this class supports GA4GH computed identifiers.

Returns:

Type Description
bool

Whether instances are identifiable.

SequenceLocation

Bases: Ga4ghIdentifiableObject, BaseModelForbidExtra

A Location defined by an interval on a Sequence.

type class-attribute instance-attribute

type: Literal["SequenceLocation"] = Field(
    default=VrsType.SEQ_LOC.value,
    description=f'MUST be "{VrsType.SEQ_LOC.value}"',
)

sequenceReference class-attribute instance-attribute

sequenceReference: (
    iriReference | SequenceReference | None
) = Field(
    default=None,
    description="A reference to a SequenceReference on which the location is defined.",
)

start class-attribute instance-attribute

start: Range | int | None = Field(
    default=None,
    description="The start coordinate or range of the SequenceLocation. The minimum value of this coordinate or range is 0. For locations on linear sequences, this MUST represent a coordinate or range less than or equal to the value of `end`. For circular sequences, `start` is greater than `end` when the location spans the sequence 0 coordinate.",
)

end class-attribute instance-attribute

end: Range | int | None = Field(
    default=None,
    description="The end coordinate or range of the SequenceLocation. The minimum value of this coordinate or range is 0. For locations on linear sequences, this MUST represent a coordinate or range greater than or equal to the value of `start`. For circular sequences, `end` is less than `start` when the location spans the sequence 0 coordinate.",
)

sequence class-attribute instance-attribute

sequence: sequenceString | None = Field(
    default=None,
    description="The literal sequence encoded by the `sequenceReference` at these coordinates.",
)

model_config class-attribute instance-attribute

model_config = ConfigDict(extra='forbid')

id class-attribute instance-attribute

id: str | None = Field(
    default=None,
    description="The 'logical' identifier of the Entity in the system of record, e.g. a UUID.  This 'id' is unique within a given system, but may or may not be globally unique outside the system. It is used within a system to reference an object from another.",
)

name class-attribute instance-attribute

name: str | None = Field(
    default=None,
    description="A primary name for the entity.",
)

description class-attribute instance-attribute

description: str | None = Field(
    default=None,
    description="A free-text description of the Entity.",
)

aliases class-attribute instance-attribute

aliases: list[str] | None = Field(
    default=None,
    description="Alternative name(s) for the Entity.",
)

extensions class-attribute instance-attribute

extensions: list[Extension] | None = Field(
    default=None,
    description="A list of extensions to the Entity, that allow for capture of information not directly supported by elements defined in the model.",
)

digest class-attribute instance-attribute

digest: (
    Annotated[
        str,
        StringConstraints(pattern="^[0-9A-Za-z_\\-]{32}$"),
    ]
    | None
) = Field(
    default=None,
    description="A sha512t24u digest created using the VRS Computed Identifier algorithm.",
)

ga4gh

Bases: ga4gh

Define GA4GH serialization metadata for this model.

prefix class-attribute instance-attribute

prefix = 'SL'

priorPrefix class-attribute instance-attribute

priorPrefix = {PrevVrsVersion.V1_3.value: 'VSL'}

inherent class-attribute instance-attribute

inherent = ['end', 'sequenceReference', 'start', 'type']

validate_start_end

validate_start_end(
    v: Range | int | None, info: ValidationInfo
) -> Range | int | None

Validate start and end fields

Parameters:

Name Type Description Default
v Range | int | None

start or end value

required
info ValidationInfo

Validation info

required

Returns:

Type Description
Range | int | None

The validated coordinate or range, or None.

Raises:

Type Description
ValueError

If start or end has a value less than 0

ga4gh_serialize_as_version

ga4gh_serialize_as_version(
    as_version: PrevVrsVersion,
) -> str

Return a serialized string following the conventions for SequenceLocation serialization as defined in the VRS version specified by as_version.

Parameters:

Name Type Description Default
as_version PrevVrsVersion

Prior VRS version to use.

required

Returns:

Type Description
str

Serialization for the requested prior version.

Raises:

Type Description
ValueError

If sequenceReference is not a SequenceReference object; start or end are not an int or list.

TypeError

If the requested version is unsupported.

get_refget_accession

get_refget_accession() -> str | None

Get the sequence reference accession or IRI.

Returns:

Type Description
str | None

Accession or IRI, or None if no reference is available.

schema_id classmethod

schema_id() -> str

Return the canonical JSON Schema identifier for the model.

Returns:

Type Description
str

Canonical schema URI.

maturity classmethod

maturity() -> Maturity

Return the GKM maturity level for the model.

Returns:

Type Description
Maturity

Declared maturity level.

apply_schema_metadata classmethod

apply_schema_metadata(
    schema: dict[str, Any],
) -> dict[str, Any]

Add GKM metadata to a generated JSON Schema.

Parameters:

Name Type Description Default
schema dict[str, Any]

Generated JSON Schema to mutate in place.

required

Returns:

Type Description
dict[str, Any]

The annotated JSON Schema.

model_json_schema classmethod

model_json_schema(
    by_alias: bool = True,
    ref_template: str = "#/$defs/{model}",
    schema_generator: type[
        GenerateJsonSchema
    ] = GenerateJsonSchema,
    mode: JsonSchemaMode = "validation",
    *,
    union_format: Literal[
        "any_of", "primitive_type_array"
    ] = "any_of",
) -> dict[str, Any]

Generate JSON Schema with GKM metadata.

Default values follow Pydantic defaults.

Parameters:

Name Type Description Default
by_alias bool

Whether to use field aliases.

True
ref_template str

Template for schema references.

'#/$defs/{model}'
schema_generator type[GenerateJsonSchema]

Pydantic schema generator class.

GenerateJsonSchema
mode JsonSchemaMode

Pydantic schema generation mode.

'validation'
union_format Literal['any_of', 'primitive_type_array']

How to represent unions; ignored on Pydantic versions older than 2.12.

'any_of'

Returns:

Type Description
dict[str, Any]

JSON Schema annotated with GKM metadata.

__hash__

__hash__() -> int

Hash the canonical JSON representation.

Returns:

Type Description
int

Hash of the serialized value.

ga4gh_serialize

ga4gh_serialize() -> dict

Serialize inherent fields for GA4GH digest computation.

Returns:

Type Description
dict

Mapping of inherent fields to serialized values.

is_ga4gh_identifiable staticmethod

is_ga4gh_identifiable() -> bool

Report whether this class supports GA4GH computed identifiers.

Returns:

Type Description
bool

Whether instances are identifiable.

__lt__

__lt__(other: Ga4ghIdentifiableObject) -> bool

Compare objects by their computed digests.

Parameters:

Name Type Description Default
other Ga4ghIdentifiableObject

Object to compare.

required

Returns:

Type Description
bool

Whether this digest sorts before the other digest.

has_valid_ga4gh_id

has_valid_ga4gh_id() -> bool | str | None

Check the existing identifier against the GA4GH identifier pattern.

Returns:

Type Description
bool | str | None

Match status, or the unset or empty identifier.

compute_digest

compute_digest(
    store: bool = True,
    as_version: PrevVrsVersion | None = None,
) -> str

Compute a sha512t24u digest, created using the VRS Computed Identifier algorithm.

Stores the digest in the object if store is True.

If as_version is provided, other parameters are ignored and a digest is returned following the conventions of the VRS version indicated by as_version.

Parameters:

Name Type Description Default
store bool

Save the computed digest on the object.

True
as_version PrevVrsVersion | None

Optional prior VRS version for serialization.

None

Returns:

Type Description
str

Computed digest.

Raises:

Type Description
AttributeError

If prior-version serialization is unsupported.

get_or_create_ga4gh_identifier

get_or_create_ga4gh_identifier(
    in_place: str = "default",
    recompute: bool = False,
    as_version: PrevVrsVersion | None = None,
) -> str

Get a GA4GH computed identifier and optionally update the object ID.

This function has three options for in_place editing of vro.id:

  • 'default': the standard identifier update behavior for GA4GH identifiable objects, this mode will update the vro.id field only when it is None
  • 'always': this will update the vro.id field any time the identifier is computed
  • 'never': the vro.id field will not be edited in-place, even when empty

recompute applies when this call computes an identifier. A valid existing ID returned by the default policy bypasses digest computation. An invalid existing ID is replaced in the return value, but is only stored with the always policy.

If as_version is provided, other parameters are ignored and an identifier is returned following the conventions of the VRS version indicated by as_version.

Parameters:

Name Type Description Default
in_place str

ID update policy: default, always, or never.

'default'
recompute bool

Recompute an existing digest.

False
as_version PrevVrsVersion | None

Optional prior VRS version.

None

Returns:

Type Description
str

GA4GH computed identifier.

Raises:

Type Description
ValueError

If the update policy is invalid.

compute_ga4gh_identifier

compute_ga4gh_identifier(
    recompute: bool = False,
    as_version: PrevVrsVersion | None = None,
) -> str

Return a GA4GH Computed Identifier.

If as_version is provided, other parameters are ignored and a computed identifier is returned following the conventions of the VRS version indicated by as_version.

Parameters:

Name Type Description Default
recompute bool

Recompute an existing digest.

False
as_version PrevVrsVersion | None

Optional prior VRS version.

None

Returns:

Type Description
str

GA4GH computed identifier.

get_or_create_digest

get_or_create_digest(recompute: bool = False) -> str

Return the cached digest, computing and storing it when needed.

Parameters:

Name Type Description Default
recompute bool

Recompute an existing digest when true.

False

Returns:

Type Description
str

Existing or newly computed digest.

SequenceOffsetLocation

Bases: VRSMetadataMixin, _ValueObject, BaseModelForbidExtra

A location defined by an offset relative to an anchor on a mapped sequence reference.

model_config class-attribute instance-attribute

model_config = ConfigDict(use_enum_values=True)

type class-attribute instance-attribute

type: Literal["SequenceOffsetLocation"] = Field(
    default=VrsType.SEQ_OFFSET_LOCATION.value,
    description=f'MUST be "{VrsType.SEQ_OFFSET_LOCATION.value}"',
)

sequenceReference class-attribute instance-attribute

sequenceReference: SequenceReference | iriReference = Field(
    ...,
    description="A sequence reference that has been mapped from which a relative location is defined.",
)

anchor class-attribute instance-attribute

anchor: int = Field(
    ...,
    description="The inter-residue position on the sequence reference from which the relative location offset is calculated.",
)

anchorOrientation class-attribute instance-attribute

anchorOrientation: AnchorOrientation = Field(
    ...,
    description="Indicates which side of a discontinuous anchor on the sequenceReference is used as the reference point for interpreting offsetStart/offsetEnd. The anchor is an inter-residue coordinate on the sequenceReference. When that anchor corresponds to a boundary whose realization on a base sequence yields two distinct locations (e.g., an exon junction), this property disambiguates which anchor side on the sequenceReference is intended. `left` denotes the side immediately preceding the anchor in sequenceReference coordinate order; `right` denotes the side immediately following the anchor in sequenceReference coordinate order.",
)

offsetStart class-attribute instance-attribute

offsetStart: int | Range | None = Field(
    default=None,
    description="The start offset, in inter-residue coordinates, from the anchor realization selected by anchorOrientation on the sequenceReference.",
)

offsetEnd class-attribute instance-attribute

offsetEnd: int | Range | None = Field(
    default=None,
    description="The end offset, in inter-residue coordinates, from the anchor realization selected by anchorOrientation on the sequenceReference.",
)

id class-attribute instance-attribute

id: str | None = Field(
    default=None,
    description="The 'logical' identifier of the Entity in the system of record, e.g. a UUID.  This 'id' is unique within a given system, but may or may not be globally unique outside the system. It is used within a system to reference an object from another.",
)

name class-attribute instance-attribute

name: str | None = Field(
    default=None,
    description="A primary name for the entity.",
)

description class-attribute instance-attribute

description: str | None = Field(
    default=None,
    description="A free-text description of the Entity.",
)

aliases class-attribute instance-attribute

aliases: list[str] | None = Field(
    default=None,
    description="Alternative name(s) for the Entity.",
)

extensions class-attribute instance-attribute

extensions: list[Extension] | None = Field(
    default=None,
    description="A list of extensions to the Entity, that allow for capture of information not directly supported by elements defined in the model.",
)

ga4gh

Bases: ga4gh

Define GA4GH serialization metadata for this model.

inherent class-attribute instance-attribute

inherent = [
    "sequenceReference",
    "anchor",
    "anchorOrientation",
    "offsetStart",
    "offsetEnd",
    "type",
]

schema_id classmethod

schema_id() -> str

Return the canonical JSON Schema identifier for the model.

Returns:

Type Description
str

Canonical schema URI.

maturity classmethod

maturity() -> Maturity

Return the GKM maturity level for the model.

Returns:

Type Description
Maturity

Declared maturity level.

apply_schema_metadata classmethod

apply_schema_metadata(
    schema: dict[str, Any],
) -> dict[str, Any]

Add GKM metadata to a generated JSON Schema.

Parameters:

Name Type Description Default
schema dict[str, Any]

Generated JSON Schema to mutate in place.

required

Returns:

Type Description
dict[str, Any]

The annotated JSON Schema.

model_json_schema classmethod

model_json_schema(
    by_alias: bool = True,
    ref_template: str = "#/$defs/{model}",
    schema_generator: type[
        GenerateJsonSchema
    ] = GenerateJsonSchema,
    mode: JsonSchemaMode = "validation",
    *,
    union_format: Literal[
        "any_of", "primitive_type_array"
    ] = "any_of",
) -> dict[str, Any]

Generate JSON Schema with GKM metadata.

Default values follow Pydantic defaults.

Parameters:

Name Type Description Default
by_alias bool

Whether to use field aliases.

True
ref_template str

Template for schema references.

'#/$defs/{model}'
schema_generator type[GenerateJsonSchema]

Pydantic schema generator class.

GenerateJsonSchema
mode JsonSchemaMode

Pydantic schema generation mode.

'validation'
union_format Literal['any_of', 'primitive_type_array']

How to represent unions; ignored on Pydantic versions older than 2.12.

'any_of'

Returns:

Type Description
dict[str, Any]

JSON Schema annotated with GKM metadata.

__hash__

__hash__() -> int

Hash the canonical JSON representation.

Returns:

Type Description
int

Hash of the serialized value.

ga4gh_serialize

ga4gh_serialize() -> dict

Serialize inherent fields for GA4GH digest computation.

Returns:

Type Description
dict

Mapping of inherent fields to serialized values.

is_ga4gh_identifiable staticmethod

is_ga4gh_identifiable() -> bool

Report whether this class supports GA4GH computed identifiers.

Returns:

Type Description
bool

Whether instances are identifiable.

RelativeSequenceLocation

Bases: Ga4ghIdentifiableObject, BaseModelForbidExtra

A location on a base sequence and its position relative to a boundary offset on a mapped sequence gap.

Typically used to describe intronic locations that exist with respect to a mapped RNA transcript sequence.

type class-attribute instance-attribute

type: Literal["RelativeSequenceLocation"] = Field(
    default=VrsType.RELATIVE_SEQ_LOC.value,
    description=f'MUST be "{VrsType.RELATIVE_SEQ_LOC.value}"',
)

baseSequenceLocation class-attribute instance-attribute

baseSequenceLocation: SequenceLocation | iriReference = (
    Field(
        ...,
        description="An absolute location on a sequence.",
    )
)

mappedSequenceLocation class-attribute instance-attribute

mappedSequenceLocation: (
    SequenceOffsetLocation | iriReference
) = Field(
    ...,
    description="A location relative to an offset on a mapped sequence.",
)

model_config class-attribute instance-attribute

model_config = ConfigDict(extra='forbid')

id class-attribute instance-attribute

id: str | None = Field(
    default=None,
    description="The 'logical' identifier of the Entity in the system of record, e.g. a UUID.  This 'id' is unique within a given system, but may or may not be globally unique outside the system. It is used within a system to reference an object from another.",
)

name class-attribute instance-attribute

name: str | None = Field(
    default=None,
    description="A primary name for the entity.",
)

description class-attribute instance-attribute

description: str | None = Field(
    default=None,
    description="A free-text description of the Entity.",
)

aliases class-attribute instance-attribute

aliases: list[str] | None = Field(
    default=None,
    description="Alternative name(s) for the Entity.",
)

extensions class-attribute instance-attribute

extensions: list[Extension] | None = Field(
    default=None,
    description="A list of extensions to the Entity, that allow for capture of information not directly supported by elements defined in the model.",
)

digest class-attribute instance-attribute

digest: (
    Annotated[
        str,
        StringConstraints(pattern="^[0-9A-Za-z_\\-]{32}$"),
    ]
    | None
) = Field(
    default=None,
    description="A sha512t24u digest created using the VRS Computed Identifier algorithm.",
)

ga4gh

Bases: ga4gh

Define GA4GH serialization metadata for this model.

prefix class-attribute instance-attribute

prefix = 'RSL'

inherent class-attribute instance-attribute

inherent = [
    "baseSequenceLocation",
    "mappedSequenceLocation",
    "type",
]

schema_id classmethod

schema_id() -> str

Return the canonical JSON Schema identifier for the model.

Returns:

Type Description
str

Canonical schema URI.

maturity classmethod

maturity() -> Maturity

Return the GKM maturity level for the model.

Returns:

Type Description
Maturity

Declared maturity level.

apply_schema_metadata classmethod

apply_schema_metadata(
    schema: dict[str, Any],
) -> dict[str, Any]

Add GKM metadata to a generated JSON Schema.

Parameters:

Name Type Description Default
schema dict[str, Any]

Generated JSON Schema to mutate in place.

required

Returns:

Type Description
dict[str, Any]

The annotated JSON Schema.

model_json_schema classmethod

model_json_schema(
    by_alias: bool = True,
    ref_template: str = "#/$defs/{model}",
    schema_generator: type[
        GenerateJsonSchema
    ] = GenerateJsonSchema,
    mode: JsonSchemaMode = "validation",
    *,
    union_format: Literal[
        "any_of", "primitive_type_array"
    ] = "any_of",
) -> dict[str, Any]

Generate JSON Schema with GKM metadata.

Default values follow Pydantic defaults.

Parameters:

Name Type Description Default
by_alias bool

Whether to use field aliases.

True
ref_template str

Template for schema references.

'#/$defs/{model}'
schema_generator type[GenerateJsonSchema]

Pydantic schema generator class.

GenerateJsonSchema
mode JsonSchemaMode

Pydantic schema generation mode.

'validation'
union_format Literal['any_of', 'primitive_type_array']

How to represent unions; ignored on Pydantic versions older than 2.12.

'any_of'

Returns:

Type Description
dict[str, Any]

JSON Schema annotated with GKM metadata.

__hash__

__hash__() -> int

Hash the canonical JSON representation.

Returns:

Type Description
int

Hash of the serialized value.

ga4gh_serialize

ga4gh_serialize() -> dict

Serialize inherent fields for GA4GH digest computation.

Returns:

Type Description
dict

Mapping of inherent fields to serialized values.

is_ga4gh_identifiable staticmethod

is_ga4gh_identifiable() -> bool

Report whether this class supports GA4GH computed identifiers.

Returns:

Type Description
bool

Whether instances are identifiable.

__lt__

__lt__(other: Ga4ghIdentifiableObject) -> bool

Compare objects by their computed digests.

Parameters:

Name Type Description Default
other Ga4ghIdentifiableObject

Object to compare.

required

Returns:

Type Description
bool

Whether this digest sorts before the other digest.

has_valid_ga4gh_id

has_valid_ga4gh_id() -> bool | str | None

Check the existing identifier against the GA4GH identifier pattern.

Returns:

Type Description
bool | str | None

Match status, or the unset or empty identifier.

compute_digest

compute_digest(
    store: bool = True,
    as_version: PrevVrsVersion | None = None,
) -> str

Compute a sha512t24u digest, created using the VRS Computed Identifier algorithm.

Stores the digest in the object if store is True.

If as_version is provided, other parameters are ignored and a digest is returned following the conventions of the VRS version indicated by as_version.

Parameters:

Name Type Description Default
store bool

Save the computed digest on the object.

True
as_version PrevVrsVersion | None

Optional prior VRS version for serialization.

None

Returns:

Type Description
str

Computed digest.

Raises:

Type Description
AttributeError

If prior-version serialization is unsupported.

get_or_create_ga4gh_identifier

get_or_create_ga4gh_identifier(
    in_place: str = "default",
    recompute: bool = False,
    as_version: PrevVrsVersion | None = None,
) -> str

Get a GA4GH computed identifier and optionally update the object ID.

This function has three options for in_place editing of vro.id:

  • 'default': the standard identifier update behavior for GA4GH identifiable objects, this mode will update the vro.id field only when it is None
  • 'always': this will update the vro.id field any time the identifier is computed
  • 'never': the vro.id field will not be edited in-place, even when empty

recompute applies when this call computes an identifier. A valid existing ID returned by the default policy bypasses digest computation. An invalid existing ID is replaced in the return value, but is only stored with the always policy.

If as_version is provided, other parameters are ignored and an identifier is returned following the conventions of the VRS version indicated by as_version.

Parameters:

Name Type Description Default
in_place str

ID update policy: default, always, or never.

'default'
recompute bool

Recompute an existing digest.

False
as_version PrevVrsVersion | None

Optional prior VRS version.

None

Returns:

Type Description
str

GA4GH computed identifier.

Raises:

Type Description
ValueError

If the update policy is invalid.

compute_ga4gh_identifier

compute_ga4gh_identifier(
    recompute: bool = False,
    as_version: PrevVrsVersion | None = None,
) -> str

Return a GA4GH Computed Identifier.

If as_version is provided, other parameters are ignored and a computed identifier is returned following the conventions of the VRS version indicated by as_version.

Parameters:

Name Type Description Default
recompute bool

Recompute an existing digest.

False
as_version PrevVrsVersion | None

Optional prior VRS version.

None

Returns:

Type Description
str

GA4GH computed identifier.

get_or_create_digest

get_or_create_digest(recompute: bool = False) -> str

Return the cached digest, computing and storing it when needed.

Parameters:

Name Type Description Default
recompute bool

Recompute an existing digest when true.

False

Returns:

Type Description
str

Existing or newly computed digest.

Allele

Bases: _VariationBase, BaseModelForbidExtra

The state of a molecule at a Location.

type class-attribute instance-attribute

type: Literal["Allele"] = Field(
    default=VrsType.ALLELE.value,
    description=f'MUST be "{VrsType.ALLELE.value}"',
)

location class-attribute instance-attribute

location: iriReference | SequenceLocation = Field(
    ..., description="The location of the Allele"
)

state class-attribute instance-attribute

state: (
    LiteralSequenceExpression
    | ReferenceLengthExpression
    | LengthExpression
) = Field(
    ..., description="An expression of the sequence state"
)

model_config class-attribute instance-attribute

model_config = ConfigDict(extra='forbid')

id class-attribute instance-attribute

id: str | None = Field(
    default=None,
    description="The 'logical' identifier of the Entity in the system of record, e.g. a UUID.  This 'id' is unique within a given system, but may or may not be globally unique outside the system. It is used within a system to reference an object from another.",
)

name class-attribute instance-attribute

name: str | None = Field(
    default=None,
    description="A primary name for the entity.",
)

description class-attribute instance-attribute

description: str | None = Field(
    default=None,
    description="A free-text description of the Entity.",
)

aliases class-attribute instance-attribute

aliases: list[str] | None = Field(
    default=None,
    description="Alternative name(s) for the Entity.",
)

extensions class-attribute instance-attribute

extensions: list[Extension] | None = Field(
    default=None,
    description="A list of extensions to the Entity, that allow for capture of information not directly supported by elements defined in the model.",
)

digest class-attribute instance-attribute

digest: (
    Annotated[
        str,
        StringConstraints(pattern="^[0-9A-Za-z_\\-]{32}$"),
    ]
    | None
) = Field(
    default=None,
    description="A sha512t24u digest created using the VRS Computed Identifier algorithm.",
)

expressions class-attribute instance-attribute

expressions: list[Expression] | None = None

ga4gh

Bases: ga4gh

Define GA4GH serialization metadata for this model.

prefix class-attribute instance-attribute

prefix = 'VA'

priorPrefix class-attribute instance-attribute

priorPrefix = {PrevVrsVersion.V1_3.value: 'VA'}

inherent class-attribute instance-attribute

inherent = ['location', 'state', 'type']

ga4gh_serialize_as_version

ga4gh_serialize_as_version(
    as_version: PrevVrsVersion,
) -> str

Return a serialized string following the conventions for Allele serialization as defined in the VRS version specified by as_version.

Parameters:

Name Type Description Default
as_version PrevVrsVersion

Prior VRS version to use.

required

Returns:

Type Description
str

Serialization for the requested prior version.

Raises:

Type Description
ValueError

If state is not a LiteralSequenceExpression or ReferenceLengthExpression; state.sequence is null.

TypeError

If the requested version is unsupported.

schema_id classmethod

schema_id() -> str

Return the canonical JSON Schema identifier for the model.

Returns:

Type Description
str

Canonical schema URI.

maturity classmethod

maturity() -> Maturity

Return the GKM maturity level for the model.

Returns:

Type Description
Maturity

Declared maturity level.

apply_schema_metadata classmethod

apply_schema_metadata(
    schema: dict[str, Any],
) -> dict[str, Any]

Add GKM metadata to a generated JSON Schema.

Parameters:

Name Type Description Default
schema dict[str, Any]

Generated JSON Schema to mutate in place.

required

Returns:

Type Description
dict[str, Any]

The annotated JSON Schema.

model_json_schema classmethod

model_json_schema(
    by_alias: bool = True,
    ref_template: str = "#/$defs/{model}",
    schema_generator: type[
        GenerateJsonSchema
    ] = GenerateJsonSchema,
    mode: JsonSchemaMode = "validation",
    *,
    union_format: Literal[
        "any_of", "primitive_type_array"
    ] = "any_of",
) -> dict[str, Any]

Generate JSON Schema with GKM metadata.

Default values follow Pydantic defaults.

Parameters:

Name Type Description Default
by_alias bool

Whether to use field aliases.

True
ref_template str

Template for schema references.

'#/$defs/{model}'
schema_generator type[GenerateJsonSchema]

Pydantic schema generator class.

GenerateJsonSchema
mode JsonSchemaMode

Pydantic schema generation mode.

'validation'
union_format Literal['any_of', 'primitive_type_array']

How to represent unions; ignored on Pydantic versions older than 2.12.

'any_of'

Returns:

Type Description
dict[str, Any]

JSON Schema annotated with GKM metadata.

__hash__

__hash__() -> int

Hash the canonical JSON representation.

Returns:

Type Description
int

Hash of the serialized value.

ga4gh_serialize

ga4gh_serialize() -> dict

Serialize inherent fields for GA4GH digest computation.

Returns:

Type Description
dict

Mapping of inherent fields to serialized values.

is_ga4gh_identifiable staticmethod

is_ga4gh_identifiable() -> bool

Report whether this class supports GA4GH computed identifiers.

Returns:

Type Description
bool

Whether instances are identifiable.

__lt__

__lt__(other: Ga4ghIdentifiableObject) -> bool

Compare objects by their computed digests.

Parameters:

Name Type Description Default
other Ga4ghIdentifiableObject

Object to compare.

required

Returns:

Type Description
bool

Whether this digest sorts before the other digest.

has_valid_ga4gh_id

has_valid_ga4gh_id() -> bool | str | None

Check the existing identifier against the GA4GH identifier pattern.

Returns:

Type Description
bool | str | None

Match status, or the unset or empty identifier.

compute_digest

compute_digest(
    store: bool = True,
    as_version: PrevVrsVersion | None = None,
) -> str

Compute a sha512t24u digest, created using the VRS Computed Identifier algorithm.

Stores the digest in the object if store is True.

If as_version is provided, other parameters are ignored and a digest is returned following the conventions of the VRS version indicated by as_version.

Parameters:

Name Type Description Default
store bool

Save the computed digest on the object.

True
as_version PrevVrsVersion | None

Optional prior VRS version for serialization.

None

Returns:

Type Description
str

Computed digest.

Raises:

Type Description
AttributeError

If prior-version serialization is unsupported.

get_or_create_ga4gh_identifier

get_or_create_ga4gh_identifier(
    in_place: str = "default",
    recompute: bool = False,
    as_version: PrevVrsVersion | None = None,
) -> str

Get a GA4GH computed identifier and optionally update the object ID.

This function has three options for in_place editing of vro.id:

  • 'default': the standard identifier update behavior for GA4GH identifiable objects, this mode will update the vro.id field only when it is None
  • 'always': this will update the vro.id field any time the identifier is computed
  • 'never': the vro.id field will not be edited in-place, even when empty

recompute applies when this call computes an identifier. A valid existing ID returned by the default policy bypasses digest computation. An invalid existing ID is replaced in the return value, but is only stored with the always policy.

If as_version is provided, other parameters are ignored and an identifier is returned following the conventions of the VRS version indicated by as_version.

Parameters:

Name Type Description Default
in_place str

ID update policy: default, always, or never.

'default'
recompute bool

Recompute an existing digest.

False
as_version PrevVrsVersion | None

Optional prior VRS version.

None

Returns:

Type Description
str

GA4GH computed identifier.

Raises:

Type Description
ValueError

If the update policy is invalid.

compute_ga4gh_identifier

compute_ga4gh_identifier(
    recompute: bool = False,
    as_version: PrevVrsVersion | None = None,
) -> str

Return a GA4GH Computed Identifier.

If as_version is provided, other parameters are ignored and a computed identifier is returned following the conventions of the VRS version indicated by as_version.

Parameters:

Name Type Description Default
recompute bool

Recompute an existing digest.

False
as_version PrevVrsVersion | None

Optional prior VRS version.

None

Returns:

Type Description
str

GA4GH computed identifier.

get_or_create_digest

get_or_create_digest(recompute: bool = False) -> str

Return the cached digest, computing and storing it when needed.

Parameters:

Name Type Description Default
recompute bool

Recompute an existing digest when true.

False

Returns:

Type Description
str

Existing or newly computed digest.

RelativeAllele

Bases: _VariationBase, BaseModelForbidExtra

An Allele defined on a mapped location relative to a base location. Often used to describe intronic variants.

type class-attribute instance-attribute

type: Literal["RelativeAllele"] = Field(
    default=VrsType.RELATIVE_ALLELE.value,
    description=f'MUST be "{VrsType.RELATIVE_ALLELE.value}"',
)

mappedState class-attribute instance-attribute

mappedState: (
    LiteralSequenceExpression
    | ReferenceLengthExpression
    | LengthExpression
) = Field(
    ...,
    description='The state of the RelativeAllele as expressed on the mapped sequence. This will differ from the base state when mapping to a reverse complement sequence, commonly observed when representing the state on transcripts mapped to the "negative strand" of a chromosome.',
)

baseState class-attribute instance-attribute

baseState: (
    LiteralSequenceExpression
    | ReferenceLengthExpression
    | LengthExpression
) = Field(
    ...,
    description="The state of the RelativeAllele as expressed on the base sequence.",
)

relativeLocation class-attribute instance-attribute

relativeLocation: (
    RelativeSequenceLocation | iriReference
) = Field(
    ...,
    description="The relative location at which the baseState and mappedState are expressed.",
)

model_config class-attribute instance-attribute

model_config = ConfigDict(extra='forbid')

id class-attribute instance-attribute

id: str | None = Field(
    default=None,
    description="The 'logical' identifier of the Entity in the system of record, e.g. a UUID.  This 'id' is unique within a given system, but may or may not be globally unique outside the system. It is used within a system to reference an object from another.",
)

name class-attribute instance-attribute

name: str | None = Field(
    default=None,
    description="A primary name for the entity.",
)

description class-attribute instance-attribute

description: str | None = Field(
    default=None,
    description="A free-text description of the Entity.",
)

aliases class-attribute instance-attribute

aliases: list[str] | None = Field(
    default=None,
    description="Alternative name(s) for the Entity.",
)

extensions class-attribute instance-attribute

extensions: list[Extension] | None = Field(
    default=None,
    description="A list of extensions to the Entity, that allow for capture of information not directly supported by elements defined in the model.",
)

digest class-attribute instance-attribute

digest: (
    Annotated[
        str,
        StringConstraints(pattern="^[0-9A-Za-z_\\-]{32}$"),
    ]
    | None
) = Field(
    default=None,
    description="A sha512t24u digest created using the VRS Computed Identifier algorithm.",
)

expressions class-attribute instance-attribute

expressions: list[Expression] | None = None

ga4gh

Bases: ga4gh

Define GA4GH serialization metadata for this model.

prefix class-attribute instance-attribute

prefix = 'RA'

inherent class-attribute instance-attribute

inherent = [
    "mappedState",
    "baseState",
    "relativeLocation",
    "type",
]

schema_id classmethod

schema_id() -> str

Return the canonical JSON Schema identifier for the model.

Returns:

Type Description
str

Canonical schema URI.

maturity classmethod

maturity() -> Maturity

Return the GKM maturity level for the model.

Returns:

Type Description
Maturity

Declared maturity level.

apply_schema_metadata classmethod

apply_schema_metadata(
    schema: dict[str, Any],
) -> dict[str, Any]

Add GKM metadata to a generated JSON Schema.

Parameters:

Name Type Description Default
schema dict[str, Any]

Generated JSON Schema to mutate in place.

required

Returns:

Type Description
dict[str, Any]

The annotated JSON Schema.

model_json_schema classmethod

model_json_schema(
    by_alias: bool = True,
    ref_template: str = "#/$defs/{model}",
    schema_generator: type[
        GenerateJsonSchema
    ] = GenerateJsonSchema,
    mode: JsonSchemaMode = "validation",
    *,
    union_format: Literal[
        "any_of", "primitive_type_array"
    ] = "any_of",
) -> dict[str, Any]

Generate JSON Schema with GKM metadata.

Default values follow Pydantic defaults.

Parameters:

Name Type Description Default
by_alias bool

Whether to use field aliases.

True
ref_template str

Template for schema references.

'#/$defs/{model}'
schema_generator type[GenerateJsonSchema]

Pydantic schema generator class.

GenerateJsonSchema
mode JsonSchemaMode

Pydantic schema generation mode.

'validation'
union_format Literal['any_of', 'primitive_type_array']

How to represent unions; ignored on Pydantic versions older than 2.12.

'any_of'

Returns:

Type Description
dict[str, Any]

JSON Schema annotated with GKM metadata.

__hash__

__hash__() -> int

Hash the canonical JSON representation.

Returns:

Type Description
int

Hash of the serialized value.

ga4gh_serialize

ga4gh_serialize() -> dict

Serialize inherent fields for GA4GH digest computation.

Returns:

Type Description
dict

Mapping of inherent fields to serialized values.

is_ga4gh_identifiable staticmethod

is_ga4gh_identifiable() -> bool

Report whether this class supports GA4GH computed identifiers.

Returns:

Type Description
bool

Whether instances are identifiable.

__lt__

__lt__(other: Ga4ghIdentifiableObject) -> bool

Compare objects by their computed digests.

Parameters:

Name Type Description Default
other Ga4ghIdentifiableObject

Object to compare.

required

Returns:

Type Description
bool

Whether this digest sorts before the other digest.

has_valid_ga4gh_id

has_valid_ga4gh_id() -> bool | str | None

Check the existing identifier against the GA4GH identifier pattern.

Returns:

Type Description
bool | str | None

Match status, or the unset or empty identifier.

compute_digest

compute_digest(
    store: bool = True,
    as_version: PrevVrsVersion | None = None,
) -> str

Compute a sha512t24u digest, created using the VRS Computed Identifier algorithm.

Stores the digest in the object if store is True.

If as_version is provided, other parameters are ignored and a digest is returned following the conventions of the VRS version indicated by as_version.

Parameters:

Name Type Description Default
store bool

Save the computed digest on the object.

True
as_version PrevVrsVersion | None

Optional prior VRS version for serialization.

None

Returns:

Type Description
str

Computed digest.

Raises:

Type Description
AttributeError

If prior-version serialization is unsupported.

get_or_create_ga4gh_identifier

get_or_create_ga4gh_identifier(
    in_place: str = "default",
    recompute: bool = False,
    as_version: PrevVrsVersion | None = None,
) -> str

Get a GA4GH computed identifier and optionally update the object ID.

This function has three options for in_place editing of vro.id:

  • 'default': the standard identifier update behavior for GA4GH identifiable objects, this mode will update the vro.id field only when it is None
  • 'always': this will update the vro.id field any time the identifier is computed
  • 'never': the vro.id field will not be edited in-place, even when empty

recompute applies when this call computes an identifier. A valid existing ID returned by the default policy bypasses digest computation. An invalid existing ID is replaced in the return value, but is only stored with the always policy.

If as_version is provided, other parameters are ignored and an identifier is returned following the conventions of the VRS version indicated by as_version.

Parameters:

Name Type Description Default
in_place str

ID update policy: default, always, or never.

'default'
recompute bool

Recompute an existing digest.

False
as_version PrevVrsVersion | None

Optional prior VRS version.

None

Returns:

Type Description
str

GA4GH computed identifier.

Raises:

Type Description
ValueError

If the update policy is invalid.

compute_ga4gh_identifier

compute_ga4gh_identifier(
    recompute: bool = False,
    as_version: PrevVrsVersion | None = None,
) -> str

Return a GA4GH Computed Identifier.

If as_version is provided, other parameters are ignored and a computed identifier is returned following the conventions of the VRS version indicated by as_version.

Parameters:

Name Type Description Default
recompute bool

Recompute an existing digest.

False
as_version PrevVrsVersion | None

Optional prior VRS version.

None

Returns:

Type Description
str

GA4GH computed identifier.

get_or_create_digest

get_or_create_digest(recompute: bool = False) -> str

Return the cached digest, computing and storing it when needed.

Parameters:

Name Type Description Default
recompute bool

Recompute an existing digest when true.

False

Returns:

Type Description
str

Existing or newly computed digest.

CisPhasedBlock

Bases: _VariationBase, BaseModelForbidExtra

An ordered set of co-occurring Variation on the same molecule.

type class-attribute instance-attribute

type: Literal["CisPhasedBlock"] = Field(
    default=VrsType.CIS_PHASED_BLOCK.value,
    description=f'MUST be "{VrsType.CIS_PHASED_BLOCK.value}"',
)

members class-attribute instance-attribute

members: list[Allele | iriReference] = Field(
    ...,
    description="A list of Alleles that are found in-cis on a shared molecule.",
    min_length=2,
)

sequenceReference class-attribute instance-attribute

sequenceReference: SequenceReference | None = Field(
    default=None,
    description="An optional Sequence Reference on which all of the in-cis Alleles are found. When defined, this may be used to implicitly define the `sequenceReference` attribute for each of the CisPhasedBlock member Alleles.",
)

model_config class-attribute instance-attribute

model_config = ConfigDict(extra='forbid')

id class-attribute instance-attribute

id: str | None = Field(
    default=None,
    description="The 'logical' identifier of the Entity in the system of record, e.g. a UUID.  This 'id' is unique within a given system, but may or may not be globally unique outside the system. It is used within a system to reference an object from another.",
)

name class-attribute instance-attribute

name: str | None = Field(
    default=None,
    description="A primary name for the entity.",
)

description class-attribute instance-attribute

description: str | None = Field(
    default=None,
    description="A free-text description of the Entity.",
)

aliases class-attribute instance-attribute

aliases: list[str] | None = Field(
    default=None,
    description="Alternative name(s) for the Entity.",
)

extensions class-attribute instance-attribute

extensions: list[Extension] | None = Field(
    default=None,
    description="A list of extensions to the Entity, that allow for capture of information not directly supported by elements defined in the model.",
)

digest class-attribute instance-attribute

digest: (
    Annotated[
        str,
        StringConstraints(pattern="^[0-9A-Za-z_\\-]{32}$"),
    ]
    | None
) = Field(
    default=None,
    description="A sha512t24u digest created using the VRS Computed Identifier algorithm.",
)

expressions class-attribute instance-attribute

expressions: list[Expression] | None = None

ga4gh

Bases: ga4gh

Define GA4GH serialization metadata for this model.

prefix class-attribute instance-attribute

prefix = 'CPB'

inherent class-attribute instance-attribute

inherent = ['members', 'type']

ga4gh_serialize

ga4gh_serialize() -> dict

Serialize inherent fields for GA4GH digest computation.

Returns:

Type Description
dict

Mapping of inherent fields to serialized values.

schema_id classmethod

schema_id() -> str

Return the canonical JSON Schema identifier for the model.

Returns:

Type Description
str

Canonical schema URI.

maturity classmethod

maturity() -> Maturity

Return the GKM maturity level for the model.

Returns:

Type Description
Maturity

Declared maturity level.

apply_schema_metadata classmethod

apply_schema_metadata(
    schema: dict[str, Any],
) -> dict[str, Any]

Add GKM metadata to a generated JSON Schema.

Parameters:

Name Type Description Default
schema dict[str, Any]

Generated JSON Schema to mutate in place.

required

Returns:

Type Description
dict[str, Any]

The annotated JSON Schema.

model_json_schema classmethod

model_json_schema(
    by_alias: bool = True,
    ref_template: str = "#/$defs/{model}",
    schema_generator: type[
        GenerateJsonSchema
    ] = GenerateJsonSchema,
    mode: JsonSchemaMode = "validation",
    *,
    union_format: Literal[
        "any_of", "primitive_type_array"
    ] = "any_of",
) -> dict[str, Any]

Generate JSON Schema with GKM metadata.

Default values follow Pydantic defaults.

Parameters:

Name Type Description Default
by_alias bool

Whether to use field aliases.

True
ref_template str

Template for schema references.

'#/$defs/{model}'
schema_generator type[GenerateJsonSchema]

Pydantic schema generator class.

GenerateJsonSchema
mode JsonSchemaMode

Pydantic schema generation mode.

'validation'
union_format Literal['any_of', 'primitive_type_array']

How to represent unions; ignored on Pydantic versions older than 2.12.

'any_of'

Returns:

Type Description
dict[str, Any]

JSON Schema annotated with GKM metadata.

__hash__

__hash__() -> int

Hash the canonical JSON representation.

Returns:

Type Description
int

Hash of the serialized value.

is_ga4gh_identifiable staticmethod

is_ga4gh_identifiable() -> bool

Report whether this class supports GA4GH computed identifiers.

Returns:

Type Description
bool

Whether instances are identifiable.

__lt__

__lt__(other: Ga4ghIdentifiableObject) -> bool

Compare objects by their computed digests.

Parameters:

Name Type Description Default
other Ga4ghIdentifiableObject

Object to compare.

required

Returns:

Type Description
bool

Whether this digest sorts before the other digest.

has_valid_ga4gh_id

has_valid_ga4gh_id() -> bool | str | None

Check the existing identifier against the GA4GH identifier pattern.

Returns:

Type Description
bool | str | None

Match status, or the unset or empty identifier.

compute_digest

compute_digest(
    store: bool = True,
    as_version: PrevVrsVersion | None = None,
) -> str

Compute a sha512t24u digest, created using the VRS Computed Identifier algorithm.

Stores the digest in the object if store is True.

If as_version is provided, other parameters are ignored and a digest is returned following the conventions of the VRS version indicated by as_version.

Parameters:

Name Type Description Default
store bool

Save the computed digest on the object.

True
as_version PrevVrsVersion | None

Optional prior VRS version for serialization.

None

Returns:

Type Description
str

Computed digest.

Raises:

Type Description
AttributeError

If prior-version serialization is unsupported.

get_or_create_ga4gh_identifier

get_or_create_ga4gh_identifier(
    in_place: str = "default",
    recompute: bool = False,
    as_version: PrevVrsVersion | None = None,
) -> str

Get a GA4GH computed identifier and optionally update the object ID.

This function has three options for in_place editing of vro.id:

  • 'default': the standard identifier update behavior for GA4GH identifiable objects, this mode will update the vro.id field only when it is None
  • 'always': this will update the vro.id field any time the identifier is computed
  • 'never': the vro.id field will not be edited in-place, even when empty

recompute applies when this call computes an identifier. A valid existing ID returned by the default policy bypasses digest computation. An invalid existing ID is replaced in the return value, but is only stored with the always policy.

If as_version is provided, other parameters are ignored and an identifier is returned following the conventions of the VRS version indicated by as_version.

Parameters:

Name Type Description Default
in_place str

ID update policy: default, always, or never.

'default'
recompute bool

Recompute an existing digest.

False
as_version PrevVrsVersion | None

Optional prior VRS version.

None

Returns:

Type Description
str

GA4GH computed identifier.

Raises:

Type Description
ValueError

If the update policy is invalid.

compute_ga4gh_identifier

compute_ga4gh_identifier(
    recompute: bool = False,
    as_version: PrevVrsVersion | None = None,
) -> str

Return a GA4GH Computed Identifier.

If as_version is provided, other parameters are ignored and a computed identifier is returned following the conventions of the VRS version indicated by as_version.

Parameters:

Name Type Description Default
recompute bool

Recompute an existing digest.

False
as_version PrevVrsVersion | None

Optional prior VRS version.

None

Returns:

Type Description
str

GA4GH computed identifier.

get_or_create_digest

get_or_create_digest(recompute: bool = False) -> str

Return the cached digest, computing and storing it when needed.

Parameters:

Name Type Description Default
recompute bool

Recompute an existing digest when true.

False

Returns:

Type Description
str

Existing or newly computed digest.

Adjacency

Bases: _VariationBase, BaseModelForbidExtra

The Adjacency class represents the adjoining of the end of a sequence with the beginning of an adjacent sequence, potentially with an intervening linker sequence.

type class-attribute instance-attribute

type: Literal["Adjacency"] = Field(
    default=VrsType.ADJACENCY.value,
    description=f'MUST be "{VrsType.ADJACENCY.value}".',
)

adjoinedSequences class-attribute instance-attribute

adjoinedSequences: list[iriReference | SequenceLocation] = (
    Field(
        ...,
        description="The terminal sequence or pair of adjoined sequences that defines in the adjacency.",
        min_length=2,
        max_length=2,
    )
)

linker class-attribute instance-attribute

linker: (
    LiteralSequenceExpression
    | ReferenceLengthExpression
    | LengthExpression
    | None
) = Field(
    default=None,
    description="The sequence found between adjoined sequences.",
)

homology class-attribute instance-attribute

homology: bool | None = Field(
    default=None,
    description="A flag indicating if coordinate ambiguity in the adjoined sequences is from sequence homology (true) or other uncertainty, such as instrument ambiguity (false).",
)

model_config class-attribute instance-attribute

model_config = ConfigDict(extra='forbid')

id class-attribute instance-attribute

id: str | None = Field(
    default=None,
    description="The 'logical' identifier of the Entity in the system of record, e.g. a UUID.  This 'id' is unique within a given system, but may or may not be globally unique outside the system. It is used within a system to reference an object from another.",
)

name class-attribute instance-attribute

name: str | None = Field(
    default=None,
    description="A primary name for the entity.",
)

description class-attribute instance-attribute

description: str | None = Field(
    default=None,
    description="A free-text description of the Entity.",
)

aliases class-attribute instance-attribute

aliases: list[str] | None = Field(
    default=None,
    description="Alternative name(s) for the Entity.",
)

extensions class-attribute instance-attribute

extensions: list[Extension] | None = Field(
    default=None,
    description="A list of extensions to the Entity, that allow for capture of information not directly supported by elements defined in the model.",
)

digest class-attribute instance-attribute

digest: (
    Annotated[
        str,
        StringConstraints(pattern="^[0-9A-Za-z_\\-]{32}$"),
    ]
    | None
) = Field(
    default=None,
    description="A sha512t24u digest created using the VRS Computed Identifier algorithm.",
)

expressions class-attribute instance-attribute

expressions: list[Expression] | None = None

ga4gh

Bases: ga4gh

Define GA4GH serialization metadata for this model.

prefix class-attribute instance-attribute

prefix = 'AJ'

inherent class-attribute instance-attribute

inherent = ['adjoinedSequences', 'linker', 'type']

validate_adjoined_sequences

validate_adjoined_sequences(
    v: list[iriReference | SequenceLocation],
) -> list[iriReference | SequenceLocation]

Reject adjoined sequence locations with two truthy endpoints.

Parameters:

Name Type Description Default
v list[iriReference | SequenceLocation]

Adjoined sequence references or locations to validate.

required

Returns:

Type Description
list[iriReference | SequenceLocation]

Adjoined sequences represented as iri reference or sequence location

Raises:

Type Description
ValueError

If both endpoints are truthy. Zero and None do not trigger this check.

schema_id classmethod

schema_id() -> str

Return the canonical JSON Schema identifier for the model.

Returns:

Type Description
str

Canonical schema URI.

maturity classmethod

maturity() -> Maturity

Return the GKM maturity level for the model.

Returns:

Type Description
Maturity

Declared maturity level.

apply_schema_metadata classmethod

apply_schema_metadata(
    schema: dict[str, Any],
) -> dict[str, Any]

Add GKM metadata to a generated JSON Schema.

Parameters:

Name Type Description Default
schema dict[str, Any]

Generated JSON Schema to mutate in place.

required

Returns:

Type Description
dict[str, Any]

The annotated JSON Schema.

model_json_schema classmethod

model_json_schema(
    by_alias: bool = True,
    ref_template: str = "#/$defs/{model}",
    schema_generator: type[
        GenerateJsonSchema
    ] = GenerateJsonSchema,
    mode: JsonSchemaMode = "validation",
    *,
    union_format: Literal[
        "any_of", "primitive_type_array"
    ] = "any_of",
) -> dict[str, Any]

Generate JSON Schema with GKM metadata.

Default values follow Pydantic defaults.

Parameters:

Name Type Description Default
by_alias bool

Whether to use field aliases.

True
ref_template str

Template for schema references.

'#/$defs/{model}'
schema_generator type[GenerateJsonSchema]

Pydantic schema generator class.

GenerateJsonSchema
mode JsonSchemaMode

Pydantic schema generation mode.

'validation'
union_format Literal['any_of', 'primitive_type_array']

How to represent unions; ignored on Pydantic versions older than 2.12.

'any_of'

Returns:

Type Description
dict[str, Any]

JSON Schema annotated with GKM metadata.

__hash__

__hash__() -> int

Hash the canonical JSON representation.

Returns:

Type Description
int

Hash of the serialized value.

ga4gh_serialize

ga4gh_serialize() -> dict

Serialize inherent fields for GA4GH digest computation.

Returns:

Type Description
dict

Mapping of inherent fields to serialized values.

is_ga4gh_identifiable staticmethod

is_ga4gh_identifiable() -> bool

Report whether this class supports GA4GH computed identifiers.

Returns:

Type Description
bool

Whether instances are identifiable.

__lt__

__lt__(other: Ga4ghIdentifiableObject) -> bool

Compare objects by their computed digests.

Parameters:

Name Type Description Default
other Ga4ghIdentifiableObject

Object to compare.

required

Returns:

Type Description
bool

Whether this digest sorts before the other digest.

has_valid_ga4gh_id

has_valid_ga4gh_id() -> bool | str | None

Check the existing identifier against the GA4GH identifier pattern.

Returns:

Type Description
bool | str | None

Match status, or the unset or empty identifier.

compute_digest

compute_digest(
    store: bool = True,
    as_version: PrevVrsVersion | None = None,
) -> str

Compute a sha512t24u digest, created using the VRS Computed Identifier algorithm.

Stores the digest in the object if store is True.

If as_version is provided, other parameters are ignored and a digest is returned following the conventions of the VRS version indicated by as_version.

Parameters:

Name Type Description Default
store bool

Save the computed digest on the object.

True
as_version PrevVrsVersion | None

Optional prior VRS version for serialization.

None

Returns:

Type Description
str

Computed digest.

Raises:

Type Description
AttributeError

If prior-version serialization is unsupported.

get_or_create_ga4gh_identifier

get_or_create_ga4gh_identifier(
    in_place: str = "default",
    recompute: bool = False,
    as_version: PrevVrsVersion | None = None,
) -> str

Get a GA4GH computed identifier and optionally update the object ID.

This function has three options for in_place editing of vro.id:

  • 'default': the standard identifier update behavior for GA4GH identifiable objects, this mode will update the vro.id field only when it is None
  • 'always': this will update the vro.id field any time the identifier is computed
  • 'never': the vro.id field will not be edited in-place, even when empty

recompute applies when this call computes an identifier. A valid existing ID returned by the default policy bypasses digest computation. An invalid existing ID is replaced in the return value, but is only stored with the always policy.

If as_version is provided, other parameters are ignored and an identifier is returned following the conventions of the VRS version indicated by as_version.

Parameters:

Name Type Description Default
in_place str

ID update policy: default, always, or never.

'default'
recompute bool

Recompute an existing digest.

False
as_version PrevVrsVersion | None

Optional prior VRS version.

None

Returns:

Type Description
str

GA4GH computed identifier.

Raises:

Type Description
ValueError

If the update policy is invalid.

compute_ga4gh_identifier

compute_ga4gh_identifier(
    recompute: bool = False,
    as_version: PrevVrsVersion | None = None,
) -> str

Return a GA4GH Computed Identifier.

If as_version is provided, other parameters are ignored and a computed identifier is returned following the conventions of the VRS version indicated by as_version.

Parameters:

Name Type Description Default
recompute bool

Recompute an existing digest.

False
as_version PrevVrsVersion | None

Optional prior VRS version.

None

Returns:

Type Description
str

GA4GH computed identifier.

get_or_create_digest

get_or_create_digest(recompute: bool = False) -> str

Return the cached digest, computing and storing it when needed.

Parameters:

Name Type Description Default
recompute bool

Recompute an existing digest when true.

False

Returns:

Type Description
str

Existing or newly computed digest.

Terminus

Bases: _VariationBase, BaseModelForbidExtra

The Terminus data class provides a structure for describing the end (terminus) of a sequence.

Structurally similar to Adjacency but the linker sequence is not allowed and it removes the unnecessary array structure.

type class-attribute instance-attribute

type: Literal["Terminus"] = Field(
    default=VrsType.TERMINUS.value,
    description=f'MUST be "{VrsType.TERMINUS.value}".',
)

location class-attribute instance-attribute

location: iriReference | SequenceLocation = Field(
    ..., description="The location of the terminus."
)

model_config class-attribute instance-attribute

model_config = ConfigDict(extra='forbid')

id class-attribute instance-attribute

id: str | None = Field(
    default=None,
    description="The 'logical' identifier of the Entity in the system of record, e.g. a UUID.  This 'id' is unique within a given system, but may or may not be globally unique outside the system. It is used within a system to reference an object from another.",
)

name class-attribute instance-attribute

name: str | None = Field(
    default=None,
    description="A primary name for the entity.",
)

description class-attribute instance-attribute

description: str | None = Field(
    default=None,
    description="A free-text description of the Entity.",
)

aliases class-attribute instance-attribute

aliases: list[str] | None = Field(
    default=None,
    description="Alternative name(s) for the Entity.",
)

extensions class-attribute instance-attribute

extensions: list[Extension] | None = Field(
    default=None,
    description="A list of extensions to the Entity, that allow for capture of information not directly supported by elements defined in the model.",
)

digest class-attribute instance-attribute

digest: (
    Annotated[
        str,
        StringConstraints(pattern="^[0-9A-Za-z_\\-]{32}$"),
    ]
    | None
) = Field(
    default=None,
    description="A sha512t24u digest created using the VRS Computed Identifier algorithm.",
)

expressions class-attribute instance-attribute

expressions: list[Expression] | None = None

ga4gh

Bases: ga4gh

Define GA4GH serialization metadata for this model.

prefix class-attribute instance-attribute

prefix = 'TM'

inherent class-attribute instance-attribute

inherent = ['location', 'type']

schema_id classmethod

schema_id() -> str

Return the canonical JSON Schema identifier for the model.

Returns:

Type Description
str

Canonical schema URI.

maturity classmethod

maturity() -> Maturity

Return the GKM maturity level for the model.

Returns:

Type Description
Maturity

Declared maturity level.

apply_schema_metadata classmethod

apply_schema_metadata(
    schema: dict[str, Any],
) -> dict[str, Any]

Add GKM metadata to a generated JSON Schema.

Parameters:

Name Type Description Default
schema dict[str, Any]

Generated JSON Schema to mutate in place.

required

Returns:

Type Description
dict[str, Any]

The annotated JSON Schema.

model_json_schema classmethod

model_json_schema(
    by_alias: bool = True,
    ref_template: str = "#/$defs/{model}",
    schema_generator: type[
        GenerateJsonSchema
    ] = GenerateJsonSchema,
    mode: JsonSchemaMode = "validation",
    *,
    union_format: Literal[
        "any_of", "primitive_type_array"
    ] = "any_of",
) -> dict[str, Any]

Generate JSON Schema with GKM metadata.

Default values follow Pydantic defaults.

Parameters:

Name Type Description Default
by_alias bool

Whether to use field aliases.

True
ref_template str

Template for schema references.

'#/$defs/{model}'
schema_generator type[GenerateJsonSchema]

Pydantic schema generator class.

GenerateJsonSchema
mode JsonSchemaMode

Pydantic schema generation mode.

'validation'
union_format Literal['any_of', 'primitive_type_array']

How to represent unions; ignored on Pydantic versions older than 2.12.

'any_of'

Returns:

Type Description
dict[str, Any]

JSON Schema annotated with GKM metadata.

__hash__

__hash__() -> int

Hash the canonical JSON representation.

Returns:

Type Description
int

Hash of the serialized value.

ga4gh_serialize

ga4gh_serialize() -> dict

Serialize inherent fields for GA4GH digest computation.

Returns:

Type Description
dict

Mapping of inherent fields to serialized values.

is_ga4gh_identifiable staticmethod

is_ga4gh_identifiable() -> bool

Report whether this class supports GA4GH computed identifiers.

Returns:

Type Description
bool

Whether instances are identifiable.

__lt__

__lt__(other: Ga4ghIdentifiableObject) -> bool

Compare objects by their computed digests.

Parameters:

Name Type Description Default
other Ga4ghIdentifiableObject

Object to compare.

required

Returns:

Type Description
bool

Whether this digest sorts before the other digest.

has_valid_ga4gh_id

has_valid_ga4gh_id() -> bool | str | None

Check the existing identifier against the GA4GH identifier pattern.

Returns:

Type Description
bool | str | None

Match status, or the unset or empty identifier.

compute_digest

compute_digest(
    store: bool = True,
    as_version: PrevVrsVersion | None = None,
) -> str

Compute a sha512t24u digest, created using the VRS Computed Identifier algorithm.

Stores the digest in the object if store is True.

If as_version is provided, other parameters are ignored and a digest is returned following the conventions of the VRS version indicated by as_version.

Parameters:

Name Type Description Default
store bool

Save the computed digest on the object.

True
as_version PrevVrsVersion | None

Optional prior VRS version for serialization.

None

Returns:

Type Description
str

Computed digest.

Raises:

Type Description
AttributeError

If prior-version serialization is unsupported.

get_or_create_ga4gh_identifier

get_or_create_ga4gh_identifier(
    in_place: str = "default",
    recompute: bool = False,
    as_version: PrevVrsVersion | None = None,
) -> str

Get a GA4GH computed identifier and optionally update the object ID.

This function has three options for in_place editing of vro.id:

  • 'default': the standard identifier update behavior for GA4GH identifiable objects, this mode will update the vro.id field only when it is None
  • 'always': this will update the vro.id field any time the identifier is computed
  • 'never': the vro.id field will not be edited in-place, even when empty

recompute applies when this call computes an identifier. A valid existing ID returned by the default policy bypasses digest computation. An invalid existing ID is replaced in the return value, but is only stored with the always policy.

If as_version is provided, other parameters are ignored and an identifier is returned following the conventions of the VRS version indicated by as_version.

Parameters:

Name Type Description Default
in_place str

ID update policy: default, always, or never.

'default'
recompute bool

Recompute an existing digest.

False
as_version PrevVrsVersion | None

Optional prior VRS version.

None

Returns:

Type Description
str

GA4GH computed identifier.

Raises:

Type Description
ValueError

If the update policy is invalid.

compute_ga4gh_identifier

compute_ga4gh_identifier(
    recompute: bool = False,
    as_version: PrevVrsVersion | None = None,
) -> str

Return a GA4GH Computed Identifier.

If as_version is provided, other parameters are ignored and a computed identifier is returned following the conventions of the VRS version indicated by as_version.

Parameters:

Name Type Description Default
recompute bool

Recompute an existing digest.

False
as_version PrevVrsVersion | None

Optional prior VRS version.

None

Returns:

Type Description
str

GA4GH computed identifier.

get_or_create_digest

get_or_create_digest(recompute: bool = False) -> str

Return the cached digest, computing and storing it when needed.

Parameters:

Name Type Description Default
recompute bool

Recompute an existing digest when true.

False

Returns:

Type Description
str

Existing or newly computed digest.

TraversalBlock

Bases: VRSMetadataMixin, _ValueObject, BaseModelForbidExtra

A component used to describe the orientation of applicable molecular variation within a DerivativeMolecule.

model_config class-attribute instance-attribute

model_config = ConfigDict(use_enum_values=True)

type class-attribute instance-attribute

type: Literal["TraversalBlock"] = Field(
    default=VrsType.TRAVERSAL_BLOCK.value,
    description=f'MUST be "{VrsType.TRAVERSAL_BLOCK.value}".',
)

orientation class-attribute instance-attribute

orientation: Orientation | None = Field(
    default=None,
    description="The orientation of the molecular variation component.",
)

component class-attribute instance-attribute

component: Adjacency | None = Field(
    default=None,
    description="The unoriented molecular variation component.",
)

id class-attribute instance-attribute

id: str | None = Field(
    default=None,
    description="The 'logical' identifier of the Entity in the system of record, e.g. a UUID.  This 'id' is unique within a given system, but may or may not be globally unique outside the system. It is used within a system to reference an object from another.",
)

name class-attribute instance-attribute

name: str | None = Field(
    default=None,
    description="A primary name for the entity.",
)

description class-attribute instance-attribute

description: str | None = Field(
    default=None,
    description="A free-text description of the Entity.",
)

aliases class-attribute instance-attribute

aliases: list[str] | None = Field(
    default=None,
    description="Alternative name(s) for the Entity.",
)

extensions class-attribute instance-attribute

extensions: list[Extension] | None = Field(
    default=None,
    description="A list of extensions to the Entity, that allow for capture of information not directly supported by elements defined in the model.",
)

ga4gh

Bases: ga4gh

Define GA4GH serialization metadata for this model.

inherent class-attribute instance-attribute

inherent = ['component', 'orientation', 'type']

schema_id classmethod

schema_id() -> str

Return the canonical JSON Schema identifier for the model.

Returns:

Type Description
str

Canonical schema URI.

maturity classmethod

maturity() -> Maturity

Return the GKM maturity level for the model.

Returns:

Type Description
Maturity

Declared maturity level.

apply_schema_metadata classmethod

apply_schema_metadata(
    schema: dict[str, Any],
) -> dict[str, Any]

Add GKM metadata to a generated JSON Schema.

Parameters:

Name Type Description Default
schema dict[str, Any]

Generated JSON Schema to mutate in place.

required

Returns:

Type Description
dict[str, Any]

The annotated JSON Schema.

model_json_schema classmethod

model_json_schema(
    by_alias: bool = True,
    ref_template: str = "#/$defs/{model}",
    schema_generator: type[
        GenerateJsonSchema
    ] = GenerateJsonSchema,
    mode: JsonSchemaMode = "validation",
    *,
    union_format: Literal[
        "any_of", "primitive_type_array"
    ] = "any_of",
) -> dict[str, Any]

Generate JSON Schema with GKM metadata.

Default values follow Pydantic defaults.

Parameters:

Name Type Description Default
by_alias bool

Whether to use field aliases.

True
ref_template str

Template for schema references.

'#/$defs/{model}'
schema_generator type[GenerateJsonSchema]

Pydantic schema generator class.

GenerateJsonSchema
mode JsonSchemaMode

Pydantic schema generation mode.

'validation'
union_format Literal['any_of', 'primitive_type_array']

How to represent unions; ignored on Pydantic versions older than 2.12.

'any_of'

Returns:

Type Description
dict[str, Any]

JSON Schema annotated with GKM metadata.

__hash__

__hash__() -> int

Hash the canonical JSON representation.

Returns:

Type Description
int

Hash of the serialized value.

ga4gh_serialize

ga4gh_serialize() -> dict

Serialize inherent fields for GA4GH digest computation.

Returns:

Type Description
dict

Mapping of inherent fields to serialized values.

is_ga4gh_identifiable staticmethod

is_ga4gh_identifiable() -> bool

Report whether this class supports GA4GH computed identifiers.

Returns:

Type Description
bool

Whether instances are identifiable.

DerivativeMolecule

Bases: _VariationBase, BaseModelForbidExtra

The "Derivative Molecule" data class is a structure for describing a derivate molecule composed from multiple sequence components.

type class-attribute instance-attribute

type: Literal["DerivativeMolecule"] = Field(
    default=VrsType.DERIVATIVE_MOL.value,
    description=f'MUST be "{VrsType.DERIVATIVE_MOL.value}".',
)

components class-attribute instance-attribute

components: list[
    iriReference
    | Allele
    | CisPhasedBlock
    | Terminus
    | TraversalBlock
] = Field(
    ...,
    description="The molecular components that constitute the derivative molecule.",
    min_length=2,
)

circular class-attribute instance-attribute

circular: bool | None = Field(
    default=None,
    description="A boolean indicating whether the molecule represented by the sequence is circular (true) or linear (false).",
)

model_config class-attribute instance-attribute

model_config = ConfigDict(extra='forbid')

id class-attribute instance-attribute

id: str | None = Field(
    default=None,
    description="The 'logical' identifier of the Entity in the system of record, e.g. a UUID.  This 'id' is unique within a given system, but may or may not be globally unique outside the system. It is used within a system to reference an object from another.",
)

name class-attribute instance-attribute

name: str | None = Field(
    default=None,
    description="A primary name for the entity.",
)

description class-attribute instance-attribute

description: str | None = Field(
    default=None,
    description="A free-text description of the Entity.",
)

aliases class-attribute instance-attribute

aliases: list[str] | None = Field(
    default=None,
    description="Alternative name(s) for the Entity.",
)

extensions class-attribute instance-attribute

extensions: list[Extension] | None = Field(
    default=None,
    description="A list of extensions to the Entity, that allow for capture of information not directly supported by elements defined in the model.",
)

digest class-attribute instance-attribute

digest: (
    Annotated[
        str,
        StringConstraints(pattern="^[0-9A-Za-z_\\-]{32}$"),
    ]
    | None
) = Field(
    default=None,
    description="A sha512t24u digest created using the VRS Computed Identifier algorithm.",
)

expressions class-attribute instance-attribute

expressions: list[Expression] | None = None

ga4gh

Bases: ga4gh

Define GA4GH serialization metadata for this model.

prefix class-attribute instance-attribute

prefix = 'DM'

inherent class-attribute instance-attribute

inherent = ['components', 'type']

schema_id classmethod

schema_id() -> str

Return the canonical JSON Schema identifier for the model.

Returns:

Type Description
str

Canonical schema URI.

maturity classmethod

maturity() -> Maturity

Return the GKM maturity level for the model.

Returns:

Type Description
Maturity

Declared maturity level.

apply_schema_metadata classmethod

apply_schema_metadata(
    schema: dict[str, Any],
) -> dict[str, Any]

Add GKM metadata to a generated JSON Schema.

Parameters:

Name Type Description Default
schema dict[str, Any]

Generated JSON Schema to mutate in place.

required

Returns:

Type Description
dict[str, Any]

The annotated JSON Schema.

model_json_schema classmethod

model_json_schema(
    by_alias: bool = True,
    ref_template: str = "#/$defs/{model}",
    schema_generator: type[
        GenerateJsonSchema
    ] = GenerateJsonSchema,
    mode: JsonSchemaMode = "validation",
    *,
    union_format: Literal[
        "any_of", "primitive_type_array"
    ] = "any_of",
) -> dict[str, Any]

Generate JSON Schema with GKM metadata.

Default values follow Pydantic defaults.

Parameters:

Name Type Description Default
by_alias bool

Whether to use field aliases.

True
ref_template str

Template for schema references.

'#/$defs/{model}'
schema_generator type[GenerateJsonSchema]

Pydantic schema generator class.

GenerateJsonSchema
mode JsonSchemaMode

Pydantic schema generation mode.

'validation'
union_format Literal['any_of', 'primitive_type_array']

How to represent unions; ignored on Pydantic versions older than 2.12.

'any_of'

Returns:

Type Description
dict[str, Any]

JSON Schema annotated with GKM metadata.

__hash__

__hash__() -> int

Hash the canonical JSON representation.

Returns:

Type Description
int

Hash of the serialized value.

ga4gh_serialize

ga4gh_serialize() -> dict

Serialize inherent fields for GA4GH digest computation.

Returns:

Type Description
dict

Mapping of inherent fields to serialized values.

is_ga4gh_identifiable staticmethod

is_ga4gh_identifiable() -> bool

Report whether this class supports GA4GH computed identifiers.

Returns:

Type Description
bool

Whether instances are identifiable.

__lt__

__lt__(other: Ga4ghIdentifiableObject) -> bool

Compare objects by their computed digests.

Parameters:

Name Type Description Default
other Ga4ghIdentifiableObject

Object to compare.

required

Returns:

Type Description
bool

Whether this digest sorts before the other digest.

has_valid_ga4gh_id

has_valid_ga4gh_id() -> bool | str | None

Check the existing identifier against the GA4GH identifier pattern.

Returns:

Type Description
bool | str | None

Match status, or the unset or empty identifier.

compute_digest

compute_digest(
    store: bool = True,
    as_version: PrevVrsVersion | None = None,
) -> str

Compute a sha512t24u digest, created using the VRS Computed Identifier algorithm.

Stores the digest in the object if store is True.

If as_version is provided, other parameters are ignored and a digest is returned following the conventions of the VRS version indicated by as_version.

Parameters:

Name Type Description Default
store bool

Save the computed digest on the object.

True
as_version PrevVrsVersion | None

Optional prior VRS version for serialization.

None

Returns:

Type Description
str

Computed digest.

Raises:

Type Description
AttributeError

If prior-version serialization is unsupported.

get_or_create_ga4gh_identifier

get_or_create_ga4gh_identifier(
    in_place: str = "default",
    recompute: bool = False,
    as_version: PrevVrsVersion | None = None,
) -> str

Get a GA4GH computed identifier and optionally update the object ID.

This function has three options for in_place editing of vro.id:

  • 'default': the standard identifier update behavior for GA4GH identifiable objects, this mode will update the vro.id field only when it is None
  • 'always': this will update the vro.id field any time the identifier is computed
  • 'never': the vro.id field will not be edited in-place, even when empty

recompute applies when this call computes an identifier. A valid existing ID returned by the default policy bypasses digest computation. An invalid existing ID is replaced in the return value, but is only stored with the always policy.

If as_version is provided, other parameters are ignored and an identifier is returned following the conventions of the VRS version indicated by as_version.

Parameters:

Name Type Description Default
in_place str

ID update policy: default, always, or never.

'default'
recompute bool

Recompute an existing digest.

False
as_version PrevVrsVersion | None

Optional prior VRS version.

None

Returns:

Type Description
str

GA4GH computed identifier.

Raises:

Type Description
ValueError

If the update policy is invalid.

compute_ga4gh_identifier

compute_ga4gh_identifier(
    recompute: bool = False,
    as_version: PrevVrsVersion | None = None,
) -> str

Return a GA4GH Computed Identifier.

If as_version is provided, other parameters are ignored and a computed identifier is returned following the conventions of the VRS version indicated by as_version.

Parameters:

Name Type Description Default
recompute bool

Recompute an existing digest.

False
as_version PrevVrsVersion | None

Optional prior VRS version.

None

Returns:

Type Description
str

GA4GH computed identifier.

get_or_create_digest

get_or_create_digest(recompute: bool = False) -> str

Return the cached digest, computing and storing it when needed.

Parameters:

Name Type Description Default
recompute bool

Recompute an existing digest when true.

False

Returns:

Type Description
str

Existing or newly computed digest.

CopyNumberCount

Bases: _VariationBase, BaseModelForbidExtra

The absolute count of discrete copies of a Location, within a system (e.g. genome, cell, etc.).

type class-attribute instance-attribute

type: Literal["CopyNumberCount"] = Field(
    default=VrsType.CN_COUNT.value,
    description=f'MUST be "{VrsType.CN_COUNT.value}"',
)

location class-attribute instance-attribute

location: iriReference | SequenceLocation = Field(
    ...,
    description="The location of the subject of the copy count.",
)

copies class-attribute instance-attribute

copies: Range | int = Field(
    ...,
    description="The integral number of copies of the subject in a system",
)

model_config class-attribute instance-attribute

model_config = ConfigDict(extra='forbid')

id class-attribute instance-attribute

id: str | None = Field(
    default=None,
    description="The 'logical' identifier of the Entity in the system of record, e.g. a UUID.  This 'id' is unique within a given system, but may or may not be globally unique outside the system. It is used within a system to reference an object from another.",
)

name class-attribute instance-attribute

name: str | None = Field(
    default=None,
    description="A primary name for the entity.",
)

description class-attribute instance-attribute

description: str | None = Field(
    default=None,
    description="A free-text description of the Entity.",
)

aliases class-attribute instance-attribute

aliases: list[str] | None = Field(
    default=None,
    description="Alternative name(s) for the Entity.",
)

extensions class-attribute instance-attribute

extensions: list[Extension] | None = Field(
    default=None,
    description="A list of extensions to the Entity, that allow for capture of information not directly supported by elements defined in the model.",
)

digest class-attribute instance-attribute

digest: (
    Annotated[
        str,
        StringConstraints(pattern="^[0-9A-Za-z_\\-]{32}$"),
    ]
    | None
) = Field(
    default=None,
    description="A sha512t24u digest created using the VRS Computed Identifier algorithm.",
)

expressions class-attribute instance-attribute

expressions: list[Expression] | None = None

ga4gh

Bases: ga4gh

Define GA4GH serialization metadata for this model.

prefix class-attribute instance-attribute

prefix = 'CN'

inherent class-attribute instance-attribute

inherent = ['copies', 'location', 'type']

schema_id classmethod

schema_id() -> str

Return the canonical JSON Schema identifier for the model.

Returns:

Type Description
str

Canonical schema URI.

maturity classmethod

maturity() -> Maturity

Return the GKM maturity level for the model.

Returns:

Type Description
Maturity

Declared maturity level.

apply_schema_metadata classmethod

apply_schema_metadata(
    schema: dict[str, Any],
) -> dict[str, Any]

Add GKM metadata to a generated JSON Schema.

Parameters:

Name Type Description Default
schema dict[str, Any]

Generated JSON Schema to mutate in place.

required

Returns:

Type Description
dict[str, Any]

The annotated JSON Schema.

model_json_schema classmethod

model_json_schema(
    by_alias: bool = True,
    ref_template: str = "#/$defs/{model}",
    schema_generator: type[
        GenerateJsonSchema
    ] = GenerateJsonSchema,
    mode: JsonSchemaMode = "validation",
    *,
    union_format: Literal[
        "any_of", "primitive_type_array"
    ] = "any_of",
) -> dict[str, Any]

Generate JSON Schema with GKM metadata.

Default values follow Pydantic defaults.

Parameters:

Name Type Description Default
by_alias bool

Whether to use field aliases.

True
ref_template str

Template for schema references.

'#/$defs/{model}'
schema_generator type[GenerateJsonSchema]

Pydantic schema generator class.

GenerateJsonSchema
mode JsonSchemaMode

Pydantic schema generation mode.

'validation'
union_format Literal['any_of', 'primitive_type_array']

How to represent unions; ignored on Pydantic versions older than 2.12.

'any_of'

Returns:

Type Description
dict[str, Any]

JSON Schema annotated with GKM metadata.

__hash__

__hash__() -> int

Hash the canonical JSON representation.

Returns:

Type Description
int

Hash of the serialized value.

ga4gh_serialize

ga4gh_serialize() -> dict

Serialize inherent fields for GA4GH digest computation.

Returns:

Type Description
dict

Mapping of inherent fields to serialized values.

is_ga4gh_identifiable staticmethod

is_ga4gh_identifiable() -> bool

Report whether this class supports GA4GH computed identifiers.

Returns:

Type Description
bool

Whether instances are identifiable.

__lt__

__lt__(other: Ga4ghIdentifiableObject) -> bool

Compare objects by their computed digests.

Parameters:

Name Type Description Default
other Ga4ghIdentifiableObject

Object to compare.

required

Returns:

Type Description
bool

Whether this digest sorts before the other digest.

has_valid_ga4gh_id

has_valid_ga4gh_id() -> bool | str | None

Check the existing identifier against the GA4GH identifier pattern.

Returns:

Type Description
bool | str | None

Match status, or the unset or empty identifier.

compute_digest

compute_digest(
    store: bool = True,
    as_version: PrevVrsVersion | None = None,
) -> str

Compute a sha512t24u digest, created using the VRS Computed Identifier algorithm.

Stores the digest in the object if store is True.

If as_version is provided, other parameters are ignored and a digest is returned following the conventions of the VRS version indicated by as_version.

Parameters:

Name Type Description Default
store bool

Save the computed digest on the object.

True
as_version PrevVrsVersion | None

Optional prior VRS version for serialization.

None

Returns:

Type Description
str

Computed digest.

Raises:

Type Description
AttributeError

If prior-version serialization is unsupported.

get_or_create_ga4gh_identifier

get_or_create_ga4gh_identifier(
    in_place: str = "default",
    recompute: bool = False,
    as_version: PrevVrsVersion | None = None,
) -> str

Get a GA4GH computed identifier and optionally update the object ID.

This function has three options for in_place editing of vro.id:

  • 'default': the standard identifier update behavior for GA4GH identifiable objects, this mode will update the vro.id field only when it is None
  • 'always': this will update the vro.id field any time the identifier is computed
  • 'never': the vro.id field will not be edited in-place, even when empty

recompute applies when this call computes an identifier. A valid existing ID returned by the default policy bypasses digest computation. An invalid existing ID is replaced in the return value, but is only stored with the always policy.

If as_version is provided, other parameters are ignored and an identifier is returned following the conventions of the VRS version indicated by as_version.

Parameters:

Name Type Description Default
in_place str

ID update policy: default, always, or never.

'default'
recompute bool

Recompute an existing digest.

False
as_version PrevVrsVersion | None

Optional prior VRS version.

None

Returns:

Type Description
str

GA4GH computed identifier.

Raises:

Type Description
ValueError

If the update policy is invalid.

compute_ga4gh_identifier

compute_ga4gh_identifier(
    recompute: bool = False,
    as_version: PrevVrsVersion | None = None,
) -> str

Return a GA4GH Computed Identifier.

If as_version is provided, other parameters are ignored and a computed identifier is returned following the conventions of the VRS version indicated by as_version.

Parameters:

Name Type Description Default
recompute bool

Recompute an existing digest.

False
as_version PrevVrsVersion | None

Optional prior VRS version.

None

Returns:

Type Description
str

GA4GH computed identifier.

get_or_create_digest

get_or_create_digest(recompute: bool = False) -> str

Return the cached digest, computing and storing it when needed.

Parameters:

Name Type Description Default
recompute bool

Recompute an existing digest when true.

False

Returns:

Type Description
str

Existing or newly computed digest.

CopyNumberChange

Bases: _VariationBase, BaseModelForbidExtra

An assessment of the copy number of a Location within a system (e.g. genome, cell, etc.) relative to a baseline ploidy.

model_config class-attribute instance-attribute

model_config = ConfigDict(use_enum_values=True)

type class-attribute instance-attribute

type: Literal["CopyNumberChange"] = Field(
    default=VrsType.CN_CHANGE.value,
    description=f'MUST be "{VrsType.CN_CHANGE.value}"',
)

location class-attribute instance-attribute

location: iriReference | SequenceLocation = Field(
    ...,
    description="The location of the subject of the copy change.",
)

copyChange class-attribute instance-attribute

copyChange: CopyChange = Field(
    ...,
    description="MUST use one of the defined enumerations that are based on the corresponding EFO ontological terms for copy number variation. See Implementation Guidance for more details.",
)

id class-attribute instance-attribute

id: str | None = Field(
    default=None,
    description="The 'logical' identifier of the Entity in the system of record, e.g. a UUID.  This 'id' is unique within a given system, but may or may not be globally unique outside the system. It is used within a system to reference an object from another.",
)

name class-attribute instance-attribute

name: str | None = Field(
    default=None,
    description="A primary name for the entity.",
)

description class-attribute instance-attribute

description: str | None = Field(
    default=None,
    description="A free-text description of the Entity.",
)

aliases class-attribute instance-attribute

aliases: list[str] | None = Field(
    default=None,
    description="Alternative name(s) for the Entity.",
)

extensions class-attribute instance-attribute

extensions: list[Extension] | None = Field(
    default=None,
    description="A list of extensions to the Entity, that allow for capture of information not directly supported by elements defined in the model.",
)

digest class-attribute instance-attribute

digest: (
    Annotated[
        str,
        StringConstraints(pattern="^[0-9A-Za-z_\\-]{32}$"),
    ]
    | None
) = Field(
    default=None,
    description="A sha512t24u digest created using the VRS Computed Identifier algorithm.",
)

expressions class-attribute instance-attribute

expressions: list[Expression] | None = None

ga4gh

Bases: ga4gh

Define GA4GH serialization metadata for this model.

prefix class-attribute instance-attribute

prefix = 'CX'

inherent class-attribute instance-attribute

inherent = ['copyChange', 'location', 'type']

schema_id classmethod

schema_id() -> str

Return the canonical JSON Schema identifier for the model.

Returns:

Type Description
str

Canonical schema URI.

maturity classmethod

maturity() -> Maturity

Return the GKM maturity level for the model.

Returns:

Type Description
Maturity

Declared maturity level.

apply_schema_metadata classmethod

apply_schema_metadata(
    schema: dict[str, Any],
) -> dict[str, Any]

Add GKM metadata to a generated JSON Schema.

Parameters:

Name Type Description Default
schema dict[str, Any]

Generated JSON Schema to mutate in place.

required

Returns:

Type Description
dict[str, Any]

The annotated JSON Schema.

model_json_schema classmethod

model_json_schema(
    by_alias: bool = True,
    ref_template: str = "#/$defs/{model}",
    schema_generator: type[
        GenerateJsonSchema
    ] = GenerateJsonSchema,
    mode: JsonSchemaMode = "validation",
    *,
    union_format: Literal[
        "any_of", "primitive_type_array"
    ] = "any_of",
) -> dict[str, Any]

Generate JSON Schema with GKM metadata.

Default values follow Pydantic defaults.

Parameters:

Name Type Description Default
by_alias bool

Whether to use field aliases.

True
ref_template str

Template for schema references.

'#/$defs/{model}'
schema_generator type[GenerateJsonSchema]

Pydantic schema generator class.

GenerateJsonSchema
mode JsonSchemaMode

Pydantic schema generation mode.

'validation'
union_format Literal['any_of', 'primitive_type_array']

How to represent unions; ignored on Pydantic versions older than 2.12.

'any_of'

Returns:

Type Description
dict[str, Any]

JSON Schema annotated with GKM metadata.

__hash__

__hash__() -> int

Hash the canonical JSON representation.

Returns:

Type Description
int

Hash of the serialized value.

ga4gh_serialize

ga4gh_serialize() -> dict

Serialize inherent fields for GA4GH digest computation.

Returns:

Type Description
dict

Mapping of inherent fields to serialized values.

is_ga4gh_identifiable staticmethod

is_ga4gh_identifiable() -> bool

Report whether this class supports GA4GH computed identifiers.

Returns:

Type Description
bool

Whether instances are identifiable.

__lt__

__lt__(other: Ga4ghIdentifiableObject) -> bool

Compare objects by their computed digests.

Parameters:

Name Type Description Default
other Ga4ghIdentifiableObject

Object to compare.

required

Returns:

Type Description
bool

Whether this digest sorts before the other digest.

has_valid_ga4gh_id

has_valid_ga4gh_id() -> bool | str | None

Check the existing identifier against the GA4GH identifier pattern.

Returns:

Type Description
bool | str | None

Match status, or the unset or empty identifier.

compute_digest

compute_digest(
    store: bool = True,
    as_version: PrevVrsVersion | None = None,
) -> str

Compute a sha512t24u digest, created using the VRS Computed Identifier algorithm.

Stores the digest in the object if store is True.

If as_version is provided, other parameters are ignored and a digest is returned following the conventions of the VRS version indicated by as_version.

Parameters:

Name Type Description Default
store bool

Save the computed digest on the object.

True
as_version PrevVrsVersion | None

Optional prior VRS version for serialization.

None

Returns:

Type Description
str

Computed digest.

Raises:

Type Description
AttributeError

If prior-version serialization is unsupported.

get_or_create_ga4gh_identifier

get_or_create_ga4gh_identifier(
    in_place: str = "default",
    recompute: bool = False,
    as_version: PrevVrsVersion | None = None,
) -> str

Get a GA4GH computed identifier and optionally update the object ID.

This function has three options for in_place editing of vro.id:

  • 'default': the standard identifier update behavior for GA4GH identifiable objects, this mode will update the vro.id field only when it is None
  • 'always': this will update the vro.id field any time the identifier is computed
  • 'never': the vro.id field will not be edited in-place, even when empty

recompute applies when this call computes an identifier. A valid existing ID returned by the default policy bypasses digest computation. An invalid existing ID is replaced in the return value, but is only stored with the always policy.

If as_version is provided, other parameters are ignored and an identifier is returned following the conventions of the VRS version indicated by as_version.

Parameters:

Name Type Description Default
in_place str

ID update policy: default, always, or never.

'default'
recompute bool

Recompute an existing digest.

False
as_version PrevVrsVersion | None

Optional prior VRS version.

None

Returns:

Type Description
str

GA4GH computed identifier.

Raises:

Type Description
ValueError

If the update policy is invalid.

compute_ga4gh_identifier

compute_ga4gh_identifier(
    recompute: bool = False,
    as_version: PrevVrsVersion | None = None,
) -> str

Return a GA4GH Computed Identifier.

If as_version is provided, other parameters are ignored and a computed identifier is returned following the conventions of the VRS version indicated by as_version.

Parameters:

Name Type Description Default
recompute bool

Recompute an existing digest.

False
as_version PrevVrsVersion | None

Optional prior VRS version.

None

Returns:

Type Description
str

GA4GH computed identifier.

get_or_create_digest

get_or_create_digest(recompute: bool = False) -> str

Return the cached digest, computing and storing it when needed.

Parameters:

Name Type Description Default
recompute bool

Recompute an existing digest when true.

False

Returns:

Type Description
str

Existing or newly computed digest.

MolecularVariation

Bases: VRSMetadataMixin, RootModel

A Variation on a contiguous molecule.

root class-attribute instance-attribute

root: (
    Allele
    | RelativeAllele
    | CisPhasedBlock
    | Adjacency
    | Terminus
    | DerivativeMolecule
) = Field(
    ...,
    json_schema_extra={
        "description": "A `variation` on a contiguous molecule."
    },
    discriminator="type",
)

schema_id classmethod

schema_id() -> str

Return the canonical JSON Schema identifier for the model.

Returns:

Type Description
str

Canonical schema URI.

maturity classmethod

maturity() -> Maturity

Return the GKM maturity level for the model.

Returns:

Type Description
Maturity

Declared maturity level.

apply_schema_metadata classmethod

apply_schema_metadata(
    schema: dict[str, Any],
) -> dict[str, Any]

Add GKM metadata to a generated JSON Schema.

Parameters:

Name Type Description Default
schema dict[str, Any]

Generated JSON Schema to mutate in place.

required

Returns:

Type Description
dict[str, Any]

The annotated JSON Schema.

model_json_schema classmethod

model_json_schema(
    by_alias: bool = True,
    ref_template: str = "#/$defs/{model}",
    schema_generator: type[
        GenerateJsonSchema
    ] = GenerateJsonSchema,
    mode: JsonSchemaMode = "validation",
    *,
    union_format: Literal[
        "any_of", "primitive_type_array"
    ] = "any_of",
) -> dict[str, Any]

Generate JSON Schema with GKM metadata.

Default values follow Pydantic defaults.

Parameters:

Name Type Description Default
by_alias bool

Whether to use field aliases.

True
ref_template str

Template for schema references.

'#/$defs/{model}'
schema_generator type[GenerateJsonSchema]

Pydantic schema generator class.

GenerateJsonSchema
mode JsonSchemaMode

Pydantic schema generation mode.

'validation'
union_format Literal['any_of', 'primitive_type_array']

How to represent unions; ignored on Pydantic versions older than 2.12.

'any_of'

Returns:

Type Description
dict[str, Any]

JSON Schema annotated with GKM metadata.

SequenceExpression

Bases: VRSMetadataMixin, RootModel

An expression describing a Sequence.

root class-attribute instance-attribute

root: (
    LiteralSequenceExpression
    | ReferenceLengthExpression
    | LengthExpression
) = Field(
    ...,
    json_schema_extra={
        "description": "An expression describing a `Sequence`."
    },
    discriminator="type",
)

schema_id classmethod

schema_id() -> str

Return the canonical JSON Schema identifier for the model.

Returns:

Type Description
str

Canonical schema URI.

maturity classmethod

maturity() -> Maturity

Return the GKM maturity level for the model.

Returns:

Type Description
Maturity

Declared maturity level.

apply_schema_metadata classmethod

apply_schema_metadata(
    schema: dict[str, Any],
) -> dict[str, Any]

Add GKM metadata to a generated JSON Schema.

Parameters:

Name Type Description Default
schema dict[str, Any]

Generated JSON Schema to mutate in place.

required

Returns:

Type Description
dict[str, Any]

The annotated JSON Schema.

model_json_schema classmethod

model_json_schema(
    by_alias: bool = True,
    ref_template: str = "#/$defs/{model}",
    schema_generator: type[
        GenerateJsonSchema
    ] = GenerateJsonSchema,
    mode: JsonSchemaMode = "validation",
    *,
    union_format: Literal[
        "any_of", "primitive_type_array"
    ] = "any_of",
) -> dict[str, Any]

Generate JSON Schema with GKM metadata.

Default values follow Pydantic defaults.

Parameters:

Name Type Description Default
by_alias bool

Whether to use field aliases.

True
ref_template str

Template for schema references.

'#/$defs/{model}'
schema_generator type[GenerateJsonSchema]

Pydantic schema generator class.

GenerateJsonSchema
mode JsonSchemaMode

Pydantic schema generation mode.

'validation'
union_format Literal['any_of', 'primitive_type_array']

How to represent unions; ignored on Pydantic versions older than 2.12.

'any_of'

Returns:

Type Description
dict[str, Any]

JSON Schema annotated with GKM metadata.

Location

Bases: VRSMetadataMixin, RootModel

A contiguous segment of a biological sequence.

root class-attribute instance-attribute

root: SequenceLocation | RelativeSequenceLocation = Field(
    ...,
    json_schema_extra={
        "description": "A contiguous segment of a biological sequence."
    },
    discriminator="type",
)

schema_id classmethod

schema_id() -> str

Return the canonical JSON Schema identifier for the model.

Returns:

Type Description
str

Canonical schema URI.

maturity classmethod

maturity() -> Maturity

Return the GKM maturity level for the model.

Returns:

Type Description
Maturity

Declared maturity level.

apply_schema_metadata classmethod

apply_schema_metadata(
    schema: dict[str, Any],
) -> dict[str, Any]

Add GKM metadata to a generated JSON Schema.

Parameters:

Name Type Description Default
schema dict[str, Any]

Generated JSON Schema to mutate in place.

required

Returns:

Type Description
dict[str, Any]

The annotated JSON Schema.

model_json_schema classmethod

model_json_schema(
    by_alias: bool = True,
    ref_template: str = "#/$defs/{model}",
    schema_generator: type[
        GenerateJsonSchema
    ] = GenerateJsonSchema,
    mode: JsonSchemaMode = "validation",
    *,
    union_format: Literal[
        "any_of", "primitive_type_array"
    ] = "any_of",
) -> dict[str, Any]

Generate JSON Schema with GKM metadata.

Default values follow Pydantic defaults.

Parameters:

Name Type Description Default
by_alias bool

Whether to use field aliases.

True
ref_template str

Template for schema references.

'#/$defs/{model}'
schema_generator type[GenerateJsonSchema]

Pydantic schema generator class.

GenerateJsonSchema
mode JsonSchemaMode

Pydantic schema generation mode.

'validation'
union_format Literal['any_of', 'primitive_type_array']

How to represent unions; ignored on Pydantic versions older than 2.12.

'any_of'

Returns:

Type Description
dict[str, Any]

JSON Schema annotated with GKM metadata.

Variation

Bases: VRSMetadataMixin, RootModel

A representation of the state of one or more biomolecules.

root class-attribute instance-attribute

root: (
    Allele
    | RelativeAllele
    | CisPhasedBlock
    | Adjacency
    | Terminus
    | DerivativeMolecule
    | CopyNumberChange
    | CopyNumberCount
) = Field(
    ...,
    json_schema_extra={
        "description": "A representation of the state of one or more biomolecules."
    },
    discriminator="type",
)

schema_id classmethod

schema_id() -> str

Return the canonical JSON Schema identifier for the model.

Returns:

Type Description
str

Canonical schema URI.

maturity classmethod

maturity() -> Maturity

Return the GKM maturity level for the model.

Returns:

Type Description
Maturity

Declared maturity level.

apply_schema_metadata classmethod

apply_schema_metadata(
    schema: dict[str, Any],
) -> dict[str, Any]

Add GKM metadata to a generated JSON Schema.

Parameters:

Name Type Description Default
schema dict[str, Any]

Generated JSON Schema to mutate in place.

required

Returns:

Type Description
dict[str, Any]

The annotated JSON Schema.

model_json_schema classmethod

model_json_schema(
    by_alias: bool = True,
    ref_template: str = "#/$defs/{model}",
    schema_generator: type[
        GenerateJsonSchema
    ] = GenerateJsonSchema,
    mode: JsonSchemaMode = "validation",
    *,
    union_format: Literal[
        "any_of", "primitive_type_array"
    ] = "any_of",
) -> dict[str, Any]

Generate JSON Schema with GKM metadata.

Default values follow Pydantic defaults.

Parameters:

Name Type Description Default
by_alias bool

Whether to use field aliases.

True
ref_template str

Template for schema references.

'#/$defs/{model}'
schema_generator type[GenerateJsonSchema]

Pydantic schema generator class.

GenerateJsonSchema
mode JsonSchemaMode

Pydantic schema generation mode.

'validation'
union_format Literal['any_of', 'primitive_type_array']

How to represent unions; ignored on Pydantic versions older than 2.12.

'any_of'

Returns:

Type Description
dict[str, Any]

JSON Schema annotated with GKM metadata.

SystemicVariation

Bases: VRSMetadataMixin, RootModel

A Variation of multiple molecules in the context of a system, e.g. a genome, sample, or homologous chromosomes.

root class-attribute instance-attribute

root: CopyNumberChange | CopyNumberCount = Field(
    ...,
    json_schema_extra={
        "description": "A Variation of multiple molecules in the context of a system, e.g. a genome, sample, or homologous chromosomes."
    },
    discriminator="type",
)

schema_id classmethod

schema_id() -> str

Return the canonical JSON Schema identifier for the model.

Returns:

Type Description
str

Canonical schema URI.

maturity classmethod

maturity() -> Maturity

Return the GKM maturity level for the model.

Returns:

Type Description
Maturity

Declared maturity level.

apply_schema_metadata classmethod

apply_schema_metadata(
    schema: dict[str, Any],
) -> dict[str, Any]

Add GKM metadata to a generated JSON Schema.

Parameters:

Name Type Description Default
schema dict[str, Any]

Generated JSON Schema to mutate in place.

required

Returns:

Type Description
dict[str, Any]

The annotated JSON Schema.

model_json_schema classmethod

model_json_schema(
    by_alias: bool = True,
    ref_template: str = "#/$defs/{model}",
    schema_generator: type[
        GenerateJsonSchema
    ] = GenerateJsonSchema,
    mode: JsonSchemaMode = "validation",
    *,
    union_format: Literal[
        "any_of", "primitive_type_array"
    ] = "any_of",
) -> dict[str, Any]

Generate JSON Schema with GKM metadata.

Default values follow Pydantic defaults.

Parameters:

Name Type Description Default
by_alias bool

Whether to use field aliases.

True
ref_template str

Template for schema references.

'#/$defs/{model}'
schema_generator type[GenerateJsonSchema]

Pydantic schema generator class.

GenerateJsonSchema
mode JsonSchemaMode

Pydantic schema generation mode.

'validation'
union_format Literal['any_of', 'primitive_type_array']

How to represent unions; ignored on Pydantic versions older than 2.12.

'any_of'

Returns:

Type Description
dict[str, Any]

JSON Schema annotated with GKM metadata.

flatten

flatten(vals: object) -> Iterator[object]

Yield values from nested lists and sets.

Parameters:

Name Type Description Default
vals object

Scalar or nested collection to flatten.

required

Returns:

Type Description
Iterator[object]

Iterator over leaf values.

flatten_type

flatten_type(t: object) -> list[object]

Flatten a complex type into a list of constituent types.

Parameters:

Name Type Description Default
t object

Type annotation to inspect.

required

Returns:

Type Description
list[object]

Constituent types or literal values.

overlaps

overlaps(a: list, b: list) -> bool

Return true if there are any elements in common between a and b

Parameters:

Name Type Description Default
a list

First collection.

required
b list

Second collection.

required

Returns:

Type Description
bool

Whether the collections share any values.

pydantic_class_refatt_map

pydantic_class_refatt_map() -> tuple[
    list[type[BaseModel]],
    list[type[BaseModel]],
    dict[str, list[str]],
    dict[str, list[str]],
]

Collect referable model classes, field references, and inherent fields.

Referable fields can contain identifiable objects or references to them. For example, the referable-field map includes {"Allele": ["location"]}.

Returns:

Type Description
tuple[list[type[BaseModel]], list[type[BaseModel]], dict[str, list[str]], dict[str, list[str]]]

Referable classes, root-model unions containing them, the referable-field map, and the inherent-field map, in that order.