@kanonak-protocol/sdk

TypeScript SDK for Kanonak Protocol — parse, validate, resolve, and visualize semantic ontologies.

Installation

npm install @kanonak-protocol/sdk

Quick start

Parse a Kanonak document

import { KanonakParser } from '@kanonak-protocol/sdk';

const parser = new KanonakParser();
const doc = parser.parse(yamlContent);

// doc.metadata — package info, publisher, version, imports
// doc.body — all entities (classes, properties, instances) as key-value pairs

Validate

import { KanonakParser, KanonakObjectValidator, InMemoryKanonakDocumentRepository } from '@kanonak-protocol/sdk';

const parser = new KanonakParser();
const repo = new InMemoryKanonakDocumentRepository(parser);

// Load one or more documents
const doc = parser.parse(yamlContent);
await repo.saveDocumentAsync(doc, 'my-ontology');

// Validate
const validator = new KanonakObjectValidator(parser);
const result = await validator.validateAsync(doc, repo);

for (const error of result.errors) {
  console.log(`${error.severity}: ${error.message}`);
}

Extract a graph for visualization

Returns nodes and edges ready for D3, Cytoscape, React Flow, vis.js, or any graph library:

import { GraphBuilder, KanonakParser, InMemoryKanonakDocumentRepository } from '@kanonak-protocol/sdk';

const parser = new KanonakParser();
const repo = new InMemoryKanonakDocumentRepository(parser);
const doc = parser.parse(yamlContent);
await repo.saveDocumentAsync(doc, 'contacts');

const graph = await GraphBuilder.buildFromRepository(repo);

// graph.nodes — each node has: id, label, type, namespace, properties
//   type is one of: Class, ObjectProperty, DatatypeProperty, Instance, Datatype, Unknown
//
// graph.edges — each edge has: source, target, type, label
//   type is one of: instanceOf, subClassOf, domain, range, objectRelationship, subPropertyOf

// Quick single-document graph (no repository needed):
const simpleGraph = GraphBuilder.buildFromDocument(doc);

Resolve entity references across imports

import { ResourceResolver, KanonakParser, InMemoryKanonakDocumentRepository } from '@kanonak-protocol/sdk';

const parser = new KanonakParser();
const repo = new InMemoryKanonakDocumentRepository(parser);
// ... load documents into repo ...

const resolver = new ResourceResolver(repo);
const entity = await resolver.resolveEntityAsync('Person', doc);
// entity.uri — fully qualified Kanonak URI
// entity.entity — the raw entity definition
// entity.isImported — whether it came from an imported package

Browser usage

For browser applications (no Node.js APIs), import from the browser entry point:

import {
  KanonakParser,
  GraphBuilder,
  InMemoryKanonakDocumentRepository,
  HttpKanonakDocumentRepository,
  KanonakObjectValidator,
} from '@kanonak-protocol/sdk/browser';

This includes parsing, validation, graph building, resolution, and HTTP/in-memory repositories. It excludes filesystem access, OS credential stores, and other Node.js-specific modules.

Works with Vite, webpack, esbuild, Rollup, or any browser bundler.

Document repositories

import {
  InMemoryKanonakDocumentRepository,   // In-memory — for testing, browser, or single-document work
  FileSystemKanonakDocumentRepository,  // Filesystem — scan a directory of .kan.yml files (Node.js only)
  HttpKanonakDocumentRepository,        // HTTP — fetch packages from publisher domains
} from '@kanonak-protocol/sdk';

Key modules

| Module | Description | Browser-safe | |--------|-------------|:---:| | KanonakParser | Parse .kan.yml YAML into KanonakDocument objects | Yes | | KanonakObjectValidator | Validate documents against ontology rules | Yes | | GraphBuilder | Extract nodes and edges for graph visualization | Yes | | ResourceResolver | Resolve entity references across imports | Yes | | InMemoryKanonakDocumentRepository | In-memory document store | Yes | | HttpKanonakDocumentRepository | Fetch packages from publisher HTTP endpoints | Yes | | PublisherIndex | Discover and resolve package versions from publishers | Yes | | FileSystemKanonakDocumentRepository | Read/write .kan.yml files on disk | No | | CredentialStore | OS-native credential storage (Keychain, CredMan, etc.) | No |

License

Apache-2.0