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):

• id
• created_at
• updated_at
• flag

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 90
• longitude: must be a decimal number between -180 and 180
• name: 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.json and states.json files
• Verify country_id exists in the countries data
• Verify country_code matches the ISO2 code of the referenced country
• For cities: verify state_id exists in states data AND belongs to the specified country
• For cities: verify state_code matches 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]**