{"id":"providers/nga-open-data","relativePath":"providers/nga-open-data.md","title":"National Gallery of Art (NGA) Open Data Integration Plan","markdown":"# National Gallery of Art (NGA) Open Data Integration Plan\n\nStatus: Planned (B5 provider/data-source slice)  \nUpdated: May 30, 2026\n\n## Official source summary\n\n- Program: National Gallery of Art Open Data Program\n- Dataset form: CSV (UTF-8), updated frequently (typically daily)\n- Scale: 130,000+ artworks and artists\n- License: CC0 (dataset factual records)\n- Distribution: downloadable from NGA-linked GitHub dataset repo\n\n## Key constraints (from official program text)\n\n- Open data package includes factual collection data records.\n- Images/media binaries are not included in the dataset package.\n- Dataset may include links/references to media and related resources.\n- Data is “as is” and continuously changing (daily refresh cadence).\n- Wikidata QIDs are included when known, but are not exhaustive.\n- Attribution/citation is requested for research usage.\n- Do not use NGA logo or imply endorsement without permission.\n\n## Integration goals\n\n- Treat NGA as a first-class provider source in B5 with CSV-first ingest.\n- Preserve raw source fields in `_source.raw` and map stable Linked Art boundary fields.\n- Use Wikidata IDs as reconciliation hints in B6 authority-cache flows.\n- Keep image/reuse semantics conservative unless rights and open access status are explicit per object.\n\n## Proposed implementation slice\n\n### Adapter\n\n- `src/adapters/nga.ts`\n  - profile descriptor\n  - CSV row-to-record mapper\n  - optional object-link enrichment using dataset-provided URLs\n  - normalization to `SourceRecord` + `Artwork` DTO boundary\n\n### Routes\n\n- `GET /api/nga/profile`\n- `POST /api/nga/search` (search over imported/indexed NGA rows in app storage)\n- `POST /api/nga/import` (CSV row batch ingest)\n- optional `POST /api/nga/refresh` (manual refresh trigger for local dev)\n\n### UI\n\n- add `nga` source toggle in `/explore`\n- show citation + source attribution + open data context in detail surfaces\n\n## Env configuration\n\n- `NGA_DATASET_URL` (CSV export URL or local mirrored feed URL)\n- `NGA_REFRESH_MODE` (`manual` default, `scheduled` in later ops slice)\n- `NGA_MAX_IMPORT_ROWS` (safety cap per import run)\n\n## Operational guardrails\n\n- Prefer bulk CSV ingest pipelines over request-per-object harvesting.\n- Support idempotent re-import keyed by stable NGA identifiers.\n- Preserve import timestamp/version markers for refresh audits.\n- Handle daily dataset drift with upsert-safe writes.\n\n## Standards mapping + tests\n\nRequired rounds (minimum): object/provenance/shared-structure + protocol/search rounds.\n\nRequired tests (failing-first):\n\n- `tests/adapters/nga.test.ts`\n- `tests/api/nga/profile.test.ts`\n- `tests/api/nga/search.test.ts`\n- `tests/api/nga/import.test.ts`\n\nProvider-specific conformance tests:\n\n- CSV parsing + UTF-8 safety\n- idempotent upsert behavior on repeated ingest\n- preservation of source media-link references (without media binary assumptions)\n- Wikidata ID passthrough for reconciliation\n\nProtocol checks (B8):\n\n- OPTIONS/CORS behavior on NGA routes\n- response shape conformance\n- URI opacity + array-cardinality safety where applicable\n\n## Exit criteria\n\n- Adapter + routes + tests green.\n- `/explore` can query/import NGA records.\n- PR includes Standards Mapping note with round + fixture anchor coverage.\n","sections":[{"level":2,"heading":"Official source summary","anchor":"official-source-summary"},{"level":2,"heading":"Key constraints (from official program text)","anchor":"key-constraints-from-official-program-text"},{"level":2,"heading":"Integration goals","anchor":"integration-goals"},{"level":2,"heading":"Proposed implementation slice","anchor":"proposed-implementation-slice"},{"level":3,"heading":"Adapter","anchor":"adapter"},{"level":3,"heading":"Routes","anchor":"routes"},{"level":3,"heading":"UI","anchor":"ui"},{"level":2,"heading":"Env configuration","anchor":"env-configuration"},{"level":2,"heading":"Operational guardrails","anchor":"operational-guardrails"},{"level":2,"heading":"Standards mapping + tests","anchor":"standards-mapping-tests"},{"level":2,"heading":"Exit criteria","anchor":"exit-criteria"}],"html":"<h1 id=\"national-gallery-of-art-nga-open-data-integration-plan\">National Gallery of Art (NGA) Open Data Integration Plan</h1>\n<p>Status: Planned (B5 provider/data-source slice)  </p>\n<p>Updated: May 30, 2026</p>\n<h2 id=\"official-source-summary\">Official source summary</h2>\n<ul><li>Program: National Gallery of Art Open Data Program</li><li>Dataset form: CSV (UTF-8), updated frequently (typically daily)</li><li>Scale: 130,000+ artworks and artists</li><li>License: CC0 (dataset factual records)</li><li>Distribution: downloadable from NGA-linked GitHub dataset repo</li></ul>\n<h2 id=\"key-constraints-from-official-program-text\">Key constraints (from official program text)</h2>\n<ul><li>Open data package includes factual collection data records.</li><li>Images/media binaries are not included in the dataset package.</li><li>Dataset may include links/references to media and related resources.</li><li>Data is “as is” and continuously changing (daily refresh cadence).</li><li>Wikidata QIDs are included when known, but are not exhaustive.</li><li>Attribution/citation is requested for research usage.</li><li>Do not use NGA logo or imply endorsement without permission.</li></ul>\n<h2 id=\"integration-goals\">Integration goals</h2>\n<ul><li>Treat NGA as a first-class provider source in B5 with CSV-first ingest.</li><li>Preserve raw source fields in `_source.raw` and map stable Linked Art boundary fields.</li><li>Use Wikidata IDs as reconciliation hints in B6 authority-cache flows.</li><li>Keep image/reuse semantics conservative unless rights and open access status are explicit per object.</li></ul>\n<h2 id=\"proposed-implementation-slice\">Proposed implementation slice</h2>\n<h3 id=\"adapter\">Adapter</h3>\n<ul><li>`src/adapters/nga.ts`</li><li>profile descriptor</li><li>CSV row-to-record mapper</li><li>optional object-link enrichment using dataset-provided URLs</li><li>normalization to `SourceRecord` + `Artwork` DTO boundary</li></ul>\n<h3 id=\"routes\">Routes</h3>\n<ul><li>`GET /api/nga/profile`</li><li>`POST /api/nga/search` (search over imported/indexed NGA rows in app storage)</li><li>`POST /api/nga/import` (CSV row batch ingest)</li><li>optional `POST /api/nga/refresh` (manual refresh trigger for local dev)</li></ul>\n<h3 id=\"ui\">UI</h3>\n<ul><li>add `nga` source toggle in `/explore`</li><li>show citation + source attribution + open data context in detail surfaces</li></ul>\n<h2 id=\"env-configuration\">Env configuration</h2>\n<ul><li>`NGA_DATASET_URL` (CSV export URL or local mirrored feed URL)</li><li>`NGA_REFRESH_MODE` (`manual` default, `scheduled` in later ops slice)</li><li>`NGA_MAX_IMPORT_ROWS` (safety cap per import run)</li></ul>\n<h2 id=\"operational-guardrails\">Operational guardrails</h2>\n<ul><li>Prefer bulk CSV ingest pipelines over request-per-object harvesting.</li><li>Support idempotent re-import keyed by stable NGA identifiers.</li><li>Preserve import timestamp/version markers for refresh audits.</li><li>Handle daily dataset drift with upsert-safe writes.</li></ul>\n<h2 id=\"standards-mapping-tests\">Standards mapping + tests</h2>\n<p>Required rounds (minimum): object/provenance/shared-structure + protocol/search rounds.</p>\n<p>Required tests (failing-first):</p>\n<ul><li>`tests/adapters/nga.test.ts`</li><li>`tests/api/nga/profile.test.ts`</li><li>`tests/api/nga/search.test.ts`</li><li>`tests/api/nga/import.test.ts`</li></ul>\n<p>Provider-specific conformance tests:</p>\n<ul><li>CSV parsing + UTF-8 safety</li><li>idempotent upsert behavior on repeated ingest</li><li>preservation of source media-link references (without media binary assumptions)</li><li>Wikidata ID passthrough for reconciliation</li></ul>\n<p>Protocol checks (B8):</p>\n<ul><li>OPTIONS/CORS behavior on NGA routes</li><li>response shape conformance</li><li>URI opacity + array-cardinality safety where applicable</li></ul>\n<h2 id=\"exit-criteria\">Exit criteria</h2>\n<ul><li>Adapter + routes + tests green.</li><li>`/explore` can query/import NGA records.</li><li>PR includes Standards Mapping note with round + fixture anchor coverage.</li></ul>","updatedAt":"2018-10-20T01:46:40.000Z","checksum":"51c4807c8de0ce7dd81dac8d17ff4b28798e3e68578f45161019ff43ee1a639f","checksumPrefix":"51c4807c8de0","anchorCount":11,"lineCount":95,"rawUrl":"/api/docs/content?path=providers%2Fnga-open-data.md","htmlUrl":"/docs?doc=providers%2Fnga-open-data.md","apiUrl":"/api/docs/content?path=providers%2Fnga-open-data.md"}