@nesso-how/schema

Vocabulary-agnostic JSON schema for Nesso 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

npm install @nesso-how/schema

Usage

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.

Compatibility

deserialize requires an explicit envelope version. It replays sequential migrations for released older formats and rejects files from newer formats with NewerGraphFormatError.

Envelope format 1 is the first protected beta baseline. Unversioned alpha documents are outside the compatibility contract.

License

Copyright © 2026 Omar Desogus, Paolo Manfredotti. Licensed under the MIT License. See LICENSE.