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 2, 2026 3:56pm

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:35:27Z

    full: { format: contentTypes.markdown, value: roamFullMarkdown },
  },
-  sourceModifiedAt: "2026-06-12T14:00:00.000Z",
+  createdAt: new Date("2026-06-12T14:00:00.000Z"),


We removed the modifiedAt? example from both cases. Also why is it optional? I think keeping it optional makes downstream code like roamOriginNodeExmple.modifiedAt? and then dependent on that. We can make the initial modifiedAt same as createdAt iff its not present.

I could add it back in the example. It's optional precisely for the reason you gave: it uses createdAt if absent.

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

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.

sid597 · 2026-07-02T18:43:59Z

+export type CrossAppRelationTripleSchema = CrossAppBase & {
+  label: string;
+  reverseLabel: string;
+  relation?: Ref | CrossAppRelationTypeSchema;


Sorry this is confusing like we already have the label, and reverseLabel is that like source space's version? and this one is for the target's space (or vice-versa)? If so can we name them to reflect that?

reverseLabel is the label of the reverse relation. So nothing to do with source space or import.

Ah, and I put it on the triple, which is redundant, because in Roam we don't have the relation as a separate object.

Let's use complement here instead of reverseLabel

reverseLabel looks new in this PR, while complement is already the repo-wide term for the inverse/reverse relation label in both Roam and Obsidian. For example, Roam relation settings and query logic use label / complement, and Obsidian relation types also store label / complement.

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

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


When would author use Ref (specifically LocalRef)?

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

+};
+
+export type CrossAppAccount = {
+  account: string;


Is this intended to be accountLocalId?

account is ambiguous here: it could mean a display label, platform username, database account id, or the whole account object. Existing DB-facing shapes use account_local_id, and TypeScript-facing code generally uses accountLocalId.

mdroidian · 2026-07-03T00:59:06Z

+  createdAt: Date;
+  modifiedAt?: Date;
+  author: CrossAppAccount | Ref;
+  contributors?: (CrossAppAccount | Ref)[];


I don't believe contributors is actively used anywhere today, correct? I see the DB tables for it, but I don't see app/converter paths producing or consuming it.

If that's right, I'd prefer we wait to add this to the cross-app contract until we have a concrete use case and are actually wiring it through. Otherwise it adds another field to reason about without a clear behavior

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

eng-1983 initial stab at crossAppContracts

66ebc78

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

		@@ -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!

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!

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 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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

vercel Bot commented Jul 2, 2026 •

edited

Loading

mdroidian Jul 3, 2026 •

edited

Loading

mdroidian Jul 3, 2026 •

edited

Loading