TAB Update: Concept Set Specification Draft Updated

Developers
1

Update: Concept Set Specification Draft

Thank you for the feedback on the draft Concept Set Specification. I’ve incorporated several community suggestions and TAB recommendations. Here’s a summary of the key updates:

Major Changes

1. Minimal Required Fields Approach

Based on Ed’s feedback, we’ve adopted a minimal required fields design for concept metadata. Only conceptId is now required within the concept object - all other vocabulary metadata fields (conceptName, domainId, vocabularyId, etc.) are optional and can be resolved by looking up the concept ID in any OMOP vocabulary instance.

Rationale:

  • Reduces file sizes for concept sets with many concepts
  • Avoids redundant storage of vocabulary metadata
  • Makes concept sets independent of vocabulary version updates
  • Allows tools to enrich concept data as needed based on available vocabulary access

2. Tool Provenance Tracking

Added optional createdByTool and modifiedByTool fields to track which software created or modified a concept set (e.g., “ATLAS 2.12.0”, “CAPR 4.3”). This complements the existing createdBy/modifiedBy fields:

  • createdBy/modifiedBy track who (person/user)
  • createdByTool/modifiedByTool track what (software/tool)
  • Both are optional and backward compatible with existing ATLAS/WebAPI implementations

3. Programmatic Schema Access

Per Vojtech’s suggestion, the JSON schema is now published as a standalone file accessible at: https://raw.githubusercontent.com/ohdsi/tab/main/docs/schemas/concept-set-schema.json

This enables programmatic validation, code generation, and tool development. The documentation automatically includes this schema via VitePress, maintaining a single source of truth.

4. Improved Documentation

  • Split the complex schema diagram into three focused diagrams for better readability
  • Added comprehensive “Design Philosophy” section explaining the minimal required fields approach
  • Enhanced implementation notes with guidance for both tool developers and concept set authors
  • Included examples showing both full metadata and minimal (ID-only) formats

Next Steps

TAB Meeting - Friday, November 7th at 10:30 AM EST

We invite the community to join us at the next OHDSI Technical Advisory Board meeting where we will discuss ratifying this specification. Your input is valuable, and we would appreciate any feedback before we move forward.

The complete specification is available at: Concept Set Specification | OHDSI Technical Advisory Board

Please review and share any thoughts or concerns before the meeting.

1 Like