Support JSON Schema validation workflows (biovalidator-style custom keywords)

[cmungall]

linkml-term-validator currently supports two usage patterns:

• Standalone CLI
• LinkML validator plugin

However, some users need to work within JSON Schema validation workflows—either because they author JSON Schema natively or because downstream tools require JSON Schema validators. These users still need ontology term validation (dynamic enums, reachable_from constraints, etc.).

Current Options

Option 1: Materialize to static JSON Schema

Already well-supported via linkml-term-validator or vskit. See [Dynamic Enums documentation](https://linkml.io/linkml/schemas/enums.html#dynamic-enums).

Pros:

• Works with any JSON Schema validator
• No custom tooling required at validation time

Cons:

• Produces large, unwieldy schemas (especially for broad constraints like "any descendant of GO:0008150")
• Requires regeneration when ontologies update
• Loses the semantic intent of the constraint

Option 2: JSON Schema Vocabularies (Draft 2019-09+)

The json-schema-vocabularies mechanism allows formal extension of JSON Schema with custom keywords.

Pros:

• Standards-compliant approach
• Clean separation of concerns

Cons:

• Limited validator support in practice
• Most validators only partially implement vocabulary features
• Adds complexity for end users

Option 3: Custom keywords with specialized validator (HCA/biovalidator pattern)

The Human Cell Atlas project defined a graph_restriction keyword (see [linkml/linkml#274](linkml/linkml#274)) and ELIXIR maintains [biovalidator](https://github.com/elixir-europe/biovalidator) to interpret it:

"ontology": {
  "type": "string",
  "graph_restriction": {
    "ontologies": ["obo:go"],
    "classes": ["GO:0007049"],
    "relations": ["rdfs:subClassOf"],
    "direct": false,
    "include_self": false
  }
}

This is semantically equivalent to LinkML's reachable_from:

reachable_from:
  source_ontology: obo:go
  source_nodes: [GO:0007049]
  relationship_types: [rdfs:subClassOf]
  include_self: false

Pros:

• Pragmatic, proven in production (HCA, ELIXIR)
• Schema remains human-readable with semantic intent preserved
• Standard validators ignore custom keywords (graceful degradation)

Cons:

• Requires biovalidator or compatible tooling
• Not a formal standard (though widely adopted in life sciences)

Proposal / Discussion

Should linkml-term-validator support the biovalidator ecosystem? Possible directions:

1. Generate graph_restriction keywords when converting LinkML → JSON Schema (alternative to materialization)
2. Provide a biovalidator-compatible mode or adapter
3. Document interoperability with biovalidator for users who need JSON Schema workflows
4. Contribute upstream to biovalidator to align keyword semantics with LinkML

Related

• [linkml/linkml#274](All ontology selectors extension to LinkML, similar to HCA jsonschema linkml#274) - Original HCA schema discussion
• [elixir-europe/biovalidator](https://github.com/elixir-europe/biovalidator) - JSON Schema validator with OLS integration
• [OLS graph_restriction docs](https://www.ebi.ac.uk/ols/docs/api) - EMBL-EBI implementation

[cmungall]

@sierra-moxon possibly this belongs in the main linkml discussions

[github-actions]

Summary: JSON Schema Validation Workflows for Ontology Terms

This issue explores bridging LinkML's ontology validation capabilities with JSON Schema-centric workflows, particularly the graph_restriction pattern used by the Human Cell Atlas and ELIXIR biovalidator.

Context & Background

The Core Problem: Many bioinformatics users need ontology term validation within JSON Schema workflows, but materializing LinkML dynamic enums to static JSON Schema produces unwieldy, hard-to-maintain schemas that lose semantic intent.

Historical Evolution:

• 2021: Human Cell Atlas introduced graph_restriction custom keyword for JSON Schema (All ontology selectors extension to LinkML, similar to HCA jsonschema linkml#274)
• 2022: LinkML 1.3 added reachable_from support, closing All ontology selectors extension to LinkML, similar to HCA jsonschema linkml#274
• Present: Gap remains between LinkML's native validation and JSON Schema ecosystems

Technical Deep Dive

Semantic Equivalence

LinkML's reachable_from and biovalidator's graph_restriction are nearly identical:

LinkML:

reachable_from:
  source_ontology: obo:go
  source_nodes: [GO:0007049]
  relationship_types: [rdfs:subClassOf]
  include_self: false

JSON Schema + biovalidator:

"graph_restriction": {
  "ontologies": ["obo:go"],
  "classes": ["GO:0007049"],
  "relations": ["rdfs:subClassOf"],
  "direct": false,
  "include_self": false
}

Biovalidator Architecture

From my research, biovalidator:

• Extends AJV (JavaScript JSON Schema validator)
• Adds async validation via OLS API calls
• Supports three custom keywords: graphRestriction, isChildTermOf, isValidTerm
• Requires "$async": true in schemas
• Used in production by ELIXIR and HCA projects

JSON Schema Vocabularies Approach

The json-schema-vocabularies project (JSON Schema draft 2019-09+) provides a standards-compliant extension mechanism, but:

• Implementation support varies widely across validators
• Adds complexity for end users
• Not widely adopted for ontology use cases yet

Implementation Options Analysis

Approach	Effort	Interoperability	Maintenance
1. Generate graph_restriction	Medium	High (works with biovalidator)	Low (automatic translation)
2. Biovalidator-compatible mode	Medium-High	High	Medium (alignment needed)
3. Document interop patterns	Low	Medium (manual process)	Low
4. Upstream contribution	High	Very High	Medium-High

Recommendations

Short-term (Low effort, high value):

1. Documentation: Create guide showing LinkML → JSON Schema + biovalidator workflows
2. Example schemas: Provide working examples with both LinkML and biovalidator versions

Medium-term (Moderate effort):
3. Generator enhancement: Add --json-schema-flavor biovalidator flag to emit graph_restriction keywords instead of materialized enums
4. Test suite: Validate that generated schemas work with biovalidator

Long-term (Strategic):
5. Upstream collaboration: Work with ELIXIR biovalidator team to ensure semantic alignment
6. OAK adapter: Consider whether biovalidator could use OAK instead of OLS directly

Related Issues in This Repo

• Issue term cache files should be free of spurious diffs #9: Cache file management (affects performance for both workflows)
• Issue Question: can linkml-term-validator support using classes or slot lists as vocabulary sources? #10: Class-based vocabularies (complementary validation strategy)

Use Cases

This would benefit:

• HCA/ELIXIR users who need JSON Schema validation with ontology constraints
• Mixed toolchain projects where some tools expect JSON Schema
• Legacy systems that can't easily adopt LinkML validation plugins
• Regulatory submissions where JSON Schema is mandated format

Open Questions

1. Should linkml-term-validator be opinionated about biovalidator vs vocabularies approach?
2. Do we need bidirectional conversion (biovalidator → LinkML)?
3. What's the maintenance burden of keeping keyword semantics aligned?
4. Should this live in linkml-term-validator or upstream in LinkML core generators?

---

Status of linkml/linkml#274: Closed as completed in LinkML 1.3 milestone. The dynamic enum functionality was implemented in LinkML core, but the JSON Schema export path still materializes enums rather than preserving them as semantic constraints.

Ecosystem Context: The json-schema-vocabularies project shows growing interest in extensible JSON Schema with domain-specific vocabularies across multiple languages, suggesting standardization momentum may build over time.