Home /Modules/docs/CSPML.DATA.SOURCE.AND.SALT-AND-SALARY.REFERENCE.md

CSPML.DATA.SOURCE.AND.SALT-AND-SALARY.REFERENCE.md

docs/reference/CSPML.DATA.SOURCE.AND.SALT-AND-SALARY.REFERENCE.md · 170 line(s) · markdown

<img align="right" src="../../images/sleela/sleela-medium-profile-permanent-icon-002.jpg" width="45" height="45" alt="SLeeLa">

CSPML Data Source Reference and Salt & Salary Research Framework

Document class: Cross-repository data-source and research reference Maintained by: SLeeLa project Primary external data source: CSPML — City System Planning Markup Language Primary dataset: USA Cities XML Loads Source branch: master Status: Reference and integration guidance; not a claim that a live connector or automated import is already implemented.


1. Purpose

This document establishes CSPML as a recognized external data source for work performed in the SLeeLa repository. It also defines how CSPML may support the Salt & Salary research and application work: place-based economic context, compensation research, household resources, education, labor-market context, and the relationship between essential commodities and the value of work.

SLeeLa is the software, language, runtime, and application environment. CSPML is a separately maintained data project. The two repositories remain independently versioned and governed. A SLeeLa component may read, transform, validate, cache, or analyze CSPML data, but must preserve the identity and provenance of the source records.

CSPML is a private GitHub repository. Access requires an authorized GitHub account and repository permission. A link in this document is a reference, not a grant of access.

2. Authoritative repository references

ResourceReferenceIntended use
CSPML repositorymearvk/CSPMLProject identity, schemas, generators, workflows, and source documentation
U.S. place datasetusa-cities-xml-loadsNational, state, and individual Census-place records
Dataset READMEUSA Cities XML Loads READMERecord structure, measures, source vintages, generation, validation, and limitations
National indexindex.xmlState/covered-area navigation and national index
Public-school directoryeducation/usa-schools-by-state.xmlPublic elementary and secondary school directory by state
Place schemaschema/XML structure and validation contracts

The dataset README is the first stop for changes to the CSPML data model. Do not rely on a copied summary here when the current source README, schema, or XML record provides a more recent and precise definition.

3. What CSPML contributes

The USA Cities XML Loads dataset is organized around U.S. Census places rather than an informal assumption that every named place is an incorporated city. Its documented structure includes:

The source documentation describes 50-state research indicators and the broader place geography as including the District of Columbia and Puerto Rico where represented by the Census Gazetteer. Consumers must inspect the actual index and record coverage rather than assume every geography or field is populated.

Dataset counts are intentionally not frozen in this reference. Counts change as the generator and source data are refreshed; obtain current totals from the repository's indexes, validation output, and workflow artifacts.

4. Salt & Salary: intended research use

Salt & Salary is treated here as a research and application domain that connects the material conditions of places with the economic value and adequacy of work. CSPML can supply geographic and socioeconomic context for that work.

Potential analytical dimensions include:

  1. Place and population context — identify the relevant Census place, state, GEOID, population, and geographic classification.
  2. Household economic context — use median household income, poverty, housing values, and gross rent to describe the local economic setting.
  3. Workforce context — use civilian labor-force and unemployment measures as contextual indicators, retaining their published year, definition, and uncertainty.
  4. Education context — use educational-attainment measures and the separate public-school directory to describe local educational infrastructure. Do not treat school-directory presence as a direct measure of educational outcomes.
  5. Compensation context — compare a proposed or observed salary with local income and housing measures only after defining the comparison population, time period, household/person basis, and geographic match.
  6. Essential-goods context — use separately sourced and dated commodity-price or household-expenditure data when evaluating the cost of essential goods. CSPML does not, by itself, provide a complete historical or current salt-price series.
  7. Longitudinal comparison — align data vintages before comparing places or years; never imply that an ACS 5-year estimate is a point-in-time census count.

CSPML's median household income is not an individual salary, an average wage, or a guaranteed measure of disposable income. It must retain its original statistical meaning in every Salt & Salary output.

5. Salt and salary: historical and conceptual care

