@kgdiff/core 0.1.0 → 0.3.0

package/schema/graph.v1.json

@@ -0,0 +1,154 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://cdn.jsdelivr.net/npm/@kgdiff/core/schema/graph.v1.json",
+  "title": "kgdiff graph, version 1",
+  "description": "A graph in kgdiff JSON, as graphToJSON and `kgdiff apply` write it. kgdiff also reads looser JSON (other field names, numeric ids, loose fields as attributes); this schema describes the canonical form. See https://github.com/iiwish/kgdiff/blob/main/docs/formats.md#kgdiff-json",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "The URI of this schema, for editors."
+    },
+    "format": {
+      "const": "kgdiff.graph",
+      "description": "Format marker. Optional, together with version; it makes readers recognise the file for certain."
+    },
+    "version": {
+      "const": 1,
+      "description": "Version of the format (not of the graph: that is meta.version). Readers reject versions they do not support."
+    },
+    "meta": { "$ref": "#/$defs/meta" },
+    "nodes": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/node" }
+    },
+    "edges": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/edge" }
+    }
+  },
+  "required": ["nodes"],
+  "dependentRequired": {
+    "format": ["version"],
+    "version": ["format"]
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "A node id: an IRI, a CURIE such as GO:0008150, or any non-empty string."
+    },
+    "ids": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/id" }
+    },
+    "strings": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "attrs": {
+      "type": "object",
+      "description": "Any other values, by name: strings, numbers, booleans, null, arrays and objects."
+    },
+    "meta": {
+      "type": "object",
+      "description": "About the graph. Other keys are kept as they are.",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Shown in headers and titles."
+        },
+        "version": {
+          "type": "string",
+          "description": "The version of the graph, shown in headers and titles."
+        },
+        "source": {
+          "type": "string",
+          "description": "Where the graph came from: a file name, a URL…"
+        },
+        "predicateLabels": {
+          "type": "object",
+          "additionalProperties": { "type": "string" },
+          "description": "Display names of relations, by predicate."
+        }
+      }
+    },
+    "node": {
+      "type": "object",
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "label": {
+          "type": "string",
+          "description": "The display name; defaults to the id. A changed label is a rename."
+        },
+        "type": {
+          "anyOf": [{ "type": "string" }, { "$ref": "#/$defs/strings" }],
+          "description": "A type, or several (class, category, rdf:type)."
+        },
+        "types": {
+          "$ref": "#/$defs/strings",
+          "description": "The types, as graphToJSON writes them. Use type or types, not both."
+        },
+        "aliases": {
+          "$ref": "#/$defs/strings",
+          "description": "Synonyms."
+        },
+        "attrs": { "$ref": "#/$defs/attrs" },
+        "deprecated": {
+          "type": "boolean",
+          "description": "True for an obsolete node that is still present."
+        },
+        "replaces": {
+          "$ref": "#/$defs/ids",
+          "description": "Ids of the nodes this one replaces in the other version: a strong merge hint."
+        },
+        "replacedBy": {
+          "$ref": "#/$defs/ids",
+          "description": "Ids of the nodes that replace this one: a strong merge hint."
+        },
+        "implicit": {
+          "type": "boolean",
+          "description": "Written by graphToJSON for a node created at an edge end the graph does not describe."
+        },
+        "position": {
+          "type": "object",
+          "properties": {
+            "x": { "type": "number" },
+            "y": { "type": "number" }
+          },
+          "required": ["x", "y"],
+          "additionalProperties": false,
+          "description": "A pinned layout position. Never part of the diff."
+        }
+      },
+      "required": ["id"],
+      "dependentSchemas": {
+        "types": { "type": "object", "properties": { "type": false } }
+      },
+      "additionalProperties": false
+    },
+    "edge": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/id",
+          "description": "An explicit edge id, used for identity only when edges are identified by id."
+        },
+        "source": { "$ref": "#/$defs/id" },
+        "target": { "$ref": "#/$defs/id" },
+        "predicate": {
+          "type": "string",
+          "description": "The relation: an IRI, a CURIE or a plain name. Defaults to the empty string."
+        },
+        "label": {
+          "type": "string",
+          "description": "Display label of the relation; defaults to a readable form of the predicate."
+        },
+        "attrs": { "$ref": "#/$defs/attrs" }
+      },
+      "required": ["source", "target"],
+      "additionalProperties": false
+    }
+  }
+}

package/src/graph-json.ts

