Question: can linkml-term-validator support using classes or slot lists as vocabulary sources?

[sierra-moxon]

While working with bindings in linkml-term-validator, we ran into a modeling question around whether structured LinkML content (classes or slot lists) could act as vocabularies, similar to enums or ontology-backed term sets.
This came up when trying to model rich “terms” (e.g. harmonized variables / CDE-like concepts) that carry substantially more metadata than fits comfortably in a permissible value.

Is it possible to support bindings where the vocabulary is derived from:

• a list of classes (e.g. all subclasses or instances of Term), or
• a declared slot list within the schema

Conceptually, something like:

bindings:
  - binds_value_of: id
    source: class
    range: Term

Intended meaning:
Validate that the id of an inlined Term corresponds to one of the structured terms defined in the schema.
This would allow terms to be modeled as objects while still benefiting from controlled-vocabulary validation.

My notes that led me to this ticket for future memory:
Take a PV like, ALBUMIN_IN_BLOOD:

MeasurementObservationTypeEnum:
    description: Values describing the types of MeasurementObservations.
    permissible_values:
      ALBUMIN_IN_BLOOD: 
        meaning: OBA:2050068 #Albumin in blood

and make it into a "term" subclass. (keep generic Term class in the model so we can use it as a Range for observation_type, but have more specific kinds of Terms, e.g., AlbuminInBloodTerm is_a Term to keep specificity. Term class would have slots equivalent to all columns in Anne's spreadsheet)

Then, in the BDCHM schema, observation_type definition becomes something like this:

      observation_type:
        description: The type of Observation being represented (e.g. 'diastolic blood pressure')
        comments: This field holds the "key" in the core key-value pair comprised of the observation_type field and the relevant value(s) field.  
        range: Term
        inlined: true
        bindings:
           - binds_value_of: id
             range: MeasurementObservationTypeEnum

And easurementObservationTypeEnum becomes:

enums:
  MeasurementObservationTypeEnum:
     reachable_from:

then we slot in the ontology from the team in the reachable_from annotations? What is the best practice here?
If we could use the subclasses of Term in this example as the vocab, that would be sweet.

[github-actions]

Summary

This issue explores extending linkml-term-validator's binding validation capabilities to support classes and slot lists as vocabulary sources, beyond the current support for enums and ontology-backed term sets.

Context: The Use Case

The request stems from working with the NHLBI-BDC-DMC Harmonization Model (BDCHM), specifically around modeling rich "terms" (harmonized variables / Common Data Elements) that carry more metadata than fits in a simple permissible value. The motivating example is ALBUMIN_IN_BLOOD, currently modeled as an enum permissible value with a meaning field pointing to an ontology term.

Current Architecture

The BindingValidationPlugin (src/linkml_term_validator/plugins/binding_plugin.py:66) currently supports:

1. Static enums - validates against permissible_values keys and their meanings
2. Dynamic enums - validates against ontology-backed enums using:
   • reachable_from - descendants of specified terms
   • matches - pattern-based term selection
   • concepts - explicit term lists

The binding mechanism allows validation of nested object fields:

bindings:
  - binds_value_of: id
    range: SomeEnum  # Must be an EnumDefinition

Proposed Extension

The request is to allow bindings where the vocabulary source is:

1. Class hierarchy - all subclasses or instances of a Term class
2. Slot lists - declared slot values within the schema

Conceptual syntax:

bindings:
  - binds_value_of: id
    source: class  # NEW: specify source type
    range: Term    # A ClassDefinition instead of EnumDefinition

This would validate that observation_type.id corresponds to one of the structured Term subclasses defined in the schema (e.g., AlbuminInBloodTerm, DiastolicBloodPressureTerm, etc.).

Design Considerations

1. Architectural Pattern

The current plugin architecture (BaseOntologyPlugin → BindingValidationPlugin) is built around enum validation via the _validate_against_enum() method (binding_plugin.py:426). Supporting class-based vocabularies would require:

• New validation pathway parallel to enum validation
• Schema introspection to collect valid class instances/subclasses
• Potentially a new source parameter on EnumBinding to distinguish between enum vs. class ranges

2. Validation Semantics

When validating against a class hierarchy, what constitutes a valid value?

• Option A: The id field of any instantiated subclass of Term in the schema
• Option B: Any declared class name that is_a Term
• Option C: A hybrid - allow both class names and instance IDs

3. Caching Strategy

The plugin already supports two caching modes (CacheStrategy.PROGRESSIVE vs GREEDY) for dynamic enums. Class-based vocabularies would need similar treatment:

• Greedy: Collect all valid class IDs upfront in pre_process()
• Progressive: Lazy validation by checking class hierarchy on-demand

4. Integration with Existing Features

The plugin also validates labels (validate_labels=True) and checks term existence in ontologies (strict=True). How should these work with class-based validation?

Related Patterns in Metadata Standards

This request aligns with Common Data Element (CDE) modeling patterns used in clinical research:

• NIH CDE Repository - structured metadata for harmonized variables
• CDISC CDASH - clinical data acquisition standards
• ISO 11179 - metadata registry standards

These typically require richer term representations than simple enums can provide (e.g., units, value sets, provenance, mappings).

Recommendation: Hybrid Approach

Consider a two-phase solution:

Phase 1: Enhanced Enum Support
Instead of moving to class-based validation, enhance the current enum pattern to better support rich terms:

# Define rich terms as enum PVs with structured annotations
enums:
  MeasurementObservationTypeEnum:
    permissible_values:
      ALBUMIN_IN_BLOOD:
        meaning: OBA:2050068
        annotations:
          unit: g/dL
          value_set: LOINC:1234-5
          harmonization_source: Anne's spreadsheet
          # ... other metadata from spreadsheet columns

This keeps the validation simple while allowing rich metadata in annotations.

Phase 2: Class-based Validation (if needed)
If Phase 1 proves insufficient, implement class-based validation:

1. Add source field to EnumBinding (default: "enum")
2. Create _validate_against_class() method parallel to _validate_against_enum()
3. Support both range: EnumDefinition and range: ClassDefinition
4. Collect valid class IDs during pre_process() based on class hierarchy

Questions for Clarification

1. Metadata usage: How will the additional Term metadata (from Anne's spreadsheet columns) be used? If it's just for documentation/provenance and not validation, annotations on enum PVs might suffice.

2. Validation requirements: Do you need to validate relationships between terms (e.g., "this observation_type requires these specific units")? That would favor class-based modeling.

3. Schema evolution: How frequently do new terms get added? If it's high-churn, having them as separate class definitions might create schema management overhead vs. adding enum PVs.

4. Hybrid approach: Could you use enums for validation but generate Term class instances at runtime for data representation? This separates concerns: enums for validation, classes for data modeling.

Next Steps

If you'd like to proceed with implementing class-based validation, I recommend:

1. Create a minimal example schema showing desired Term class hierarchy
2. Define expected validation behavior with test cases
3. Decide on caching strategy and integration points
4. Consider whether this should be a new plugin or extension of BindingValidationPlugin

Related Issues

• Issue term cache files should be free of spurious diffs #9 - Cache file timestamp management (related to validation performance concerns)

---

Note: I don't have access to "Anne's spreadsheet" (Google Sheets link requires auth), so I can't analyze the specific metadata requirements. If you can share the column structure or a sanitized example, that would help refine the design.

[cmungall]

What I had in mind was more like a large collection of slots:

prefixes:
  my_slot_schema: ...
slots:
  albumin_in_blood:
    range: float
    unit: ...
  calcium_in_blood:
    range: float
    unit:...
  # <potentially 100s more>

then making a dynamic enum from it:

enums:
  MeasurementEnum:
    < some way of saying this should shadow slots in my_slot_schema >

Then allowing this to be used in combination with an EAV type generic model (similar to https://linkml.io/linkml/howtos/model-measurements.html#generic-quantity-type-pattern but for now assume simple scalar values with the vocabulary bakes in the unit for simplicity)

classes:
  Subject:
    attributes:
      id:
        identifier: true
      measurements:
        range: Measurement
        multivalued: true
  Measurement:
    attributes:
      measurement_type:
        range: uriorcurie
        bindings:
          - binds_value_of: id
            source: class
            range: MeasurementEnum
      value:
        range: decimal

Data would look like:

id: P001
measurements:
 - measurement_type: my_slot_schema:albumin_in_blood
   value: ...
 - ...

Using core linkml tools this would give some flexibility and delayed validation using the slot vocab. In fact this could be done in 2 days:

1. a pivot/unmelt to make each meaurement type a column/slot, then use core linkml validation
2. validation on the EAV representation with vocabulary validation done by the term validator extension

The main thing to decide is how best to specify that the dynamic enum mirrors the slots. This should be consistent with the OWL representation;

this formally works:

MeasurementEnum:
  reachable_from:
    source_nodes:
      - my_slot_schema:
    relationship_types:
      - skos:inScheme

But is a little obscure.

If the original slot has a hierarchy then this fits naturally into reachable_from

slots:
  measurement_slot:
     abstract: true
  albumin_in_blood:
    is_a: measurement_slot
    range: float
    unit: ...

MeasurementEnum:
  reachable_from:
    source_nodes:
      - my_slot_schema:measurement_slot
    relationship_types:
      - rdfs:subPropertyOf

but this adds verbiage to the slot schema

A more direct representation might be:

MeasurementEnum:
  implements:
    - linkml:SlotsAsVocabulary
  annotations:
    source_schema: my_slot_schema