Thank you for your interest in contributing! This document outlines how to contribute to the DOME Registry schema — the community-maintained, versioned JSON schema that underpins the DOME Registry for supervised machine learning methods in biology.
Contributions are made via a GitHub-based workflow using Pull Requests (PRs), reviewed and merged by the project maintainers. All contributions are licensed under CC BY 4.0.
- How to Contribute
- What to Contribute
- What Not to Contribute
- Versioning and Schema Evolution
- Contribution Licensing
- Review Process
If you find an error, want to propose a new field or category, or have an idea for improving the schema structure without submitting a PR yourself:
- Check existing issues: See if someone has already raised the same point or a similar suggestion at https://github.com/BioComputingUP/dome-schema/issues.
- Create a new issue: If not, open a new issue and include:
- A clear title and description of the proposed change or problem.
- For new fields, explain what DOME category it belongs to (Data, Optimisation, Model, or Evaluation), what information it captures, and why it is broadly useful.
- For breaking changes, explain why the benefit outweighs the migration cost.
- Links or references to supporting publications or community standards where applicable.
This is the preferred way to contribute schema changes.
- Fork the repository: Create your own copy of dome-schema on GitHub.
- Create a branch: Use a descriptive branch name:
Common prefixes:
git checkout -b feat/add-field-xyz
feat/(new field/feature),fix/(correction),docs/(documentation only),schema/(structural schema change). - Make your changes:
- Edit the relevant JSON schema file(s) under
releases/. - For new versions, create a new version folder (e.g.,
releases/v1.1.0/) — do not edit existing released versions in place. - Ensure JSON is valid and the schema is self-consistent.
- Update any user-facing documentation or the version
README.mdinside the release folder.
- Edit the relevant JSON schema file(s) under
- Commit your changes:
Use clear, descriptive commit messages. Reference any related issues.
git add . git commit -m "feat: Add field 'xyz' to Data section (closes #42)"
- Push to your fork:
git push origin feat/add-field-xyz
- Open a Pull Request:
- Go to the original dome-schema repository on GitHub.
- Open a PR from your branch.
- Provide a clear title and description explaining the change and its motivation.
- If the change affects schema version numbering, state the proposed new version and the version type (patch / minor / major) — see Versioning and Schema Evolution.
We welcome contributions that add or improve:
- New schema fields: Additional properties in the Data, Optimisation, Model, or Evaluation sections that capture information aligned with the DOME Recommendations and community needs.
- Field corrections: Fixes to field types, descriptions, required/optional status, or enumerations.
- Structural improvements: Better organisation of nested objects, improved
$refreferences, or vocabulary standardisation — discuss major structural changes via an issue first. - Tooling and validation: Scripts or CI workflows for validating entries against the schema, checking backward compatibility, or generating changelogs.
- Documentation: Improvements to field descriptions, version READMEs, or usage examples.
When proposing a new field, consider its alignment with the DOME Recommendations pillars:
| Pillar | Focus |
|---|---|
| D — Data | Training/test data, splits, provenance, accessibility |
| O — Optimisation | Cross-validation strategy, hyperparameter tuning, training conditions |
| M — Model | Architecture, algorithm type, parameters, availability |
| E — Evaluation | Metrics, benchmarks, comparison to baselines, fairness |
- Changes that edit a previously released schema version in place — released versions are immutable. Propose changes as a new version instead.
- Fields or changes that are not broadly applicable to supervised machine learning in biology; highly domain-specific extensions should be discussed in an issue first.
- Changes to core infrastructure files (GitHub Actions workflows,
.gitattributes, etc.) without prior maintainer discussion. - Promotional content or entries advertising specific tools without scientific grounding.
This repository follows Semantic Versioning (SemVer) for schema releases, using vMAJOR.MINOR.PATCH:
| Version type | When to use | Example |
|---|---|---|
| PATCH | Corrections to descriptions, fixing typos, clarifying enumerations — no structural change | v1.0.0 → v1.0.1 |
| MINOR | New optional fields or properties added in a backward-compatible way | v1.0.0 → v1.1.0 |
| MAJOR | Breaking changes: renaming or removing existing fields, changing field types, restructuring sections | v1.0.0 → v2.0.0 |
Each released version lives in its own folder under releases/ (e.g., releases/v1.0.0/) and is never modified after release. This ensures that applications and tools depending on a specific version remain stable, and that DOME Registry entries remain valid and interpretable against the schema version they were created under — including those generated at scale by automated pipelines such as DOME Copilot.
If you are unsure which version type applies to your proposed change, raise it as an issue to discuss with maintainers first.
By contributing to this repository, you agree that your contributions will be licensed under the CC BY 4.0 license. All contributed content must respect the intellectual property rights of others.
Project maintainers will review Pull Requests.
- We aim to review contributions promptly; complex changes or new major versions may take longer.
- Feedback or requests for revisions will be made via comments on the PR.
- Once approved, a maintainer will merge the PR into the
mainbranch and, where appropriate, tag a new release.
We appreciate every contribution that helps make AI/ML methods in biology more transparent, reproducible, and FAIR.