Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion packages/database/doc/concept_design.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,12 +54,14 @@ CrossAppNodeSchema:
label: string
template?: string
templateTitle?: string
color?: string

CrossAppRelationTypeSchema:
# Base and...
metadata?: Json
label: string
complement: string
color?: string

CrossAppRelationTripleSchema (Roam):
# Base and...
Expand Down Expand Up @@ -106,7 +108,7 @@ CrossAppRelation:

Note on metadata: It is read from the database, but currently not written. We will phase it out.

When some specific keys of `literal_content` are mapped to a CrossApp field, those key-value pairs are not included again in the `metadata`. Thus `metadata` is a grab-bag for residual data. (Eg color for now.)
When some specific keys of `literal_content` are mapped to a CrossApp field, those key-value pairs are not included again in the `metadata`. Thus `metadata` is a grab-bag for residual data. (Eg `source_data` for now.)

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

color is now a CrossApp field, so it is no longer residual. source_data is what metadata still carries for Obsidian rows.


Residual (not otherwise accounted for) keys in Obsidian frontmatter are mapped to `literal_content->source_data`. (Not through CrossApp.)

Expand All @@ -118,6 +120,7 @@ Residual (not otherwise accounted for) keys in Obsidian frontmatter are mapped t
| `template` | `literal_content->template_content` | |
| `templateTitle` | `literal_content->template` | |
| `format` | `literal_content->format` | |
| `color` | `literal_content->color` | hex |
| - | `is_schema` | true |
| - | `schema_id` | null |
| - | `arity` | 0 |
Expand Down Expand Up @@ -170,6 +173,7 @@ Query filter: `.eq("is_relation", false).eq("is_schema", false)`
| - | `reference_content` | {} |
| `label` | `name`, `literal_content->label` | |
| `complement` | `literal_content->complement` | |
| `color` | `literal_content->color` | tldraw color name |
| - | `is_relation` | true |

Query filter: `.eq("is_relation", true).eq("is_schema", true).is("reference_content->source", "null")`
Expand Down
4 changes: 3 additions & 1 deletion packages/database/src/crossAppContracts.ts
Original file line number Diff line number Diff line change
Expand Up @@ -26,14 +26,16 @@ export type CrossAppNodeSchema = CrossAppSchemaBase & {
template?: string;
templateTitle?: string;
format?: string;
color?: string;

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

color is the one field ENG-1986 adds to the CrossApp schemas. Marc-Antoine asked on ENG-2091 (2026-10-23, 2026-10-25) that every value CrossApp carries be an explicit field, and named format and colour. It is stored like format, at the top level of literal_content. Both apps already call this setting color.

slotDefinitions?: Record<string, LocalId | undefined>;
};

// A relation type schema
export type CrossAppRelationTypeSchema = CrossAppSchemaBase & {
label: string;
complement: string;
// should we add colour? format?
color?: string;

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Optional because rows Obsidian published before #1633 hold the color in literal_content.source_data, and the database-to-CrossApp converter reads only the top-level key. Obsidian sets it on every write from #1633 on.

// should we add format?
};

// A relation triple schema
Expand Down
42 changes: 42 additions & 0 deletions packages/database/src/lib/__tests__/crossAppConverters.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ import type { CrossAppNode, CrossAppNodeSchema } from "../../crossAppContracts";
import {
crossAppNodeSchemaToDbConcept,
crossAppNodeToDbConcept,
crossAppRelationTypeSchemaToDbConcept,
} from "../crossAppConverters";

const baseSchema: CrossAppNodeSchema = {
Expand Down Expand Up @@ -50,6 +51,17 @@ describe("crossAppNodeSchemaToDbConcept", () => {
});
});

it("maps color to literal_content.color", () => {
const concept = crossAppNodeSchemaToDbConcept({
...baseSchema,
color: "#7DA13E",
});
expect(concept.literal_content).toEqual({
label: "Some concept",
color: "#7DA13E",
});
});

it("writes the label into literal_content as well as the name", () => {
const concept = crossAppNodeSchemaToDbConcept(baseSchema);
expect(concept.name).toBe("Some concept");
Expand Down Expand Up @@ -83,6 +95,36 @@ describe("crossAppNodeSchemaToDbConcept", () => {
});
});

describe("crossAppRelationTypeSchemaToDbConcept", () => {
const relationType = {
...baseSchema,
label: "supports",
complement: "is supported by",
};

it("maps color to literal_content.color", () => {
expect(
crossAppRelationTypeSchemaToDbConcept({ ...relationType, color: "green" })
.literal_content,
).toStrictEqual({
roles: ["source", "destination"],
label: "supports",
complement: "is supported by",
color: "green",
});
});

it("leaves color out of literal_content when the relation type has none", () => {
expect(
crossAppRelationTypeSchemaToDbConcept(relationType).literal_content,
).toStrictEqual({
roles: ["source", "destination"],
label: "supports",
complement: "is supported by",
});
});
});

