OpenSyria Data Geography

OpenSyria Data Geography is the canonical repository for public, non-personal Syrian administrative geography data.

This repository publishes versioned release artifacts consumed by datasets-api. It is focused on stable reference data, not live maps or operational/security information.

Table of Contents

• Scope
• Current Status
• Repository Layout
• Data Workflow
• Commands
• Maintainer Tooling
• Contribution Model
• Source Policy
• Public Documentation
• License

Scope

Geography coverage includes:

• governorates,
• districts,
• subdistricts,
• cities,
• towns,
• villages,
• localities.

Out of scope:

• personal data,
• private addresses,
• checkpoints,
• military/security locations,
• surveillance-related data,
• unsourced political claims,
• proprietary map data,
• data that cannot be legally redistributed.

Current Status

The latest public release is v0.1.4. The first public seed release was v0.1.0.

Current released coverage:

Dataset	Records
Governorates	14
Districts	62
Subdistricts	272
Localities	7,605

The release generator currently produces artifacts for:

governorates
districts
subdistricts
localities

in JSON, NDJSON, CSV, SQL, YAML, and XML formats.

The released data is source-backed and maintainer-reviewed. Public records include sourceIds, dated sourceReferences, and sourceStatus so API and artifact consumers can inspect provenance consistently across OpenSyria datasets. Known gaps are tracked in the data quality and currency documents, and improvements should be made through source-backed follow-up releases.

Repository Layout

data/
  governorates.json
  districts.json
  subdistricts.json
  localities.json
  sources.json
schemas/
  README.md
  sources.schema.json
  governorates.schema.json
  districts.schema.json
  subdistricts.schema.json
  localities.schema.json
  release-manifest.schema.json
scripts/
  validate-data.mjs
  validate-schemas.mjs
  validate-imports.mjs
  build-release.mjs
  report-data.mjs
  analyze-coverage.mjs
  match-locality-geonames.mjs
imports/
  README.md
  manifests/
examples/
  *.example.json
fixtures/
  valid-data/
docs/
  DATA_SCHEMA.md
  COVERAGE_ANALYSIS.md
  DATA_QUALITY.md
  FIELD_REFERENCE.md
  GENERATED_ARTIFACTS.md
  ID_POLICY.md
  IMPORT_WORKFLOW.md
  PRE_SEED_CHECKLIST.md
  RELEASE_CHECKLIST.md
  REVIEW_PROCESS.md
  SEED_PLAN.md
  SOURCE_DECISIONS.md
  SOURCES.md
contributions/
  README.md

Data Workflow

1. Edit canonical files under data/.
2. Run validation.
3. Build release artifacts.
4. Publish a GitHub Release with:
   • release-manifest.json
   • files under artifacts/

Examples live under examples/. Machine-validated fake fixture data lives under fixtures/valid-data/.

Commands

corepack enable pnpm
pnpm install
pnpm run validate
pnpm run validate:schemas
pnpm run validate:imports
pnpm run release:prepare -- --version v0.1.3
pnpm run release:build
pnpm run report:data
pnpm run coverage:data
pnpm run match:geonames-localities -- --max-distance-km=5
pnpm run validate:fixtures
pnpm run release:build:fixtures

Generated release files are written to:

dist/release/

Generated artifacts are built from canonical JSON files and must not be edited directly. See docs/GENERATED_ARTIFACTS.md.

Coverage analysis files are written to:

dist/coverage/

Use docs/COVERAGE_ANALYSIS.md to identify missing fields, parent hierarchy gaps, and focused contribution targets.

Maintainer Tooling

This repository uses:

• Biome for formatting and checks,
• Husky for local Git hooks,
• lint-staged for staged-file checks,
• commitlint for Conventional Commit messages.

Hooks run lightweight checks before commits. CI still runs the full validation workflow.

Contribution Model

Contributions are limited to improving approved datasets:

• fixing incorrect values,
• adding missing records,
• improving names, aliases, translations, and transliterations,
• improving source attribution,
• correcting administrative relationships,
• correcting coordinates when the schema already supports coordinates.

New fields, new dataset topics, ID format changes, validation changes, and release pipeline changes require a maintainer-approved schema proposal first.

See CONTRIBUTING.md.

Detailed contributor workflow lives in contributions/README.md.

For a normal data pull request:

1. Read CONTRIBUTING.md and contributions/README.md.
2. Edit only the relevant canonical files under data/ unless a maintainer approved broader work.
3. Check docs/FIELD_REFERENCE.md, docs/ID_POLICY.md, and docs/SOURCES.md.
4. Run pnpm run validate.
5. Explain the changed files, source IDs, source URLs, and any uncertainty in the pull request.

Maintainer workflow and review references:

• docs/PRE_SEED_CHECKLIST.md
• docs/SEED_PLAN.md
• docs/IMPORT_WORKFLOW.md
• docs/COVERAGE_ANALYSIS.md
• docs/DATA_QUALITY.md
• docs/ID_POLICY.md
• docs/SOURCE_DECISIONS.md
• docs/releases.md
• docs/RELEASE_CHECKLIST.md

Source Policy

Every record should be traceable to reusable sources.

Preferred seed sources include:

• geoBoundaries for administrative boundaries,
• GeoNames for place names and feature references,
• Wikidata for public identifiers and cross-checking.

OpenStreetMap data is useful, but OSM-derived data has ODbL share-alike requirements. It should not be mixed into the default CC BY release unless the maintainer explicitly approves the licensing approach.

See docs/SOURCES.md.

Maintainer review rules live in docs/REVIEW_PROCESS.md.

Public Documentation

• Contribution guide
• Detailed contribution workflow
• Review process
• Data schema
• Field reference
• ID policy
• Source policy
• Source decisions
• Data quality
• Data currency
• Coverage analysis
• Generated artifacts
• Import workflow
• Release process
• Release checklist
• Support
• Security policy
• Code of conduct

License

See LICENSE.md.