{"id":"providers/rkd-knowledge-graph","relativePath":"providers/rkd-knowledge-graph.md","title":"RKD Knowledge Graph Integration Plan","markdown":"# RKD Knowledge Graph Integration Plan\n\nStatus: Planned (next B5 provider slice) \nUpdated: May 30, 2026\n\n## Source\n\n- Dataset page: \n- Services page: \n- Triply SPARQL API reference: \n\nAs of May 30, 2026, the public dataset reports 600M+ statements and indicates CIDOC-CRM + Linked Art oriented modeling.\n\n## Why this provider\n\n- Strong Linked Data fit for Meta Museum’s event-centric model.\n- High-value coverage in Netherlandish art and archival/provenance-rich domains.\n- Natural complement to Met, Getty, and Rijks.\n\n## Integration goals\n\n- Add RKD as a first-class provider through `provider-interface`.\n- Keep Linked Art JSON-LD canonical in storage and import flows.\n- Preserve attribution + license metadata at ingest and display boundaries.\n- Keep runtime safe at scale (bounded/paged queries only).\n\n## Proposed implementation slice\n\n### Adapter\n\n- `src/adapters/rkd.ts`\n - provider descriptor/profile\n - URI parsing/normalization helpers\n - candidate extraction from SPARQL/search payloads\n - normalization into `SourceRecord` + `Artwork` boundary DTOs\n\n### Routes\n\n- `GET /api/rkd/profile`\n- `POST /api/rkd/search`\n- `POST /api/rkd/entity`\n- `POST /api/rkd/import`\n- Optional `POST /api/rkd/sparql` (read-only, allowlisted templates only)\n\n### UI\n\n- Add `rkd` source toggle to `/explore`.\n- Show provider/license attribution consistently in cards/details/import output.\n\n## Configuration model\n\nUse environment-driven endpoint config to avoid hardcoding service assumptions:\n\n- `RKD_TRIPLY_ACCOUNT` (default: `rkd`)\n- `RKD_TRIPLY_DATASET` (default: `RKD-Knowledge-Graph`)\n- `RKD_SPARQL_SERVICE` (for example `speedy` or configured service name)\n- `RKD_SPARQL_ENDPOINT` (explicit override, if provided)\n- `RKD_TRIPLY_INSTANCE` (default: `triplydb.com`)\n- `RKD_TRIPLY_TOKEN` (optional; required for private/internal datasets or write-capable service management)\n- `RKD_USE_SAVED_QUERY_API` (`true` by default in production)\n- `RKD_SAVED_QUERY_BASE` (optional explicit saved-query API base override)\n\nResolution order:\n1. `RKD_SPARQL_ENDPOINT` explicit override\n2. computed Triply endpoint from account/dataset/service\n\nComputed endpoint patterns (from official Triply API docs):\n\n- Dataset API:\n - `https://api.INSTANCE/datasets/ACCOUNT/DATASET/`\n- Service API:\n - `https://api.INSTANCE/datasets/ACCOUNT/DATASET/services/SERVICE/`\n- SPARQL endpoint:\n - `https://api.INSTANCE/datasets/ACCOUNT/DATASET/services/SERVICE/sparql`\n- Linked-data export:\n - `https://api.INSTANCE/datasets/ACCOUNT/DATASET/download`\n- Graph list:\n - `https://api.INSTANCE/datasets/ACCOUNT/DATASET/graphs`\n- IRI describe:\n - `https://api.INSTANCE/datasets/ACCOUNT/DATASET/describe.nt?resource=RESOURCE`\n\n## Authentication and security\n\nFrom official Triply API guidance:\n\n- Public datasets: most reads can be done without auth.\n- Internal/private datasets (and write operations): require bearer token.\n- Header format:\n - `Authorization: Bearer TOKEN`\n- Token handling requirements:\n - never commit tokens to git\n - never share tokens outside authorized operators\n - rotate tokens regularly or after suspected compromise\n\nProject policy:\n\n- `RKD_TRIPLY_TOKEN` must come from environment/secret manager only.\n- No token logging in route handler errors.\n- Tests must stub auth headers and never use real secrets.\n\n## Scale and safety guardrails\n\n- Enforce small page windows (`limit`, `offset` / cursor) and max caps.\n- Timebox upstream calls and retry with backoff.\n- Reject mutation SPARQL (`INSERT`, `DELETE`, `LOAD`, `CLEAR`, etc.).\n- Prefer allowlisted query templates with controlled variables.\n- Add cache headers/internal memoization for repeated lookups.\n- Default to saved query APIs for production retrieval/pagination; use raw SPARQL only for controlled admin/research paths.\n\n## SPARQL protocol + formats (official)\n\nTriply supports the SPARQL 1.1 query protocol with:\n\n- GET query (`query` parameter) for small requests\n- POST urlencoded (`application/x-www-form-urlencoded`)\n- POST direct (`application/sparql-query`) for larger/custom requests\n\nImplementation preference:\n\n1. Saved queries for production flows\n2. Direct POST for ad hoc long queries\n3. GET only for tiny diagnostics\n\nResult formats (via `Accept` header or suffix) include:\n\n- `application/json`, `application/sparql-results+json`, `text/csv`, `text/tab-separated-values`\n- `application/ld+json`, `application/n-triples`, `application/n-quads`, `application/trig`, `text/turtle`\n\nFor Linked Art integration routes, prefer:\n\n- `application/ld+json` / `application/n-triples` for graph materialization paths\n- `application/sparql-results+json` for tabular SELECT/ASK result handling\n\n## Linked-data serialization handling\n\nTriply linked-data export supports:\n\n- TriG (`application/trig`)\n- N-Triples (`application/n-triples`)\n- N-Quads (`application/n-quads`)\n- Turtle (`text/turtle`)\n- JSON-LD (`application/ld+json`)\n\nMeta Museum adapter behavior:\n\n- ingest using JSON-LD or N-Triples/N-Quads depending on endpoint behavior\n- normalize to canonical Linked Art JSON-LD at storage boundary\n- preserve source serialization metadata in `_source` diagnostics where useful\n\n## Standards and conformance mapping\n\nAll RKD provider PRs must include Standards Mapping with round + fixture anchors from:\n\n- object + provenance rounds\n- shared structures rounds\n- schema rounds (as applicable)\n- search/protocol rounds (71+)\n\nRequired conformance checks:\n\n- event-centric modeling preserved (no object-person shortcut flattening)\n- ownership vs custody distinction preserved\n- ambiguous transfers mapped conservatively (`Transfer`)\n- carrier/content separation preserved (`HumanMadeObject`/`DigitalObject` vs `VisualItem`/`LinguisticObject`)\n- protocol/profile checks (B8): context/profile negotiation, CORS/OPTIONS, URI opacity, array cardinality safety\n- Triply transport checks: auth behavior for public/private access modes, controlled media-type negotiation, safe fallback when requested serialization is unavailable\n\n## License and attribution handling\n\n- Dataset license: Open Data Commons Attribution License 1.0 (ODC-By 1.0).\n- Persist and render source attribution and license metadata with imported records.\n- Keep reuse status conservative when image rights are not explicit.\n\n## Test plan (failing-first)\n\n- `tests/adapters/rkd.test.ts`\n- `tests/api/rkd/profile.test.ts`\n- `tests/api/rkd/search.test.ts`\n- `tests/api/rkd/entity.test.ts`\n- `tests/api/rkd/import.test.ts`\n- optional `tests/api/rkd/sparql.test.ts`\n- extend `tests/quality/protocol-conformance.test.ts` with RKD route coverage once routes land\n- add `tests/api/rkd/auth.test.ts` covering:\n - public-read unauthenticated path\n - bearer token forwarding path\n - missing/invalid token behavior for protected operations\n- add `tests/api/rkd/serialization.test.ts` covering Accept-header negotiation and fallback behavior\n\n## Exit criteria for RKD slice\n\n- Routes and adapter shipped with green tests.\n- `/explore` can discover + import RKD records.\n- Standards Mapping note included in PR.\n- B8 protocol checks implemented for RKD endpoints.\n","sections":[{"level":2,"heading":"Source","anchor":"source"},{"level":2,"heading":"Why this provider","anchor":"why-this-provider"},{"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":"Configuration model","anchor":"configuration-model"},{"level":2,"heading":"Authentication and security","anchor":"authentication-and-security"},{"level":2,"heading":"Scale and safety guardrails","anchor":"scale-and-safety-guardrails"},{"level":2,"heading":"SPARQL protocol + formats (official)","anchor":"sparql-protocol-formats-official"},{"level":2,"heading":"Linked-data serialization handling","anchor":"linked-data-serialization-handling"},{"level":2,"heading":"Standards and conformance mapping","anchor":"standards-and-conformance-mapping"},{"level":2,"heading":"License and attribution handling","anchor":"license-and-attribution-handling"},{"level":2,"heading":"Test plan (failing-first)","anchor":"test-plan-failing-first"},{"level":2,"heading":"Exit criteria for RKD slice","anchor":"exit-criteria-for-rkd-slice"}],"html":"

RKD Knowledge Graph Integration Plan

\n

Status: Planned (next B5 provider slice)

\n

Updated: May 30, 2026

\n

Source

\n
  • Dataset page: <https://rkd.triply.cc/rkd/RKD-Knowledge-Graph>
  • Services page: <https://rkd.triply.cc/rkd/RKD-Knowledge-Graph/services>
  • Triply SPARQL API reference: <https://docs.triply.cc/triply-api/>
\n

As of May 30, 2026, the public dataset reports 600M+ statements and indicates CIDOC-CRM + Linked Art oriented modeling.

\n

Why this provider

\n
  • Strong Linked Data fit for Meta Museum’s event-centric model.
  • High-value coverage in Netherlandish art and archival/provenance-rich domains.
  • Natural complement to Met, Getty, and Rijks.
\n

Integration goals

\n
  • Add RKD as a first-class provider through `provider-interface`.
  • Keep Linked Art JSON-LD canonical in storage and import flows.
  • Preserve attribution + license metadata at ingest and display boundaries.
  • Keep runtime safe at scale (bounded/paged queries only).
\n

Proposed implementation slice

\n

Adapter

\n
  • `src/adapters/rkd.ts`
  • provider descriptor/profile
  • URI parsing/normalization helpers
  • candidate extraction from SPARQL/search payloads
  • normalization into `SourceRecord` + `Artwork` boundary DTOs
\n

Routes

\n
  • `GET /api/rkd/profile`
  • `POST /api/rkd/search`
  • `POST /api/rkd/entity`
  • `POST /api/rkd/import`
  • Optional `POST /api/rkd/sparql` (read-only, allowlisted templates only)
\n

UI

\n
  • Add `rkd` source toggle to `/explore`.
  • Show provider/license attribution consistently in cards/details/import output.
\n

Configuration model

\n

Use environment-driven endpoint config to avoid hardcoding service assumptions:

\n
  • `RKD_TRIPLY_ACCOUNT` (default: `rkd`)
  • `RKD_TRIPLY_DATASET` (default: `RKD-Knowledge-Graph`)
  • `RKD_SPARQL_SERVICE` (for example `speedy` or configured service name)
  • `RKD_SPARQL_ENDPOINT` (explicit override, if provided)
  • `RKD_TRIPLY_INSTANCE` (default: `triplydb.com`)
  • `RKD_TRIPLY_TOKEN` (optional; required for private/internal datasets or write-capable service management)
  • `RKD_USE_SAVED_QUERY_API` (`true` by default in production)
  • `RKD_SAVED_QUERY_BASE` (optional explicit saved-query API base override)
\n

Resolution order:

\n
  1. `RKD_SPARQL_ENDPOINT` explicit override
\n
  1. computed Triply endpoint from account/dataset/service
\n

Computed endpoint patterns (from official Triply API docs):

\n
  • Dataset API:
  • `https://api.INSTANCE/datasets/ACCOUNT/DATASET/`
  • Service API:
  • `https://api.INSTANCE/datasets/ACCOUNT/DATASET/services/SERVICE/`
  • SPARQL endpoint:
  • `https://api.INSTANCE/datasets/ACCOUNT/DATASET/services/SERVICE/sparql`
  • Linked-data export:
  • `https://api.INSTANCE/datasets/ACCOUNT/DATASET/download`
  • Graph list:
  • `https://api.INSTANCE/datasets/ACCOUNT/DATASET/graphs`
  • IRI describe:
  • `https://api.INSTANCE/datasets/ACCOUNT/DATASET/describe.nt?resource=RESOURCE`
\n

Authentication and security

\n

From official Triply API guidance:

\n
  • Public datasets: most reads can be done without auth.
  • Internal/private datasets (and write operations): require bearer token.
  • Header format:
  • `Authorization: Bearer TOKEN`
  • Token handling requirements:
  • never commit tokens to git
  • never share tokens outside authorized operators
  • rotate tokens regularly or after suspected compromise
\n

Project policy:

\n
  • `RKD_TRIPLY_TOKEN` must come from environment/secret manager only.
  • No token logging in route handler errors.
  • Tests must stub auth headers and never use real secrets.
\n

Scale and safety guardrails

\n
  • Enforce small page windows (`limit`, `offset` / cursor) and max caps.
  • Timebox upstream calls and retry with backoff.
  • Reject mutation SPARQL (`INSERT`, `DELETE`, `LOAD`, `CLEAR`, etc.).
  • Prefer allowlisted query templates with controlled variables.
  • Add cache headers/internal memoization for repeated lookups.
  • Default to saved query APIs for production retrieval/pagination; use raw SPARQL only for controlled admin/research paths.
\n

SPARQL protocol + formats (official)

\n

Triply supports the SPARQL 1.1 query protocol with:

\n
  • GET query (`query` parameter) for small requests
  • POST urlencoded (`application/x-www-form-urlencoded`)
  • POST direct (`application/sparql-query`) for larger/custom requests
\n

Implementation preference:

\n
  1. Saved queries for production flows
\n
  1. Direct POST for ad hoc long queries
\n
  1. GET only for tiny diagnostics
\n

Result formats (via `Accept` header or suffix) include:

\n
  • `application/json`, `application/sparql-results+json`, `text/csv`, `text/tab-separated-values`
  • `application/ld+json`, `application/n-triples`, `application/n-quads`, `application/trig`, `text/turtle`
\n

For Linked Art integration routes, prefer:

\n
  • `application/ld+json` / `application/n-triples` for graph materialization paths
  • `application/sparql-results+json` for tabular SELECT/ASK result handling
\n

Linked-data serialization handling

\n

Triply linked-data export supports:

\n
  • TriG (`application/trig`)
  • N-Triples (`application/n-triples`)
  • N-Quads (`application/n-quads`)
  • Turtle (`text/turtle`)
  • JSON-LD (`application/ld+json`)
\n

Meta Museum adapter behavior:

\n
  • ingest using JSON-LD or N-Triples/N-Quads depending on endpoint behavior
  • normalize to canonical Linked Art JSON-LD at storage boundary
  • preserve source serialization metadata in `_source` diagnostics where useful
\n

Standards and conformance mapping

\n

All RKD provider PRs must include Standards Mapping with round + fixture anchors from:

\n
  • object + provenance rounds
  • shared structures rounds
  • schema rounds (as applicable)
  • search/protocol rounds (71+)
\n

Required conformance checks:

\n
  • event-centric modeling preserved (no object-person shortcut flattening)
  • ownership vs custody distinction preserved
  • ambiguous transfers mapped conservatively (`Transfer`)
  • carrier/content separation preserved (`HumanMadeObject`/`DigitalObject` vs `VisualItem`/`LinguisticObject`)
  • protocol/profile checks (B8): context/profile negotiation, CORS/OPTIONS, URI opacity, array cardinality safety
  • Triply transport checks: auth behavior for public/private access modes, controlled media-type negotiation, safe fallback when requested serialization is unavailable
\n

License and attribution handling

\n
  • Dataset license: Open Data Commons Attribution License 1.0 (ODC-By 1.0).
  • Persist and render source attribution and license metadata with imported records.
  • Keep reuse status conservative when image rights are not explicit.
\n

Test plan (failing-first)

\n
  • `tests/adapters/rkd.test.ts`
  • `tests/api/rkd/profile.test.ts`
  • `tests/api/rkd/search.test.ts`
  • `tests/api/rkd/entity.test.ts`
  • `tests/api/rkd/import.test.ts`
  • optional `tests/api/rkd/sparql.test.ts`
  • extend `tests/quality/protocol-conformance.test.ts` with RKD route coverage once routes land
  • add `tests/api/rkd/auth.test.ts` covering:
  • public-read unauthenticated path
  • bearer token forwarding path
  • missing/invalid token behavior for protected operations
  • add `tests/api/rkd/serialization.test.ts` covering Accept-header negotiation and fallback behavior
\n

Exit criteria for RKD slice

\n
  • Routes and adapter shipped with green tests.
  • `/explore` can discover + import RKD records.
  • Standards Mapping note included in PR.
  • B8 protocol checks implemented for RKD endpoints.
","updatedAt":"2018-10-20T01:46:40.000Z","checksum":"2b4b42f2ad4217ec5b67c38e43f7aff6322130f896e4e1ac0d1a5723f06106cf","checksumPrefix":"2b4b42f2ad42","anchorCount":16,"lineCount":195,"rawUrl":"/api/docs/content?path=providers%2Frkd-knowledge-graph.md","htmlUrl":"/docs?doc=providers%2Frkd-knowledge-graph.md","apiUrl":"/api/docs/content?path=providers%2Frkd-knowledge-graph.md"}