# Data contract

All four datasets are shared/global and contain no user, project, series, book, character or alias ownership.

## GivenNames

`given_name_key` is the immutable import identity (`gn_elizabeth`); database implementations may additionally use an integer surrogate PK. `display_name` preserves spelling. `normalised_name` is the lookup value. `name_type` is one of `Canonical`, `Independent`, `Diminutive`, `Nickname`, or `Variant`. `is_word_ambiguous` asks parsers to require stronger context. `is_active` supports non-destructive correction.

## NameRelationships

`relationship_key` is immutable import identity. `from_given_name_key` and `to_given_name_key` reference GivenNames. `relationship_type` is one of `ShortForm`, `Diminutive`, `Nickname`, `SpellingVariant`, `AlternativeForm`, or `AnglicisedForm`. `strength` describes confidence in the linguistic relationship, not confidence that two manuscript mentions identify one character. `is_bidirectional` controls graph traversal. `curation_source` preserves provenance.

## NameUsages

Each row covers one recognised form, one locale and one inclusive birth-year range. `male_weight` + `female_weight` equals 1.0 within tolerance. These are gender priors. `usage_weight` is relative recognisability within a locale/era and is suitable for ranking, not as an absolute population probability. `confidence` describes evidential confidence. `source_type` separates direct statistical derivation from blended estimates.

Lookup precedence: known birth year → estimated birth year → story year fallback → nearest band. Use exact locale first. Do not silently treat US evidence as another locale’s direct statistic.

## NameLocales

Supported codes: `en-GB`, `en-IE`, `en-US`, `en-CA`, `en-AU`, `en-NZ`. `evidence_basis` and `default_confidence` make limitations visible.

## Recommended constraints

- Unique stable keys in every table.
- Unique Unicode-aware `GivenNames.NormalisedName` under an explicitly chosen collation.
- Unique active `(FromNameId, ToNameId, RelationshipType)`.
- Unique active `(GivenNameId, LocaleId, BirthYearFrom, BirthYearTo)`.
- All weights/confidence in `[0,1]`; gender weights sum to 1 within `0.0002`.
- Ordered, non-overlapping usage bands.
- Reference tables read-only to ordinary users.