The words salt and salary are etymologically related through Latin sal and salarium. That relationship does not establish that Roman soldiers were routinely paid directly in physical salt. The popular direct-payment story is disputed and should not be presented as settled historical fact.

For Salt & Salary materials:

A useful secondary discussion of the historical claim is Peter Gainsford, “Salt and salary: were Roman soldiers paid in salt?”. Its central caution is that the familiar direct-salt-payment story is not demonstrated by the often-repeated Pliny quotation. A concise etymological overview with the same qualification is available at Wordorigins — “salary”. Consult primary texts and specialist scholarship before making a definitive historical assertion.

6. Data use, provenance, and attribution rules

Every CSPML-derived value used by SLeeLa or a Salt & Salary application should carry, directly or through a traceable record:

Preserve source values separately from derived values. Derived ratios, rankings, indexes, modeled values, and salary comparisons must identify their formula and inputs. Never overwrite an original source field with a calculated result.

When a value is absent, suppressed, stale, unmatched, or not supported by the source, represent it as unavailable (for example, N/A) with a reason where possible. Do not infer a value from a neighboring city, state average, school rating, or unrelated geographic unit.

7. Geographic matching and statistical boundaries

The Census place is the primary unit for place-level joins. Use GEOID as the stable key when available; do not join solely on a city name. Preserve state and place classification because identical names can occur in multiple states and because a Census-designated place is not necessarily an incorporated municipality.

For school records, use the school identifier and the documented school location. If a school is associated with a city-level measure, document the geographic crosswalk and whether the school point, mailing address, district, county, or another boundary was used. Do not imply that a school district and a Census place are equivalent.

For salary and labor comparisons, define whether the measure refers to an individual, worker, household, full-time worker, or all residents. A city median household income must not be relabeled as a local salary benchmark.

8. Integration guidance for SLeeLa

CSPML should be consumed as an external data source, not copied wholesale into the SLeeLa language or runtime repository.

A future or existing integration should follow these boundaries:

No live API, package dependency, automatic synchronization, or runtime binding is implied merely by this reference document. Such functionality requires a separately designed, implemented, and tested integration.

Use CSPML for the place-level demographic, household-income, housing, workforce, education, and public-school context described above. Supplement it with purpose-built sources for the questions CSPML does not answer.

Research questionPreferred source classHandling
Place identity and boundariesU.S. Census Gazetteer / CSPML place recordsPreserve GEOID and place type
Household income and povertyACS 5-year / CSPML fieldsPreserve estimate, year, and margin of error
Housing cost contextACS 5-year / CSPML fieldsKeep rent and owner value as separate measures
Labor force and unemploymentACS or official labor statisticsPreserve universe, period, and geography
Public-school identity and locationNCES CCD / CSPML school directoryDo not infer athletic class, SAT, or outcomes
Postsecondary institutionsNCES IPEDS or another authoritative directoryMatch institutions separately from resident attainment
Current wages and occupational payBLS and other authoritative labor datasetsMatch occupation, geography, period, and worker basis
Current prices and cost of essentialsOfficial price series or transparent local price observationsPreserve item definition, unit, date, and collection method
Historical salt economyPrimary historical records and specialist scholarshipKeep historical evidence distinct from modern statistics

10. Quality controls before publication

Before a Salt & Salary report or application publishes a CSPML-derived comparison:

11. Citation and implementation convention

When SLeeLa documentation, source code comments, reports, or Salt & Salary outputs rely on CSPML, cite the dataset as:

City System Planning Markup Language (CSPML), USA Cities XML Loads, mearvk/CSPML, master, dataset documentation. Record the specific source file, GEOID, source vintage, and commit or snapshot used.

For reproducible analysis, record the exact CSPML commit SHA in the output metadata. A branch URL is a navigation reference, not an immutable citation.

12. Maintenance

Update this document when the CSPML dataset layout, schemas, source vintages, school directory, or access model materially changes. The CSPML repository remains authoritative for its own data definitions and generation status. SLeeLa remains authoritative for its own parser, runtime, and integration behavior.

Principle: CSPML supplies traceable place-based evidence; SLeeLa supplies the tools to process it; Salt & Salary supplies a research context. None of these roles permits a source estimate to be silently redefined, a missing value to be invented, or a historical hypothesis to be reported as fact.