@canon-protocol/sdk

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

Installation

npm install @canon-protocol/sdk

Quick start

Parse a Canon document

import { CanonParser } from '@canon-protocol/sdk';

const parser = new CanonParser();
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 { CanonParser, CanonObjectValidator, InMemoryCanonDocumentRepository } from '@canon-protocol/sdk';

const parser = new CanonParser();
const repo = new InMemoryCanonDocumentRepository(parser);

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

// Validate
const validator = new CanonObjectValidator(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, CanonParser, InMemoryCanonDocumentRepository } from '@canon-protocol/sdk';

const parser = new CanonParser();
const repo = new InMemoryCanonDocumentRepository(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, CanonParser, InMemoryCanonDocumentRepository } from '@canon-protocol/sdk';

const parser = new CanonParser();
const repo = new InMemoryCanonDocumentRepository(parser);
// ... load documents into repo ...

const resolver = new ResourceResolver(repo);
const entity = await resolver.resolveEntityAsync('Person', doc);
// entity.uri — fully qualified Canon 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 {
  CanonParser,
  GraphBuilder,
  InMemoryCanonDocumentRepository,
  HttpCanonDocumentRepository,
  CanonObjectValidator,
} from '@canon-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 {
  InMemoryCanonDocumentRepository,   // In-memory — for testing, browser, or single-document work
  FileSystemCanonDocumentRepository,  // Filesystem — scan a directory of .can.yml files (Node.js only)
  HttpCanonDocumentRepository,        // HTTP — fetch packages from publisher domains
} from '@canon-protocol/sdk';

Key modules

Module	Description	Browser-safe
`CanonParser`	Parse `.can.yml` YAML into `CanonDocument` objects	Yes
`CanonObjectValidator`	Validate documents against ontology rules	Yes
`GraphBuilder`	Extract nodes and edges for graph visualization	Yes
`ResourceResolver`	Resolve entity references across imports	Yes
`InMemoryCanonDocumentRepository`	In-memory document store	Yes
`HttpCanonDocumentRepository`	Fetch packages from publisher HTTP endpoints	Yes
`PublisherIndex`	Discover and resolve package versions from publishers	Yes
`FileSystemCanonDocumentRepository`	Read/write `.can.yml` files on disk	No
`CredentialStore`	OS-native credential storage (Keychain, CredMan, etc.)	No

License

Apache-2.0