Add DwC-DP event occurrence export

documentation/functionality/dwc_data_package.md

@@ -0,0 +1,75 @@
+# Darwin Core Data Package export (v1, admin-only)
+
+Issue: `nowcommunity/nowdatabase#1150`
+
+This repository includes an **admin-only** Darwin Core Data Package (DwC-DP) test export for relational locality and occurrence data.
+
+DwC-DP is intentionally published as a separate format from the existing DwC-A exports. The taxon trait-heavy `com_species` export remains a DwC-A `Taxon` core with `MeasurementOrFact`, because those traits are synthesized at taxon level rather than linked to specimen/material source entities.
+
+## Access
+
+- Backend route: `GET /occurrence/export/dwc-data-package` (**Role.Admin only**)
+- The frontend exposes this as an export option on the cross-search occurrence table for administrators.
+
+## Output
+
+The downloaded ZIP contains:
+
+- `datapackage.json` (Frictionless Data Package descriptor with table schemas and foreign keys)
+- `event.csv` (DwC-DP Event rows derived from `now_loc`)
+- `geological-context.csv` (geological context rows referenced from `event.csv`)
+- `occurrence.csv` (DwC-DP Occurrence rows derived from `now_ls`)
+- `event-assertion.csv` (locality-level facts formerly expressed as locality `MeasurementOrFact`)
+- `occurrence-assertion.csv` (occurrence-level facts formerly expressed as occurrence `MeasurementOrFact`)
+- `eml.xml` (minimal placeholder EML metadata)
+
+## Model
+
+### `event.csv`
+
+One row per `now_loc` record.
+
+Key mappings:
+
+- `eventID` = `NOW:EVENT:<lid>`
+- `eventType` = `paleontological locality`
+- `locationID` = `NOW:LOC:<lid>`
+- locality, geography, coordinates, elevation, and remarks map from the corresponding locality fields
+- `geologicalContextID` = `NOW:GEO:<lid>`
+
+### `geological-context.csv`
+
+One row per locality geological context.
+
+Key mappings:
+
+- `geologicalContextID` = `NOW:GEO:<lid>`
+- stratigraphic terms map from `chron`, `lgroup`, `formation`, `member`, and `bed`
+- earliest/latest stage terms map from `bfa_max` / `bfa_min`, using related time-unit display names when available
+
+### `occurrence.csv`
+
+One row per `now_ls` record.
+
+Key mappings:
+
+- `occurrenceID` = `NOW:OCC:<lid>:<species_id>`
+- `eventID` = `NOW:EVENT:<lid>`
+- `taxonID` = `NOW:<species_id>`
+- `scientificName` follows the existing occurrence DwC-A mapping
+- `identificationVerificationStatus` maps from `id_status`
+
+### Assertion Tables
+
+The assertion tables preserve the non-core facts without overloading one DwC-A `measurementorfact.csv` across multiple entity types.
+
+- `event-assertion.csv` uses `eventID` and contains locality-level facts from `now_loc` and related locality lists.
+- `occurrence-assertion.csv` uses `occurrenceID` and contains occurrence-level facts from `now_ls`.
+
+The original database field name is preserved in `verbatimAssertionType`.
+
+## Relationship To Existing DwC-A Exports
+
+- Keep species traits as DwC-A `Taxon` + `MeasurementOrFact`.
+- Keep locality and occurrence DwC-A exports available for current test users.
+- Prefer this DwC-DP export for relational event/locality/geology/occurrence data because it avoids the DwC-A one-core star-schema limitation.