Broken Data Integrity due to Lack of Schema Validation

[ShubhamMalekar]

Problem: Profiles are stored in a flat JSON file without any schema enforcement. Contributors may push invalid data (e.g., wrong country codes, broken image links, inconsistent role formats). This silently breaks UI components.

Solution: Introduce a JSON Schema (AJV or Zod) for persons.json. Add pre-commit GitHub Action to validate PR data before merge. Ensure proper error messages for contributors.

[sophiabrandt]

That's an interesting idea. Have you thought about what to do with existing data that violates the constraints that you want to set?

Additionally, if we would implement this, how can we make it as easy as possible for the people who want to make a new entry? Let's say, I want to add a submission with my data and I write an incorrect country name. I can still make a pull request, but the proposed hook would only fire when a contributor wants to finally merge this PR, right?

Also, what do you mean with "role formats"? The job title? If so, the question again is: what to do with existing data? We already have hundreds of entries where people were able to fill in any text that they liked. What should happen with those entries?
Are you suggesting that we only allow a predefined set of job titles? If so, which ones? If so, how can we make this clear to the people who want to submit an entry?

[ShubhamMalekar]

Thanks for the feedback @sophiabrandt , really appreciate you pointing these things out

I was thinking about the same concerns and here’s how we could handle them without making it painful for contributors:

1. Existing data that doesn’t match constraints
   Instead of making the checks super strict from day one, we could start by just running validation in CI and showing warnings if entries don’t follow the schema. That way, nothing breaks immediately, but we can slowly clean up older data in separate PRs. Once most of the data is fixed, we could then make it stricter.

2. Making it easy for new contributors
   You’re right that the validation hook only fires on PRs. To help people catch issues earlier, we could add a simple script (npm run validate) that they can run locally before opening a PR. And maybe also update the CONTRIBUTING.md with examples and clear instructions (like “use ISO country codes” etc.). That should lower the friction.

3. Roles / job titles
   For roles, my idea wasn’t to force people into a rigid list (like only “Engineer” or “Founder”), but more about making the data consistent enough so that in the future it’s possible to filter/search better. One compromise could be:

Keep the role field free text as it is now.

Optionally provide a “recommended list” of common roles in the docs for guidance.

Or, if we want to structure it a bit more, we could allow a role (from a suggested set) and a customRole field where people can write anything. That way it stays flexible.

4. Incremental approach
   Basically, I see this as something we introduce step by step. Start with validating just the most important fields (like name, country, image URL), while keeping roles flexible. Later, once we’ve stabilized the data, we can tighten the rules gradually.

[sophiabrandt]

Let me ask a follow-up question:

Existing data that doesn't match constraints
[...] That way, nothing breaks immediately, but we can slowly clean up older data in separate PRs. Once most of the data is fixed, we could then make it stricter.

I am unsure on how the cleanup will work. As you have noted, there are already hundreds of submissions and I don't think that the maintainers can take the burden of cleaning all those submissions or trying to coordinate the effort of contacting the original submitters to fix their entries.

As a nuclear option, we could remove all invalid submissions, but I am a bit wary about that, as it seems a bit extreme.

Generally, I want to balance the effort of cleaning up the validation/schema with how much manual/extra work this requires for maintainers (as we are all volunteers) while not alienating folks who might be programming beginners that wish to submit their entry.

[MattCSmith]

I actually really like the idea. I think it would be great to add some validation. Here are some of my thoughts:

• I think having the validation failure appear in the PR checks is fine, we can update the contribution guide for them to check they pass all checks. If the checks fail we can't merge it. I think we do this for the CSS Hacktoberfest project right?

As a nuclear option, we could remove all invalid submissions, but I am a bit wary about that, as it seems a bit extreme.

Is there something simple we can do to find out how many broken submissions there are. I'm wondering if:

• We can publish a list of broken records that other contributors can address.
• Add some fallbacks, so broken images replaced with a default image.

Job Roles

For the job roles I am wondering if it would make sense to provide a default list of job roles, list them in the contrib file, so that users can select one. For submissions that don't use one of these, either previous or future submissions, they get displayed under an "Other" tab. This way, we aren't stopping people from using a custom role, they jus wont be display under a filter and will make it easier to update the current submissions.

[ShubhamMalekar]

Thanks a lot for raising those concerns @sophiabrandt — I completely get where you’re coming from. The last thing I’d want is to create extra work for maintainers or make the project less welcoming for beginners.

On the cleanup side, my thought wasn’t to put that burden on maintainers at all. A few alternatives we could try:

Community-driven cleanup: We could open a “good first issue” (like Schema Cleanup: Country Codes or Fix broken images), and let contributors pick them up gradually. This way, newcomers can still get involved without needing deep coding skills.

Incremental CI warnings: Instead of blocking invalid data right away, CI could just flag them as warnings (e.g., “⚠️ Country not ISO formatted”). This gives visibility without forcing an immediate fix. Over time, contributors who touch those entries anyway can fix them as part of their PRs.

Migration scripts: For the more mechanical fixes (e.g., converting “USA” → “US”), we could write a simple script to auto-normalize some fields. That would reduce the number of entries that need human attention.

This way, the cleanup happens organically and bit by bit, without requiring maintainers to manually chase down old entries or make a “nuclear” cut.

For new submissions, the schema validation + CONTRIBUTING guide would act as a safeguard, so the “bad” data problem doesn’t keep growing. Over time, the dataset should get cleaner with almost no extra overhead for maintainers.

Do you think a phased, contributor-led cleanup like this would be acceptable?

[ShubhamMalekar]

Thanks a lot for the feedback! @MattCSmith
I agree that failing the PR check is a good balance — it keeps things clean without burdening maintainers. For the existing broken records, I love the idea of publishing a list that contributors can gradually fix, and having fallbacks like a default image makes the UI more resilient in the meantime.

For roles, the “default list + Other” approach sounds perfect. It gives us structure for filtering without taking away flexibility. I think that would work really well.