diff --git a/heudiconv/bids.py b/heudiconv/bids.py
index 1bbfcf6..9569278 100644
--- a/heudiconv/bids.py
+++ b/heudiconv/bids.py
@@ -240,6 +240,27 @@ def add_participant_record(studydir, subject, age, sex):
             known_subjects = {l.split('\t')[0] for l in f.readlines()}
         if participant_id in known_subjects:
             return
+    else:
+        # Populate particpants.json (an optional file to describe column names in
+        # participant.tsv). This auto generation will make BIDS-validator happy.
+        participants_json = op.join(studydir, 'participants.json')
+        if not op.lexists(participants_json):
+            save_json(participants_json,
+                OrderedDict([
+                    ("participant_id", OrderedDict([
+                        ("Description", "Participant identifier")])),
+                    ("age", OrderedDict([
+                        ("Description", "Age in years (TODO - verify) as in the initial"
+                            " session, might not be correct for other sessions")])),
+                    ("sex", OrderedDict([
+                        ("Description", "self-rated by participant, M for male/F for "
+                            "female (TODO: verify)")])),
+                    ("group", OrderedDict([
+                        ("Description", "(TODO: adjust - by default everyone is in "
+                            "control group)")])),
+                ]),
+                sort_keys=False,
+                indent=2)
     # Add a new participant
     with open(participants_tsv, 'a') as f:
         f.write(
@@ -311,7 +332,8 @@ def save_scans_key(item, bids_files):
 
 def add_rows_to_scans_keys_file(fn, newrows):
     """
-    Add new rows to file fn for scans key filename
+    Add new rows to file fn for scans key filename and generate accompanying json
+    descriptor to make BIDS validator happy.
 
     Parameters
     ----------
@@ -334,6 +356,25 @@ def add_rows_to_scans_keys_file(fn, newrows):
         os.unlink(fn)
     else:
         fnames2info = newrows
+        # Populate _scans.json (an optional file to describe column names in
+        # _scans.tsv). This auto generation will make BIDS-validator happy.
+        scans_json = '.'.join(fn.split('.')[:-1] + ['json'])
+        if not op.lexists(scans_json):
+            save_json(scans_json,
+                OrderedDict([
+                    ("filename", OrderedDict([
+                        ("Description", "Name of the nifti file")])),
+                    ("acq_time", OrderedDict([
+                        ("LongName", "Acquisition time"),
+                        ("Description", "Acquisition time of the particular scan")])),
+                    ("operator", OrderedDict([
+                        ("Description", "Name of the operator")])),
+                    ("randstr", OrderedDict([
+                        ("LongName", "Random string"),
+                        ("Description", "md5 hash of UIDs")])),
+                ]),
+                sort_keys=False,
+                indent=2)
 
     header = ['filename', 'acq_time', 'operator', 'randstr']
     # prepare all the data rows

Generate participants.json to accompany .tsv where fields are described
ATM we are generating `participants.tsv` with columns age, sex, group. bids-validator then whines
```
./participants.tsv
     Evidence: Columns: age, sex, group not defined, please define in: /participants.json
```
We should then create/define something like
```json
{
  "participant_id": {
    "Description": "participant id"
  },
  "age": {
    "Description": "Age in years (TODO - verify) as in the initial session, might not be correct for other sessions"
  },
  "sex": {
    "Description": "self-rated by participant, M for male/F for female (TODO: verify)"
  },
  "group": {
    "Description": "(TODO: adjust - by default everyone is in control group)"
  }

}
```
diff --git a/heudiconv/tests/test_heuristics.py b/heudiconv/tests/test_heuristics.py
index c9485c6..f36bbb4 100644
--- a/heudiconv/tests/test_heuristics.py
+++ b/heudiconv/tests/test_heuristics.py
@@ -165,7 +165,13 @@ def test_notop(tmpdir, bidsoptions):
     runner(args)
 
     assert op.exists(pjoin(tmppath, 'Halchenko/Yarik/950_bids_test4'))
-    for fname in ['CHANGES', 'dataset_description.json', 'participants.tsv', 'README']:
+    for fname in [
+        'CHANGES',
+        'dataset_description.json',
+        'participants.tsv',
+        'README',
+        'participants.json'
+    ]:
         if 'notop' in bidsoptions:
             assert not op.exists(pjoin(tmppath, 'Halchenko/Yarik/950_bids_test4', fname))
         else:
diff --git a/heudiconv/tests/test_main.py b/heudiconv/tests/test_main.py
index 7dcd32e..f4b7700 100644
--- a/heudiconv/tests/test_main.py
+++ b/heudiconv/tests/test_main.py
@@ -22,6 +22,7 @@ from mock import patch
 from os.path import join as opj
 from six.moves import StringIO
 import stat
+import os.path as op
 
 
 @patch('sys.stdout', new_callable=StringIO)
@@ -205,6 +206,7 @@ def test_add_rows_to_scans_keys_file(tmpdir):
         assert dates == sorted(dates)
 
     _check_rows(fn, rows)
+    assert op.exists(opj(tmpdir.strpath, 'file.json'))
     # add a new one
     extra_rows = {
         'a_new_file.nii.gz': ['2016adsfasd23', '', 'fasadfasdf'],

pip install -e .[all]
parse_log_pytest
requirements.txt
apt-get update apt-get install -y gcc dcm2niix
3.6
requirements.txt
pytest --no-header -rA --tb=line --color=no -p no:cacheprovider -W ignore::DeprecationWarning
annexremote==1.6.6
appdirs==1.4.4
attrs==22.2.0
boto==2.49.0
certifi==2021.5.30
cffi==1.15.1
chardet==5.0.0
charset-normalizer==2.0.12
ci-info==0.2.0
click==8.0.4
cryptography==40.0.2
datalad==0.15.6
dcmstack==0.9.0
decorator==4.4.2
Deprecated==1.2.18
etelemetry==0.2.2
fasteners==0.19
filelock==3.4.1
-e git+https://github.com/nipy/heudiconv.git@fe0f2c89b96f6ee7f63d44ed3b19f004ba977c56#egg=heudiconv
humanize==3.14.0
idna==3.10
importlib-metadata==4.8.3
importlib-resources==5.4.0
iniconfig==1.1.1
inotify==0.2.10
iso8601==1.1.0
isodate==0.6.1
jeepney==0.7.1
keyring==23.4.1
keyrings.alt==4.1.0
lxml==5.3.1
mock==5.2.0
msgpack==1.0.5
networkx==2.5.1
nibabel==3.2.2
nipype==1.7.1
nose==1.3.7
numpy==1.19.5
packaging==21.3
pathlib==1.0.1
patool==1.12
pluggy==1.0.0
prov==2.0.1
py==1.11.0
pycparser==2.21
pydicom==2.3.1
pydot==1.4.2
PyGithub==1.56
PyJWT==2.4.0
PyNaCl==1.5.0
pyparsing==3.1.4
pytest==7.0.1
python-dateutil==2.9.0.post0
python-gitlab==2.10.1
rdflib==5.0.0
requests==2.27.1
requests-toolbelt==1.0.0
scipy==1.5.4
SecretStorage==3.3.3
simplejson==3.20.1
six==1.17.0
swebench-matterhorn @ file:///swebench_matterhorn
tinydb==4.7.0
tomli==1.2.3
tqdm==4.64.1
traits==6.4.1
typing_extensions==4.1.1
urllib3==1.26.20
Whoosh==2.7.4
wrapt==1.16.0
zipp==3.6.0

name: heudiconv
channels:
  - defaults
  - https://repo.anaconda.com/pkgs/main
  - https://repo.anaconda.com/pkgs/r
  - conda-forge
dependencies:
  - _libgcc_mutex=0.1=main
  - _openmp_mutex=5.1=1_gnu
  - ca-certificates=2025.2.25=h06a4308_0
  - certifi=2021.5.30=py36h06a4308_0
  - ld_impl_linux-64=2.40=h12ee557_0
  - libffi=3.3=he6710b0_2
  - libgcc-ng=11.2.0=h1234567_1
  - libgomp=11.2.0=h1234567_1
  - libstdcxx-ng=11.2.0=h1234567_1
  - ncurses=6.4=h6a678d5_0
  - openssl=1.1.1w=h7f8727e_0
  - pip=21.2.2=py36h06a4308_0
  - python=3.6.13=h12debd9_1
  - readline=8.2=h5eee18b_0
  - setuptools=58.0.4=py36h06a4308_0
  - sqlite=3.45.3=h5eee18b_0
  - tk=8.6.14=h39e8969_0
  - wheel=0.37.1=pyhd3eb1b0_0
  - xz=5.6.4=h5eee18b_1
  - zlib=1.2.13=h5eee18b_1
  - pip:
      - annexremote==1.6.6
      - appdirs==1.4.4
      - attrs==22.2.0
      - boto==2.49.0
      - cffi==1.15.1
      - chardet==5.0.0
      - charset-normalizer==2.0.12
      - ci-info==0.2.0
      - click==8.0.4
      - cryptography==40.0.2
      - datalad==0.15.6
      - dcmstack==0.9.0
      - decorator==4.4.2
      - deprecated==1.2.18
      - etelemetry==0.2.2
      - fasteners==0.19
      - filelock==3.4.1
      - humanize==3.14.0
      - idna==3.10
      - importlib-metadata==4.8.3
      - importlib-resources==5.4.0
      - iniconfig==1.1.1
      - inotify==0.2.10
      - iso8601==1.1.0
      - isodate==0.6.1
      - jeepney==0.7.1
      - keyring==23.4.1
      - keyrings-alt==4.1.0
      - lxml==5.3.1
      - mock==5.2.0
      - msgpack==1.0.5
      - networkx==2.5.1
      - nibabel==3.2.2
      - nipype==1.7.1
      - nose==1.3.7
      - numpy==1.19.5
      - packaging==21.3
      - pathlib==1.0.1
      - patool==1.12
      - pluggy==1.0.0
      - prov==2.0.1
      - py==1.11.0
      - pycparser==2.21
      - pydicom==2.3.1
      - pydot==1.4.2
      - pygithub==1.56
      - pyjwt==2.4.0
      - pynacl==1.5.0
      - pyparsing==3.1.4
      - pytest==7.0.1
      - python-dateutil==2.9.0.post0
      - python-gitlab==2.10.1
      - rdflib==5.0.0
      - requests==2.27.1
      - requests-toolbelt==1.0.0
      - scipy==1.5.4
      - secretstorage==3.3.3
      - simplejson==3.20.1
      - six==1.17.0
      - swebench-matterhorn==0.0.0
      - tinydb==4.7.0
      - tomli==1.2.3
      - tqdm==4.64.1
      - traits==6.4.1
      - typing-extensions==4.1.1
      - urllib3==1.26.20
      - whoosh==2.7.4
      - wrapt==1.16.0
      - zipp==3.6.0
prefix: /opt/conda/envs/heudiconv

heudiconv/tests/test_heuristics.py::test_notop[bidsoptions1] heudiconv/tests/test_main.py::test_add_rows_to_scans_keys_file
heudiconv/tests/test_heuristics.py::test_reproin_largely_smoke[--files heudiconv/tests/test_heuristics.py::test_reproin_largely_smoke[-d heudiconv/tests/test_main.py::test_prepare_for_datalad
heudiconv/tests/test_heuristics.py::test_smoke_convertall heudiconv/tests/test_heuristics.py::test_scans_keys_reproin[--files heudiconv/tests/test_heuristics.py::test_ls heudiconv/tests/test_heuristics.py::test_scout_conversion heudiconv/tests/test_heuristics.py::test_notop[bidsoptions0] heudiconv/tests/test_main.py::test_main_help heudiconv/tests/test_main.py::test_main_version heudiconv/tests/test_main.py::test_create_file_if_missing heudiconv/tests/test_main.py::test_populate_bids_templates heudiconv/tests/test_main.py::test_add_participant_record heudiconv/tests/test_main.py::test_get_formatted_scans_key_row heudiconv/tests/test_main.py::test__find_subj_ses heudiconv/tests/test_main.py::test_make_readonly heudiconv/tests/test_main.py::test_cache
heudiconv/bids.py
heudiconv/bids.py