Add docs on new linkml validator AI guardrails

[cmungall]

There are two new plugins for linkml-validate

• https://github.com/linkml/linkml-reference-validator
• https://github.com/linkml/linkml-term-validator

While they are intended for general use, they are particularly useful for hallucination guardrails in AI curation pipelines.

Neither are OWL-aware, but the reference validator has some tips on how to use for checking obo format files: https://linkml.io/linkml-reference-validator/how-to/validate-obo-files/

@dragon-ai-agent please read the existing hallucination guardrails in this repo, then read the docs for the two above, and extend the docs here. My preference is if our docs here are largely the same focusing on concepts and at the end there is a link to implementations

[github-actions]

Issue Summary: LinkML Validator AI Guardrails Documentation

Overview

This issue requests documentation for two new LinkML validation plugins that serve as hallucination guardrails in AI-assisted curation workflows:

1. linkml-reference-validator - Validates quoted text against source publications
2. linkml-term-validator - Validates ontology term references

Context & Related Work

Existing Documentation

The repository already has foundational hallucination prevention documentation:

• docs/how-tos/make-ids-hallucination-resistant.md - Documents the ID/label checksum pattern for preventing identifier hallucinations

This existing guide covers the conceptual approach: requiring both IDs and labels for validation against authoritative sources (OAK, OLS, PubMed APIs).

Related Issues

• Issue Need a reliable, fast way to determine whether a PMID _actually_ supports a curated statement #45: "Need a reliable, fast way to determine whether a PMID actually supports a curated statement" - Directly addresses the problem that linkml-reference-validator solves
• Issue Document Anti-Hallucination ID/Label Checksum Pattern for Knowledge Curation #37 (closed): Documented the anti-hallucination ID/label checksum pattern - resulted in the current how-to guide
• Issue Add github actions for QC checks #49: Mentions adding LinkML GitHub actions for QC checks

Plugin Details

1. LinkML Reference Validator

Purpose: Validates that quoted text in scientific data actually appears in cited references

Key Features:

• Deterministic substring matching against actual publication text
• Supports PubMed IDs (PMID), with DOI/URL support planned
• Fetches abstracts and full-text from PubMed Central when available
• Editorial conventions: brackets [...] for notes, ellipsis ... for omitted text
• Local caching of references as Markdown with YAML metadata
• Works as LinkML validation plugin using linkml:authoritative_reference and linkml:excerpt markers

OBO Format Support: Has specific guidance for validating OBO axiom annotations using regex patterns like 'ex:supporting_text="([^"]*)\[(\S+:\S+)\]"'

Hallucination Prevention: Catches both fabricated quotes and incorrect reference assignments by requiring exact substring matches in source publications

Documentation: https://linkml.io/linkml-reference-validator/

• Includes quickstart, tutorials (CLI and Python API), how-to guides, and concepts/reference sections

2. LinkML Term Validator

Purpose: Validates LinkML schemas and datasets against external ontology terms

Key Features:

• Three composable validation plugins:
  • Schema validation: checks meaning fields in enum permissible values
  • Dynamic enum validation: ensures data matches enums with reachable_from, matches, or concepts
  • Binding constraints: validates nested object fields satisfy binding ranges
• Multi-level caching (in-memory + file-based)
• Multiple ontology sources via OAK (Ontology Access Kit)
• CLI and Python API interfaces

Hallucination Prevention: Grounds semantic assertions in authoritative ontologies, preventing AI systems from inventing or misrepresenting term definitions

Use Cases:

1. Data quality assurance - prevents invalid ontology references
2. Schema governance - ensures consistent term usage
3. Integration validation - confirms external data conforms to schemas
4. Knowledge management - maintains semantic accuracy in knowledge graphs

Documentation Strategy

Per Chris's preference, the documentation should:

1. Focus on concepts - Extend the existing conceptual framework in docs/how-tos/make-ids-hallucination-resistant.md
2. Link to implementations - At the end, provide links to the specific LinkML validator plugins as implementation options

Suggested Structure

The documentation could be extended to cover:

Conceptual Layer (building on existing doc):

• Identifier validation (already covered)
• NEW: Reference/citation validation - ensuring quoted text actually appears in sources
• NEW: Ontology term semantic validation - ensuring terms exist and have correct meanings in authoritative ontologies

Implementation Layer (new section):

• Link to linkml-reference-validator for citation validation
• Link to linkml-term-validator for ontology validation
• Link to OAK/OLS APIs for identifier validation
• Integration patterns for validation in curation workflows

Key Insight

These validators address the entire validation stack for AI curation:

1. Identifiers (existing docs) - prevent fake IDs (GO:9999999, PMID:99999999)
2. Terms (linkml-term-validator) - prevent semantic misuse of valid terms
3. Evidence (linkml-reference-validator) - prevent fabricated supporting quotes

Together, they form a comprehensive guardrail system for AI-assisted scientific curation.

Recommendation

The @dragon-ai-agent should create/extend documentation that:

1. Expands the conceptual framework to include citation validation and semantic validation
2. Maintains the practical, immediately-actionable style of existing docs
3. Links to LinkML validators as battle-tested implementations
4. Provides integration guidance for curation workflows

[dragon-ai-agent]

I've extended the hallucination guardrails documentation as requested.

What I did:

1. Read existing documentation: Reviewed docs/how-tos/make-ids-hallucination-resistant.md to understand the current approach

2. Researched the implementations: Studied the documentation for both:

   • linkml-term-validator (ontology term validation)
   • linkml-reference-validator (text excerpt validation)

3. Extended the docs with concept-focused content: Added a new "Two Key Validation Strategies" section that explains:

   • Validating Ontology Terms: The dual validation (ID + label) approach and why it prevents hallucinations
   • Validating Text Excerpts: The deterministic matching approach for verifying quotes against source publications

4. Added implementation links: Created an "Implementation Tools" section at the end that links to both validators with brief descriptions

Approach

Following your preference, the documentation focuses on concepts rather than implementation details:

• Explains the principles behind each validation strategy
• Describes why these approaches work to prevent hallucinations
• Links to the actual implementations for users who want to use these specific tools

The new content integrates naturally with the existing material, creating a cohesive guide to hallucination prevention strategies.

See PR #52 for the full changes.

[dragon-ai-agent]

I've extended the hallucination guardrails documentation as requested. The changes are in PR #53.

What I Added

Conceptual Framework:

• Distinguished between two complementary validation approaches:
  • Term Validation (ID + label checking) - prevents fabricated identifiers
  • Reference Validation (quote + citation checking) - prevents fabricated text excerpts
• Explained the principles, use cases, and why both matter for comprehensive AI guardrails

Enhanced Examples:

• Added examples of text excerpt validation from publications
• Showed how editorial conventions (brackets, ellipses) are supported
• Demonstrated combined validation scenarios

Implementation Links:

• Following your preference, the core documentation focuses on concepts
• Added a detailed "Implementation Tools" section at the end with links to:
  • linkml-term-validator
  • linkml-reference-validator
  • OBO file validation guide

The documentation now provides a conceptual foundation while pointing readers to the specific implementation docs for technical details.

Please review PR #53 and let me know if you'd like any adjustments!