@nesso-how/schema 0.1.0-alpha.34

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Omar Desogus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,32 @@
+# @nesso-how/schema
+
+Vocabulary-agnostic JSON schema for [Nesso](https://nesso.how) knowledge graph documents.
+
+Defines the on-disk envelope (`version`, optional `vocabulary`, `name`, `concepts`, `relations`, optional `meta`) and structural validation on parse. Relation type ids and concept `data` shapes are opaque here — vocabulary packages add typed aliases and extra validation.
+
+## Install
+
+```bash
+npm install @nesso-how/schema
+```
+
+## Usage
+
+```ts
+import { GRAPH_FORMAT_VERSION, deserialize, serialize, type GraphDocument } from '@nesso-how/schema'
+
+const json = serialize({
+  name: 'My graph',
+  vocabulary: { id: '@nesso-how/vocab-learning', version: '0.1.0' },
+  concepts: [{ id: 'n1', label: 'Idea', x: 0, y: 0 }],
+  relations: [],
+})
+const doc: GraphDocument = deserialize(json)
+// doc.version === GRAPH_FORMAT_VERSION
+```
+
+Vocabulary-specific serialization (e.g. Nesso Learning Vocabulary) lives in [`@nesso-how/vocab-learning`](../vocab-learning/README.md).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+/** Current on-disk graph document schema version. Bump only when the envelope shape changes. */
+export declare const GRAPH_FORMAT_VERSION: 1;
+export interface GraphConcept<D extends Record<string, unknown> = Record<string, unknown>> {
+    id: string;
+    label: string;
+    x: number;
+    y: number;
+    data?: D;
+}
+export interface GraphRelation<D extends Record<string, unknown> = Record<string, unknown>> {
+    id: string;
+    source: string;
+    target: string;
+    type?: string;
+    data?: D;
+}
+export interface GraphDocument<NC extends Record<string, unknown> = Record<string, unknown>, RE extends Record<string, unknown> = Record<string, unknown>, M extends Record<string, unknown> = Record<string, unknown>> {
+    /** File format version — always {@link GRAPH_FORMAT_VERSION} for the current schema. */
+    version: typeof GRAPH_FORMAT_VERSION;
+    /**
+     * Vocabulary this graph was built with: its id (e.g. `@nesso-how/vocab-learning`)
+     * and normative version. Opaque to schema, which only round-trips the reference.
+     */
+    vocabulary?: {
+        id: string;
+        version: string;
+    };
+    /** Internal graph id (desktop sync); omitted in manual exports. */
+    id?: string;
+    /** Last save time (Unix ms); desktop sync metadata. */
+    updatedAt?: number;
+    name: string;
+    concepts: GraphConcept<NC>[];
+    relations: GraphRelation<RE>[];
+    meta?: M;
+}
+/** Graph payload for {@link serialize} — format version is injected by the serializer. */
+export type GraphDocumentInput<NC extends Record<string, unknown> = Record<string, unknown>, RE extends Record<string, unknown> = Record<string, unknown>, M extends Record<string, unknown> = Record<string, unknown>> = Omit<GraphDocument<NC, RE, M>, 'version'>;
+/** Serialize a graph document to JSON with keys in a stable, human-readable order. */
+export declare function serialize<NC extends Record<string, unknown>, RE extends Record<string, unknown>, M extends Record<string, unknown>>(doc: GraphDocumentInput<NC, RE, M>): string;
+/**
+ * Parse and structurally validate a graph document. Files are user-editable (and
+ * importable from anywhere), so each element is checked before it can reach
+ * the store: a concept without a valid id/position crashes the canvas and would
+ * then be re-persisted. Vocabulary-specific normalization is the caller's responsibility.
+ */
+export declare function deserialize<NC extends Record<string, unknown> = Record<string, unknown>, RE extends Record<string, unknown> = Record<string, unknown>, M extends Record<string, unknown> = Record<string, unknown>>(json: string): GraphDocument<NC, RE, M>;

package/dist/index.js

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: MIT
+/** Current on-disk graph document schema version. Bump only when the envelope shape changes. */
+export const GRAPH_FORMAT_VERSION = 1;
+/** Serialize a graph document to JSON with keys in a stable, human-readable order. */
+export function serialize(doc) {
+    const { vocabulary, id, updatedAt, name, concepts, relations, meta } = doc;
+    return JSON.stringify({
+        version: GRAPH_FORMAT_VERSION,
+        ...(vocabulary !== undefined && { vocabulary }),
+        ...(id !== undefined && { id }),
+        ...(updatedAt !== undefined && { updatedAt }),
+        name,
+        concepts,
+        relations,
+        ...(meta !== undefined && { meta }),
+    }, null, 2);
+}
+function asRecord(value) {
+    return typeof value === 'object' && value !== null ? value : null;
+}
+/**
+ * Parse and structurally validate a graph document. Files are user-editable (and
+ * importable from anywhere), so each element is checked before it can reach
+ * the store: a concept without a valid id/position crashes the canvas and would
+ * then be re-persisted. Vocabulary-specific normalization is the caller's responsibility.
+ */
+export function deserialize(json) {
+    const data = JSON.parse(json);
+    const root = asRecord(data);
+    if (!root || !Array.isArray(root.concepts) || !Array.isArray(root.relations)) {
+        throw new Error('Invalid Nesso graph document: missing concepts or relations array');
+    }
+    if (typeof root.version === 'number' && root.version !== GRAPH_FORMAT_VERSION) {
+        throw new Error(`Unsupported Nesso graph document version: ${root.version}`);
+    }
+    const concepts = root.concepts.map((value, i) => {
+        const concept = asRecord(value);
+        if (!concept ||
+            typeof concept.id !== 'string' ||
+            concept.id === '' ||
+            typeof concept.label !== 'string' ||
+            typeof concept.x !== 'number' ||
+            !Number.isFinite(concept.x) ||
+            typeof concept.y !== 'number' ||
+            !Number.isFinite(concept.y)) {
+            throw new Error(`Invalid Nesso graph document: concept ${i} is missing a valid id, label, or position`);
+        }
+        return concept;
+    });
+    const relations = root.relations.map((value, i) => {
+        const relation = asRecord(value);
+        if (!relation ||
+            typeof relation.id !== 'string' ||
+            typeof relation.source !== 'string' ||
+            typeof relation.target !== 'string') {
+            throw new Error(`Invalid Nesso graph document: relation ${i} is missing id, source or target`);
+        }
+        return relation;
+    });
+    return {
+        ...root,
+        version: GRAPH_FORMAT_VERSION,
+        concepts,
+        relations,
+    };
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@nesso-how/schema",
+  "version": "0.1.0-alpha.34",
+  "description": "Nesso knowledge graph document schema — JSON serialize/deserialize",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nesso-how/nesso",
+    "directory": "packages/schema"
+  },
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "devDependencies": {
+    "typescript": "~5.8.3"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "dev": "tsc --watch"
+  }
+}