Steps to include these valuesets in an existing LinkML schema

[bfurner]

It is not clear from the documentation how one includes / references these valuesets from within an existing LinkML schema's YAML. Are these handled as imports? If so, is there a specific nomenclature to use?

[github-actions]

Issue Summary

This is an excellent documentation gap issue that highlights a critical missing piece in the valuesets project documentation. The user @bfurner is asking about the practical mechanics of how to include/reference these valuesets from within existing LinkML schema YAML files.

Analysis

Current State

Based on my analysis of the repository structure and LinkML documentation:

1. The valuesets project is organized as a collection of LinkML enums spread across domain-specific modules:

   • Core enums in src/valuesets/schema/core.yaml
   • Biological enums in src/valuesets/schema/bio/
   • Healthcare, statistics, and other domain-specific modules
   • All consolidated in the main src/valuesets/schema/valuesets.yaml file

2. Import mechanisms exist in LinkML but the documentation doesn't clearly explain how to use them with this package.

The Missing Documentation

Users need clear guidance on three different approaches for using these valuesets:

Approach 1: Direct Schema Imports (Local Development)

# In your schema YAML file
imports:
  - https://w3id.org/linkml/valuesets/core
  - https://w3id.org/linkml/valuesets/bio/taxonomy
  
classes:
  Person:
    attributes:
      sex:
        range: SexEnum  # From core module
      organism:
        range: CommonOrganismTaxaEnum  # From bio/taxonomy

Approach 2: Python Package Usage (Runtime)

# This works now per the README examples
from valuesets.enums.core import SexEnum
from valuesets.enums.bio.taxonomy import CommonOrganismTaxaEnum

Approach 3: Schema Generation/Publishing

The project should clarify:

• Are published schemas available at https://w3id.org/linkml/valuesets/?
• Should users copy specific enum definitions?
• How to handle versioning and updates?

Related Context

• Issue Add Likert Scales #8 discusses implementation details about Likert scales and integer values in enums
• The README provides excellent Python usage examples but lacks LinkML schema import guidance
• The main schema file shows the internal import structure but doesn't document external usage

Recommendations

This issue should be tagged as documentation and good first issue. The solution involves:

1. Expanding the README with a "Using in LinkML Schemas" section
2. Creating examples showing different import approaches
3. Clarifying the published schema URLs and their availability
4. Adding a simple tutorial for common use cases

This is exactly the kind of practical documentation that bridges the gap between "here's what we built" and "here's how you use it in your project."