ENG-1983 Define intermediate schemas for node, relations and schemas by maparent · Pull Request #1183 · DiscourseGraphs/discourse-graph

maparent · 2026-07-02T13:35:09Z

https://linear.app/discourse-graphs/issue/ENG-1983/define-intermediate-schemas-for-node-relations-and-schemas

linear-code · 2026-07-02T13:35:21Z

ENG-1983

vercel · 2026-07-02T13:35:24Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
discourse-graph	Ready	Preview, Comment	Jul 10, 2026 1:41pm

supabase · 2026-07-02T13:35:25Z

This pull request has been ignored for the connected project zytfjzqyijgagqxrzbmz because there are no changes detected in packages/database/supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

mdroidian · 2026-07-02T17:50:36Z

@@ -0,0 +1,92 @@
+import type { ContentType } from "@repo/content-model";


@maparent
Let's only export types that are being used elsewhere. This adds positive signal and really helps navigate and grok the file.

When we export types that are not used, it adds a false positive and makes it harder to understand intent.

sid597

Some questions and suggestions, I read CrossApp... so many time that now I am confused what it even means lol

sid597 · 2026-07-02T18:40:03Z

+    sourceApp: "Roam",
+    url: ROAM_SOURCE_SPACE_ID,
+  },
+  local_id: ROAM_SOURCE_NODE_ID,


snake case -> camelCase

What do you think about naming, like appending source vs direct e.g

sourceLocalId, vs localId

space.sourceApp vs space.app

I have tended to remove source here, because everything was named sourceSomething, and it did not seem to add specific information (as you were remarking about CrossApp!) Maybe I missed something? Fully negotiable.

+1 to camelCase for TypeScript-facing contract fields

Agreed. Did the rename in the type and forgot to update the example.

As for source: With the same reasoning as account, happy to reintroduce it where it fits database names. It was quite broad in the original file, but that argument does not hold anymore. Would you prefer that?

sid597 · 2026-07-02T18:41:46Z

