"""
This module contains the definition of the Concept class
which is used when the value(s) of a field are drawn from a controlled vocabulary.

Example:

class Species(Concept):
    pass

species = Species(
    canonical_id="http://purl.obolibrary.org/obo/NCIT_C45247",
    canonical_term="Mus musculus",
    user_facing_display="Mouse",
)
"""

from __future__ import annotations

from ts_ids_core.annotations import Nullable
from ts_ids_core.base.ids_element import IdsElement
from ts_ids_core.base.ids_field import IdsField


class Concept(IdsElement):
    """
    A concept is a semantic entity (e.g. from a controlled vocabulary) with a unique identifier.
    """

    canonical_id: Nullable[str] = IdsField(
        description="Unique identifier, often a URI assigned to a concept.",
    )
    canonical_term: Nullable[str] = IdsField(
        description="Preferred label or name of concept.",
    )
    user_facing_display: Nullable[str] = IdsField(
        description="User facing display of the concept.",
    )
