How I Validate an Evidence-Backed YAML Catalog Contribution Before Opening a Pull Request

Structured data contributions look simple: add one YAML file, open a pull request, and wait for green checks. The difficult part is proving that every fact belongs in the catalog, matches an authoritative source, fits the data model, and does not duplicate work already in progress.

I used the workflow below while preparing a Memori entity record for the Sourcey startup credits catalog. The method kept a small change reviewable and stopped unsupported claims from hiding inside structurally valid YAML.

1. Read the repository as a contract

Before collecting data, I read CONTRIBUTING.md, a nearby accepted entity file, and the pull request template. The guide defines policy and evidence boundaries. The record shows the current shape. The template reveals what I must certify later.

I wrote down the repository-specific constraints before editing:

• The filename and directory are derived from the entity slug.
• A data pull request should contain only catalog data.
• IDs must be fresh where required and stable after publication.
• Categories must come from the verifier's pinned taxonomy.
• Every factual offer field must be supported by a cited canonical source.
• Commits must include a Developer Certificate of Origin sign-off.

2. Establish the source of truth

For a vendor-run offer, I treat the vendor's own website as the primary source. Directories, social posts, and aggregators can help locate a page, but convenient wording does not make them evidence.

I captured the canonical URL first, then drafted from it. Writing the desired record first and hunting for support later makes it easy to preserve assumptions the source never made.

For each candidate field, I asked:

1. Who controls this fact?
2. Is the cited page published by that party?
3. Does the page support the exact value, actor, duration, eligibility rule, and access method?
4. Is the statement current, or am I relying on an old announcement?

If a field failed, I removed it, modeled it as manual where allowed, or found a better first-party page.

3. Search for duplicates before reserving work

A clean file is still a bad contribution if another record or pull request covers the same entity. I searched the repository, open pull requests, and missing-record issues by company name, domain, slug, and program name.

Locally, a quick first pass looked like this:

rg -ni 'memori|memorilabs\.ai' entities

Remote search matters because an unmerged branch is absent from the default branch. I also follow the repository's reservation process before substantial work. This avoids duplicate effort without pretending a local draft was accepted.

4. Preserve exact source fidelity

Source fidelity does not require copying marketing prose word for word. It requires preserving the meaning and scope of the published fact.

For example, a neutral summary may shorten a three-month offer for qualifying startups, but it must not broaden "qualifying" to "all," make the benefit ongoing, or invent approval.

I compare the final YAML against the source field by field, not paragraph by paragraph. Structured data separates concepts that a web page may combine:

• economics: what is included and for how long
• eligibility: who may apply
• access: where and how an application is submitted
• lifecycle: whether the offer is currently presented as active
• roles: who grants or operates the offer

This pass catches prose that sounds reasonable but is more specific than the evidence.

5. Validate structure with the repository's own tooling

Generic YAML linting only proves that a parser can read the file. It cannot prove that IDs are unique, references close, categories exist, paths match slugs, or the record satisfies current repository rules.

I used the verifier and taxonomy pinned by the repository. Its documented preflight validates the changed dependency closure against the merge base. That is safer than guessing commands or copying stale CI steps.

When validation fails, I fix the smallest incorrect field and rerun the full preflight. Passing still does not prove the facts are true. It only proves the tree satisfies that check's deterministic rules.

6. Enforce one-file scope

Catalog changes are easier to audit when the diff contains exactly the intended record. Before committing, I inspect both the file list and the patch:

git diff --name-only origin/main...HEAD
git diff --stat origin/main...HEAD
git diff origin/main...HEAD

The intended result was one entity YAML file. Documentation, generated output, dependency changes, and temporary evidence did not belong. Keeping them out reduced review work and unrelated side effects.

7. Check DCO before pushing

A correct contribution can still fail if its commit lacks the required sign-off. I check it directly:

git log -1 --format=%B | rg '^Signed-off-by:'

If it is missing, git commit --amend --no-edit --signoff adds it. For a pushed branch, git push --force-with-lease avoids overwriting unexpected remote work.

The DCO line certifies that the contribution can be submitted under the project's terms.

8. Run an overclaim check

My final content review uses an adversarial question: "What would a skeptical reviewer say this sentence promises?"

I flag "guaranteed," "verified," "official," "unlimited," "free," and "available" unless the source and schema support their exact meaning. I also check numbers, dates, thresholds, plan names, and included services.

I never add repository verification, provenance, freshness, or signature claims to vendor facts. The catalog pipeline must derive those properties.

9. Create immutable review evidence

A branch URL changes after a push, and automated reviewers may not extract files from a dynamic pull request page. I record links tied to the commit SHA:

https://raw.githubusercontent.com/OWNER/REPO/COMMIT_SHA/path/to/record.yaml
https://github.com/OWNER/REPO/commit/COMMIT_SHA
https://github.com/OWNER/REPO/pull/NUMBER.patch

These links expose the exact bytes evaluated. They do not prove acceptance, merge, or publication. Local validation, CI success, approval, merge, and live publication remain separate events.

A compact pre-PR checklist

Before I open a data pull request, I now require all of the following:

• canonical sources are saved and publicly reachable
• existing records, issues, and open pull requests were searched
• every factual field is traceable to a source
• unsupported specificity was removed
• the repository's pinned verifier passes
• the diff contains only the intended data file
• the commit has a DCO sign-off
• immutable commit and raw-file links can be produced after push

The main lesson is simple: a green YAML parser is the beginning of validation, not the end. Evidence-backed catalog work is a small exercise in data modeling, source criticism, and change control. Doing those checks before opening the pull request makes the contribution faster to review and much easier to trust.