@@ -35,8 +35,9 @@ export function edgeToJSON(
 }
 
 /**
- * Canonical JSON form of a graph: nodes sorted by id, edges by key, defaults omitted,
- * attribute keys sorted. `normalize(graphToJSON(g))` rebuilds `g` (positions excepted).
+ * Canonical JSON form of a graph: the `kgdiff.graph` version 1 marker, nodes sorted by id,
+ * edges by key, defaults omitted, attribute keys sorted. `normalize(graphToJSON(g))` rebuilds
+ * `g` (positions excepted).
  */
 export function graphToJSON(graph: KGraph): GraphJSON {
   const nodes = [...graph.nodes.values()]
@@ -45,7 +46,10 @@ export function graphToJSON(graph: KGraph): GraphJSON {
   const edges = [...graph.edges.values()]
     .sort((a, b) => compareStrings(a.key, b.key))
     .map((edge) => edgeToJSON(edge));
-  return Object.keys(graph.meta).length ? { meta: graph.meta, nodes, edges } : { nodes, edges };
+  const marker = { format: 'kgdiff.graph', version: 1 } as const;
+  return Object.keys(graph.meta).length
+    ? { ...marker, meta: graph.meta, nodes, edges }
+    : { ...marker, nodes, edges };
 }
 
 /**

package/src/index.ts

@@ -68,9 +68,11 @@ export function resolveOptions(options?: DiffOptions): ResolvedDiffOptions {
  *
  * Labels default to ids; sets are sorted and de-duplicated; duplicate nodes are merged;
  * parallel edges are keyed `#2`, `#3`… in content order; dangling endpoints follow
- * `danglingEdges` (default `create`). Problems are reported in `issues`.
+ * `danglingEdges` (default `create`). Problems are reported in `issues`. The kgdiff JSON
+ * marker (`format: 'kgdiff.graph'`, `version: 1`) is optional.
  *
- * @throws KgdiffError `invalid-input` for malformed input, `dangling-edge` (policy `error`).
+ * @throws KgdiffError `invalid-input` for malformed input, `dangling-edge` (policy `error`),
+ *   `unsupported-version` for another kgdiff format or graph version.
  */
 export function normalize(input: GraphInput, options?: NormalizeOptions): KGraph {
   return normalizeGraph(input, options);
@@ -129,7 +131,10 @@ export function hashGraph(graph: KGraph): string {
   return hash(graph);
 }
 
-/** Canonical JSON form of a graph (sorted, defaults omitted). Accepted by `normalize`. */
+/**
+ * Canonical JSON form of a graph: kgdiff JSON with its `kgdiff.graph` version 1 marker, sorted,
+ * defaults omitted. Accepted by `normalize`.
+ */
 export function graphToJSON(graph: KGraph): GraphJSON {
   return toGraphJSON(graph);
 }

package/src/normalize.ts

@@ -77,6 +77,29 @@ function fail(message: string, details?: Record<string, unknown>): never {
   throw new KgdiffError('invalid-input', message, details);
 }
 
+/**
+ * Checks the optional kgdiff JSON marker. Only `kgdiff.*` formats are kgdiff's: a `format`
+ * field with any other value belongs to someone else and is ignored, like other unknown keys.
+ */
+function checkFormat(input: Readonly<Record<string, unknown>>): void {
+  const { format, version } = input;
+  if (typeof format !== 'string' || !format.startsWith('kgdiff.')) return;
+  if (format !== 'kgdiff.graph') {
+    throw new KgdiffError(
+      'unsupported-version',
+      `Expected a kgdiff graph (format "kgdiff.graph"), got format "${format}"`,
+      { format },
+    );
+  }
+  if (version !== 1) {
+    throw new KgdiffError(
+      'unsupported-version',
+      `Unsupported graph version ${String(version)}; this reader supports version 1`,
+      { version },
+    );
+  }
+}
+
 /** Ids are strings; finite numbers are accepted and stringified. Empty → undefined. */
 function coerceId(value: unknown): Id | undefined {
   if (typeof value === 'string') return value === '' ? undefined : value;
@@ -339,10 +362,14 @@ export function isKGraph(value: unknown): value is KGraph {
  *   field-wise. Both cases record a `duplicate-edge` issue.
  * - Dangling endpoints (`danglingEdges`, default `create`): `create` adds an implicit node,
  *   `drop` discards the edge, `error` throws `KgdiffError('dangling-edge')`.
+ * - The kgdiff JSON marker is optional; a `kgdiff.*` format other than `kgdiff.graph`, or a
+ *   version other than 1, is rejected.
  *
- * @throws KgdiffError `invalid-input` for malformed input, `dangling-edge` (policy `error`).
+ * @throws KgdiffError `invalid-input` for malformed input, `dangling-edge` (policy `error`),
+ *   `unsupported-version` for another kgdiff format or graph version.
  */
 export function normalize(input: GraphInput, options: NormalizeOptions = {}): KGraph {
+  if (isRecord(input)) checkFormat(input);
   if (!isRecord(input) || !Array.isArray(input.nodes)) {
     fail('normalize expects a graph of the form { nodes: [...], edges: [...] }');
   }

package/src/types.ts

@@ -105,6 +105,12 @@ export interface GraphMeta {
 }
 
 export interface GraphInput {
+  /**
+   * Format marker of kgdiff JSON, as `graphToJSON` writes it. Optional; when present, `version`
+   * must be 1 (anything else is rejected with `unsupported-version`).
+   */
+  readonly format?: 'kgdiff.graph';
+  readonly version?: 1;
   readonly nodes: readonly NodeInput[];
   readonly edges: readonly EdgeInput[];
   readonly meta?: GraphMeta;
@@ -618,7 +624,10 @@ export interface DiffResult {
 
 // ─── JSON transport ─────────────────────────────────────────────────────────
 
+/** kgdiff JSON (docs/formats.md §kgdiff JSON), schema `schema/graph.v1.json`. */
 export interface GraphJSON {
+  readonly format: 'kgdiff.graph';
+  readonly version: 1;
   readonly meta?: GraphMeta;
   readonly nodes: readonly NodeJSON[];
   readonly edges: readonly EdgeJSON[];