Add JSON schemas documenting the v5.4 table- and field-level metadata

[PouyanJay]

Summary

Adds machine-readable JSON Schemas (draft-04) documenting the metadata columns of:

• inst/csv/OMOP_CDMv5.4_Table_Level.csv
• inst/csv/OMOP_CDMv5.4_Field_Level.csv

This addresses the request in discussion #746 for formal definitions of metadata fields such as conceptPrefix and measurePersonCompletenessThreshold.

Representation

Each schema describes one CSV row represented as a JSON object (documented in inst/schema/README.md):

• Property names are identical to the CSV headers, including unique DQ identifiers.
• All values are JSON strings; the literal CSV value NA stays the string "NA" (not null).
• Draft-04 was chosen to match the example in the discussion; happy to move to a newer draft if preferred.

Column descriptions are sourced from this repository's code and the DataQualityDashboard check documentation (measurePersonCompleteness, fkDomain, fkClass link to their DQD vignettes). Columns with no current code consumer (conceptPrefix, validation, unique DQ identifiers) are described honestly and marked as pending maintainer confirmation rather than given invented semantics. Cross-field relationships that hold empirically (e.g. isForeignKey = "Yes" ⇔ fkTableName/fkFieldName set) are documented in the README as observed invariants but deliberately not enforced by the schemas.

Files added

• inst/schema/OMOP_CDMv5.4_Table_Level.schema.json
• inst/schema/OMOP_CDMv5.4_Field_Level.schema.json
• inst/schema/README.md
• extras/validateMetadataSchemas.R — optional standalone validation script (not part of the package; no DESCRIPTION changes)
• .github/workflows/validate-metadata.yml — optional CI validation that runs only when the v5.4 metadata CSVs or schemas change

The last two commits are separable — if you'd prefer schemas-only, I can drop the tooling commit.

Validation

• Both schema files parse as valid JSON
• All 39 table-level rows and 431/432 field-level rows validate against the schemas
• The single failing row is cdm_source.source_documentation_reference (line 355), the known malformed row from Fix CSV file formatting #744/Missing quotes around text block in CDM definition (CSV file for v5.4) result in incorrect number of items for that row. #775 fixed by fix: wrap comma-containing field in quotes in v5.4 Field_Level CSV (Fixes #775, #744) #792 — the CI workflow reports it as a known-issue warning (not a failure) until that fix merges, then the allowlist entry can be removed

Scope

No changes to the CDM structure, DDLs, or existing metadata CSV content.

Related discussion

#746

[MaximMoinat]

@PouyanJay Thanks for your contribution. Could you describe your use case for this PR? To my knowledge, these metadata tables were only intended to be used as input files this CommonDataModel and the DataQualityDashboard package. Would be great to learn about other tooling using these files.

[PouyanJay]

@MaximMoinat Thanks for taking a look! Some angles to the use case:

1. The direct trigger was discussion Is there a definitions schema or table that describes the Model #746. A user trying to consume these files programmatically asked where fields like conceptPrefix and measurePersonCompletenessThreshold are formally defined, and suggested a JSON Schema would be ideal. While researching the answer I found some columns have no definition anywhere outside the code that consumes them (and a few, like conceptPrefix and validation, appear to have no current consumer, the schema marks those as pending confirmation rather than guessing). The schemas are that missing data dictionary in machine-readable form.

2. These files are already consumed beyond CommonDataModel and DQD. Some examples I found. For example, dbt-synthea fetches both v5.4 CSVs straight from this repo's main branch to generate its dbt models, and pyCDMConnector, Data2Evidence, and ETL-LambdaBuilder all ship copies. The files are de facto a public interface , a schema gives those consumers something to code and validate against.

3. It protects this repo's own workflow. The schemas mechanically catch exactly the class of editing mistake in Fix CSV file formatting #744/Missing quotes around text block in CDM definition (CSV file for v5.4) result in incorrect number of items for that row. #775. I can go through the details if need be.

4. My own use case: I'm building an open-source agentic disease model (called OpenSina, still sits in a private repo) that generates OHDSI cohort definitions and SQL, and it will consume OMOP_CDMv5.4_Field_Level.csv from this repo the same way dbt-synthea's generate_dbt_yaml.py does as the machine-readable source of truth for CDM structure. For example, fkDomain = Condition on condition_occurrence.condition_concept_id tells the tool where a condition concept set applies, and isRequired/cdmDatatype inform the generated SQL. Prototyping that ingestion is what surfaced how fragile consuming the CSV without a contract is: the malformed cdm_source row (Fix CSV file formatting #744) parses into 14 columns silently, and nothing else tells you the allowed values of a column like isPrimaryKey. These schemas let a consumer validate each row at ingest unexpected columns, renamed headers, or out-of-range values fail loudly at build time instead of corrupting downstream output.