Kickoff: Native Schema API Support
- Dominant language
- TypeScript
- Stars
- 481
- Forks
- 108
- Avg merge
- 6d 8h
- Merged PRs (30d)
- 5
Description
> [!NOTE]
> **Kickoff — Wayfinder not yet run, no chart yet.** Placeholder child of the **Native Schema API Support** initiative (#2008), holding a brain dump of paths to explore and potential blockers until scoping happens. "Placeholder" means only that there's no chart — the content below is real. Run `/wayfinder` against the initiative to create the map; **this kickoff closes when that map is created**, and the map takes over the scoping route.
## Rough intent
Determine how Graph Explorer should adopt the native **Neptune DB Schema API** (and the existing **Neptune Analytics** equivalent) as a source for schema discovery, replacing or augmenting today's query-derived schema-sync path — while keeping generic (non-Neptune) databases working.
## Notes
- **Domain:** schema sync — how Graph Explorer discovers a connection's vertex/edge types, properties, and relationships.
- **Skills to consult when charting:** `/wayfinder` to chart; `/research` to read the Neptune DB Schema API and Neptune Analytics schema docs; `/domain-modeling` for schema vocabulary.
## Paths to explore
Educated guesses at what needs investigating — the charting session confirms, splits, or drops them.
- **API capabilities** *(research)* — what exactly do the Neptune DB Schema API and the Neptune Analytics schema feature return? Does their output cover everything our current sync derives (types, properties, counts, multi-label nodes, edge connections)? Where are the gaps?
- **Detection & routing** *(grilling)* — how do we know a connection *supports* the Schema API? This overlaps capability probing (#1596). Does the answer depend on the **database provider type** (#1326)?
- **Fallback for generic databases** *(grilling)* — non-Neptune Gremlin/SPARQL endpoints won't have this API; the existing query-based sync must remain for them. What's the selection model?
- **Reconcile with existing sync work** *(grilling)* — the native API may obsolete some current efforts: #1604 (alternative SPARQL queries for sync perf) and #381 (optimize SPARQL sync query) could become moot on the Neptune path; #1681 (large-schema sync perf) may be largely solved by it. Which existing issues does adoption close, change, or leave untouched?
- **Data model mapping** *(research + grilling)* — how does the API's shape map onto our internal schema model? Does it require changes to how schema is stored/cached (relates to #1616, decoupling sync from the TanStack cache)?
## Potential blockers & pitfalls
- **Provider-type dependency (related, likely not blocking):** cleanly routing to the Schema API may be easier once **database provider type** (#1326) and the **connection UI overhaul** exist — related, but adoption is probably not *blocked* on them.
- **Version/availability gating:** the Neptune DB Schema API is newly released — older Neptune engine versions won't have it, so detection can't assume presence by "it's Neptune."
- **Gap risk:** if the API doesn't return everything sync needs, we may end up running *both* the API and supplemental queries — worth confirming early so the design doesn't assume a clean replacement.
## Related issues
- Initiative: #2008
- Related (likely not blocking): #1326 (database provider type / connection UI overhaul)
- Existing schema-sync work to reconcile: #1681, #1604, #1616, #1596, #381, #1212
> [!IMPORTANT]
> Internal only — this issue is maintained by the core team and is not accepting external contributions.
Contributor guide
Research direction
Start by running /wayfinder against initiative #2008, then research the Neptune DB Schema API and Neptune Analytics schema documentation. Review the existing query-based schema sync and related issues #1681, #1604, #1616, #1596, #381, and #1212. Done means the initiative has a confirmed map covering capabilities, routing, fallback behavior, data-model mapping, and blockers; this kickoff then closes.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- api, databases
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 15/100