Status: Planned (B5 provider/data-source slice)
Updated: May 30, 2026
Official source summary
- Program: National Gallery of Art Open Data Program
- Dataset form: CSV (UTF-8), updated frequently (typically daily)
- Scale: 130,000+ artworks and artists
- License: CC0 (dataset factual records)
- Distribution: downloadable from NGA-linked GitHub dataset repo
Key constraints (from official program text)
- Open data package includes factual collection data records.
- Images/media binaries are not included in the dataset package.
- Dataset may include links/references to media and related resources.
- Data is “as is” and continuously changing (daily refresh cadence).
- Wikidata QIDs are included when known, but are not exhaustive.
- Attribution/citation is requested for research usage.
- Do not use NGA logo or imply endorsement without permission.
Integration goals
- Treat NGA as a first-class provider source in B5 with CSV-first ingest.
- Preserve raw source fields in `_source.raw` and map stable Linked Art boundary fields.
- Use Wikidata IDs as reconciliation hints in B6 authority-cache flows.
- Keep image/reuse semantics conservative unless rights and open access status are explicit per object.
Proposed implementation slice
Adapter
- `src/adapters/nga.ts`
- profile descriptor
- CSV row-to-record mapper
- optional object-link enrichment using dataset-provided URLs
- normalization to `SourceRecord` + `Artwork` DTO boundary
Routes
- `GET /api/nga/profile`
- `POST /api/nga/search` (search over imported/indexed NGA rows in app storage)
- `POST /api/nga/import` (CSV row batch ingest)
- optional `POST /api/nga/refresh` (manual refresh trigger for local dev)
UI
- add `nga` source toggle in `/explore`
- show citation + source attribution + open data context in detail surfaces
Env configuration
- `NGA_DATASET_URL` (CSV export URL or local mirrored feed URL)
- `NGA_REFRESH_MODE` (`manual` default, `scheduled` in later ops slice)
- `NGA_MAX_IMPORT_ROWS` (safety cap per import run)
Operational guardrails
- Prefer bulk CSV ingest pipelines over request-per-object harvesting.
- Support idempotent re-import keyed by stable NGA identifiers.
- Preserve import timestamp/version markers for refresh audits.
- Handle daily dataset drift with upsert-safe writes.
Standards mapping + tests
Required rounds (minimum): object/provenance/shared-structure + protocol/search rounds.
Required tests (failing-first):
- `tests/adapters/nga.test.ts`
- `tests/api/nga/profile.test.ts`
- `tests/api/nga/search.test.ts`
- `tests/api/nga/import.test.ts`
Provider-specific conformance tests:
- CSV parsing + UTF-8 safety
- idempotent upsert behavior on repeated ingest
- preservation of source media-link references (without media binary assumptions)
- Wikidata ID passthrough for reconciliation
Protocol checks (B8):
- OPTIONS/CORS behavior on NGA routes
- response shape conformance
- URI opacity + array-cardinality safety where applicable
Exit criteria
- Adapter + routes + tests green.
- `/explore` can query/import NGA records.
- PR includes Standards Mapping note with round + fixture anchor coverage.