describe("crossAppNodeToDbConcept", () => {
it("stores node slots as local reference content", () => {
expect(
Expand Down
29 changes: 29 additions & 0 deletions packages/database/src/lib/__tests__/dbToCrossAppConverters.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,20 @@ describe("dbNodeSchemaToCrossApp", () => {
expect(result.metadata).toEqual({ extra: "kept" });
});

it("splits color out of metadata onto the result", () => {
const schema = baseConcept({
literal_content: { color: "#7DA13E", extra: "kept" },
});
const result = dbNodeSchemaToCrossApp({
schema,
spaceMap,
accountMap,
schemaMap: {},
});
expect(result.color).toBe("#7DA13E");
expect(result.metadata).toEqual({ extra: "kept" });
});

it("keeps format undefined when literal_content has no format", () => {
const schema = baseConcept({
literal_content: { extra: "kept" },
Expand Down Expand Up @@ -198,6 +212,21 @@ describe("dbRelationTypeSchemaToCrossApp", () => {
authorId: "account-local-1",
});
});

it("splits color out of metadata onto the result", () => {
const schema = baseConcept({
literal_content: {
roles: ["source", "destination"],
label: "supports",
complement: "is supported by",
color: "green",
extra: "kept",
},
});
const result = dbRelationTypeSchemaToCrossApp(schema, spaceMap, accountMap);
expect(result.color).toBe("green");
expect(result.metadata).toEqual({ extra: "kept" });
});
});

describe("dbRelationTripleSchemaToCrossApp", () => {
Expand Down
6 changes: 4 additions & 2 deletions packages/database/src/lib/crossAppConverters.ts
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,7 @@ export const crossAppNodeSchemaToDbConcept = (
template: node.templateTitle,
template_content: node.template,
format: node.format,
color: node.color,
roles: slots.length > 0 ? slots : undefined,
});
const referenceContent = slots.length ? node.slotDefinitions : undefined;
Expand Down Expand Up @@ -141,11 +142,12 @@ export const crossAppRelationTypeSchemaToDbConcept = (
name: node.label,
author_local_id: node.authorId,
is_schema: true,
literal_content: {
literal_content: filterUndefined({

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

filterUndefined keeps color out of literal_content when the relation type has none, as the node type converter above does for its optional keys. The test "leaves color out of literal_content when the relation type has none" in crossAppConverters.test.ts pins this.

roles: ["source", "destination"],
label: node.label,
complement: node.complement,
},
color: node.color,
}),
created: node.createdAt?.toISOString(),
last_modified: node.modifiedAt?.toISOString(),
});
Expand Down
6 changes: 4 additions & 2 deletions packages/database/src/lib/dbToCrossAppConverters.ts
Original file line number Diff line number Diff line change
Expand Up @@ -168,7 +168,7 @@ export const dbNodeSchemaToCrossApp = ({
string,
number
>;
const { template, template_content, roles, format, ...other } =
const { template, template_content, roles, format, color, ...other } =

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Destructuring color moves it from metadata to the color field. Nothing in apps/ or packages/ reads metadata on a node type or relation type: the only consumer, Roam's importSharedRelations.ts, reads labels, the complement, the template and identity. No producer on main writes a top-level literal_content.color, so no current output changes.

schema.literal_content as Record<string, Json>;
const authorId = accountMap[schema.author_id || 0];
if (authorId === undefined) throw new Error("Missing author");
Expand All @@ -195,6 +195,7 @@ export const dbNodeSchemaToCrossApp = ({
template: template_content as string | undefined,
templateTitle: template as string | undefined,
format: format as string | undefined,
color: color as string | undefined,

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reads only the top-level key. Obsidian rows published before #1633 keep their color in source_data.color, which stays in metadata. Nothing reads CrossApp color yet. The first reader (likely Roam import, TODO at importSharedRelations.ts:73) owns a fallback or backfill, as resolveSchemaFormat did for format.

authorId,
slotDefinitions,
};
Expand Down Expand Up @@ -409,7 +410,7 @@ export const dbRelationTypeSchemaToCrossApp = (
accountMap: Record<number, string>,
): CrossAppRelationTypeSchema => {
// eslint-disable-next-line @typescript-eslint/no-unused-vars
const { roles, label, complement, ...other } =
const { roles, label, complement, color, ...other } =
schema.literal_content as Record<string, Json>;
const authorId = accountMap[schema.author_id || 0];
if (authorId === undefined) throw new Error("Missing author");
Expand All @@ -428,6 +429,7 @@ export const dbRelationTypeSchemaToCrossApp = (
metadata: other,
label: label as string,
complement: complement as string,
color: color as string | undefined,
authorId,
};
};
Expand Down
Loading