Validate Contribution
Testing & Qualityvalidate-contributionValidate Contribution is an Agent Skill for testing & quality published in the dr5hn/countries-states-cities-database repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Validate geographic data contributions against the CSC database schema. Use this skill whenever you encounter a PR that adds, modifies, or deletes data in the contributions/ directory. Trigger on: validate, check, review, verify, audit, inspect, or assess any data contribution, PR review requests, schema compliance checks, field validation, or when someone says "is this correct", "check my data", "validate this", or "review my PR". Also use when asked about required fields, allowed values, or data format rules. Read schema-rules.md in this directory for the complete field specification.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/dr5hn/countries-states-cities-database/blob/HEAD/.github/skills/validate-contribution/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/validate-contribution, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Validation Process
When validating a contribution, follow these steps in order:
Step 1: Identify the Entity Type
Determine whether the contribution is for cities, states, or countries based on the file path or content structure.
Step 2: Check for Auto-Managed Fields
The following fields must NOT be present in contributions (they are auto-managed):
idcreated_atupdated_atflag
If any are present, flag as an error and instruct the contributor to remove them.
Step 3: Validate Required Fields
Read the schema-rules.md file in this skill's directory for the complete field specifications, constraints, and example records per entity type. Use it as the authoritative reference for all field validation.
Cities require: name, state_id, state_code, country_id, country_code, latitude, longitude
States require: name, country_id, country_code
Countries require: name
Step 4: Validate Field Formats
country_code: must be exactly 2 uppercase letters (ISO 3166-1 alpha-2)latitude: must be a decimal number between -90 and 90longitude: must be a decimal number between -180 and 180name: must be non-empty, max 255 characters (100 for countries)wikiDataId: must match pattern Q followed by digits (e.g., Q65)state_id,country_id: must be positive integers
Step 5: Cross-Reference Validation
- Load the existing
countries.jsonandstates.jsonfiles - Verify
country_idexists in the countries data - Verify
country_codematches the ISO2 code of the referenced country - For cities: verify
state_idexists in states data AND belongs to the specified country - For cities: verify
state_codematches the code of the referenced state
Step 6: Coordinate Plausibility
- Check that coordinates are within the geographic bounds of the specified country
- Flag coordinates that fall outside the country (may be valid for border cities)
Step 7: Duplicate Detection
- Check for existing entries with the same name in the same state/country
- Check for entries within 5km of the new coordinates
- Report potential duplicates as warnings (they may be legitimate)
Output Format
Present results as a clear validation checklist:
### Validation Results for [filename]
**Schema Compliance:**
- [PASS/FAIL] Required fields present
- [PASS/FAIL] No auto-managed fields included
- [PASS/FAIL] Field formats valid
**Cross-References:**
- [PASS/FAIL] country_id [X] exists ([country name])
- [PASS/FAIL] country_code "[XX]" matches country_id
- [PASS/FAIL] state_id [X] exists ([state name])
- [PASS/FAIL] state_code "[XX]" matches state_id
**Data Quality:**
- [PASS/WARN] Coordinates within country bounds
- [PASS/WARN] No duplicates detected
**Overall: [PASS / NEEDS CHANGES]**