+  | {
+      localId: string;
+      // infer space from context if absent.
+      space?: SpaceRef;


Is this for future? Can space be absent in Obsidian <-> roam sync?

This is for the case where we have a reference to a node in another space. It currently happens in Obsidian; the source or destination of a relation may be an imported node, in which case we give the reference to the original node (imported nodes are not materialized again.)
But yes, it can be absent and inferred from context in most cases.

I'm assuming that localId/space can be used for more use cases? If not, then having it in a union this high up will just complicate things by making the downstream types just more complex for a single use case.

mdroidian · 2026-07-03T00:30:34Z

+  value: string;
+  localId?: string;
+  embedding?: CrossAppEmbedding;
+  author: CrossAppAccount | Ref;


When would author use Ref (specifically LocalRef)?

This allows a minimal reference to the author, i.e. enough for a reference, not enough for an upsert. I did not check how we currently include authors in the sync, but I think it's closer to Ref usage than to an InlineAccount. Reusing the Ref type is a bit of overloading here, maybe we should define a separate AccountRef. But it would end up having exactly the same parameters.

I’m still unclear on when author would actually use Ref, specifically LocalRef. Could you give a real world example?

In convertRoamNodeToFullContent, we use author_local_id which would be the equivalent of a LocalRef.

maparent · 2026-07-05T22:17:23Z

Decision: Will be split in sub-tasks.

maparent force-pushed the eng-1983-define-intermediate-schemas-for-node-relations-and-schemas branch from 3badfb0 to 4bbf2f8 Compare July 2, 2026 13:49

vercel Bot deployed to Preview July 2, 2026 13:51 View deployment

maparent force-pushed the eng-1983-define-intermediate-schemas-for-node-relations-and-schemas branch from 4bbf2f8 to a8bc33d Compare July 2, 2026 15:07

vercel Bot deployed to Preview July 2, 2026 15:09 View deployment

maparent force-pushed the eng-1983-define-intermediate-schemas-for-node-relations-and-schemas branch from a8bc33d to 47202b7 Compare July 2, 2026 15:30

vercel Bot deployed to Preview July 2, 2026 15:32 View deployment

maparent force-pushed the eng-1983-define-intermediate-schemas-for-node-relations-and-schemas branch from 47202b7 to 66ebc78 Compare July 2, 2026 15:55

vercel Bot deployed to Preview July 2, 2026 15:56 View deployment

mdroidian reviewed Jul 2, 2026

View reviewed changes

sid597 reviewed Jul 2, 2026

View reviewed changes

mdroidian reviewed Jul 3, 2026

View reviewed changes

Comment thread packages/database/src/crossAppContracts.ts Outdated

mdroidian reviewed Jul 3, 2026

View reviewed changes

Comment thread packages/database/src/crossAppContracts.ts Outdated

maparent force-pushed the eng-1983-define-intermediate-schemas-for-node-relations-and-schemas branch from 66ebc78 to 38f9ba0 Compare July 4, 2026 13:33

vercel Bot deployed to Preview July 4, 2026 13:34 View deployment

maparent force-pushed the eng-1983-define-intermediate-schemas-for-node-relations-and-schemas branch 2 times, most recently from 885ec68 to 80f3533 Compare July 4, 2026 13:41

vercel Bot deployed to Preview July 4, 2026 13:43 View deployment

maparent force-pushed the eng-1983-define-intermediate-schemas-for-node-relations-and-schemas branch from 80f3533 to e4a3d61 Compare July 4, 2026 13:51

vercel Bot deployed to Preview July 4, 2026 13:52 View deployment

maparent force-pushed the eng-1983-define-intermediate-schemas-for-node-relations-and-schemas branch from e4a3d61 to 1e9e344 Compare July 4, 2026 17:19

vercel Bot deployed to Preview July 4, 2026 17:21 View deployment

maparent force-pushed the eng-1983-define-intermediate-schemas-for-node-relations-and-schemas branch from 1e9e344 to a335e7d Compare July 4, 2026 19:17

vercel Bot deployed to Preview July 4, 2026 19:18 View deployment

maparent force-pushed the eng-1983-define-intermediate-schemas-for-node-relations-and-schemas branch from a335e7d to 768923b Compare July 4, 2026 21:49

vercel Bot deployed to Preview July 4, 2026 21:51 View deployment

maparent force-pushed the eng-1983-define-intermediate-schemas-for-node-relations-and-schemas branch from 768923b to c20936a Compare July 4, 2026 22:19

maparent marked this pull request as draft July 5, 2026 22:17

maparent removed request for mdroidian and sid597 July 5, 2026 22:17

maparent force-pushed the eng-1983-define-intermediate-schemas-for-node-relations-and-schemas branch from fc84691 to 442535f Compare July 6, 2026 02:20

maparent changed the base branch from main to eng-1987-align-cross-app-node-content-contract-with-database-schema July 6, 2026 02:21

vercel Bot deployed to Preview July 6, 2026 02:21 View deployment

maparent force-pushed the eng-1983-define-intermediate-schemas-for-node-relations-and-schemas branch from 442535f to b42b68f Compare July 6, 2026 02:29

vercel Bot deployed to Preview July 6, 2026 02:30 View deployment

maparent force-pushed the eng-1983-define-intermediate-schemas-for-node-relations-and-schemas branch from b42b68f to 729236e Compare July 6, 2026 02:39

vercel Bot deployed to Preview July 6, 2026 02:40 View deployment

Base automatically changed from eng-1987-align-cross-app-node-content-contract-with-database-schema to main July 6, 2026 11:53

maparent force-pushed the eng-1983-define-intermediate-schemas-for-node-relations-and-schemas branch from 729236e to c9117a2 Compare July 6, 2026 15:22

vercel Bot deployed to Preview July 6, 2026 15:23 View deployment

maparent force-pushed the eng-1983-define-intermediate-schemas-for-node-relations-and-schemas branch from c9117a2 to d3a1f85 Compare July 6, 2026 19:25

vercel Bot deployed to Preview July 6, 2026 19:26 View deployment

maparent force-pushed the eng-1983-define-intermediate-schemas-for-node-relations-and-schemas branch from d3a1f85 to e54938d Compare July 8, 2026 13:51

vercel Bot deployed to Preview July 8, 2026 13:53 View deployment

maparent force-pushed the eng-1983-define-intermediate-schemas-for-node-relations-and-schemas branch from e54938d to a787c0b Compare July 9, 2026 18:16

vercel Bot deployed to Preview July 9, 2026 18:17 View deployment

maparent force-pushed the eng-1983-define-intermediate-schemas-for-node-relations-and-schemas branch from a787c0b to 8394ac5 Compare July 9, 2026 18:29

vercel Bot deployed to Preview July 9, 2026 18:31 View deployment

maparent force-pushed the eng-1983-define-intermediate-schemas-for-node-relations-and-schemas branch from 8394ac5 to 859d547 Compare July 9, 2026 18:34

vercel Bot deployed to Preview July 9, 2026 18:36 View deployment

maparent force-pushed the eng-1983-define-intermediate-schemas-for-node-relations-and-schemas branch from 859d547 to fab6a5f Compare July 10, 2026 13:14

vercel Bot deployed to Preview July 10, 2026 13:15 View deployment

maparent added 2 commits July 10, 2026 09:38

eng-1863 Relation cross-app contract

f14ab44

eng-1983 initial stab at crossAppContracts

f2f5ee7

maparent force-pushed the eng-1983-define-intermediate-schemas-for-node-relations-and-schemas branch from fab6a5f to f2f5ee7 Compare July 10, 2026 13:39

vercel Bot deployed to Preview July 10, 2026 13:41 View deployment

		@@ -0,0 +1,92 @@
		import type { ContentType } from "@repo/content-model";

Uh oh!

Conversation

maparent commented Jul 2, 2026

Uh oh!

linear-code Bot commented Jul 2, 2026

Uh oh!

vercel Bot commented Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

supabase Bot commented Jul 2, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sid597 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mdroidian Jul 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mdroidian Jul 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

maparent commented Jul 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

vercel Bot commented Jul 2, 2026 •

edited

Loading

mdroidian Jul 5, 2026 •

edited

Loading

mdroidian Jul 3, 2026 •

edited

Loading