@kindgi/schema 0.0.0-bootstrap.0 → 0.1.0

package/dist/zod.js

@@ -0,0 +1,216 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { createRequire } from 'node:module';
+// `createRequire` is Node's ESM-side bridge to CJS-style synchronous
+// resolution. We only use it to resolve the `zod` peer dependency
+// synchronously — the actual JSON conversion function works ESM or CJS.
+const nodeRequire = createRequire(import.meta.url);
+/**
+ * Structural detection. Returns true iff `value` looks like a Zod v4
+ * schema — `_zod` property present AND `~standard` present. Purely
+ * structural: never imports from `zod` at runtime, so the check is safe
+ * even when zod is not installed at all.
+ *
+ * The check is deliberately narrow — a JSON Schema object never has a
+ * `_zod` property, so the two authoring surfaces cannot collide.
+ */
+export function isZodSchema(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const rec = value;
+    return '_zod' in rec && '~standard' in rec && typeof rec._zod === 'object';
+}
+/**
+ * Structural detection for a JSON Schema object. Cheap heuristic — accepts
+ * any object that isn't a Zod schema. JSON Schema validity (Draft 2020-12
+ * compilability) is checked separately by each consumer via Ajv.
+ */
+export function isJsonSchemaObject(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    if (isZodSchema(value))
+        return false;
+    return true;
+}
+/** Return `'zod'` for Zod schemas, `'json-schema'` for JSON Schema objects. */
+export function schemaKindOf(value) {
+    return isZodSchema(value) ? 'zod' : 'json-schema';
+}
+/**
+ * Convert an `AnySchema` to its authoritative JSON Schema wire form.
+ *
+ * - Zod schema → calls `z.toJSONSchema(schema, { io })` (Zod v4 native —
+ *   no third-party `zod-to-json-schema` dependency).
+ * - JSON Schema object → returned as-is.
+ * - Anything else → `err`.
+ *
+ * Conversion failures (unrepresentable Zod types like `.transform()`,
+ * cycles without a registry, function schemas) surface as
+ * `InvalidZodConversionError` with the underlying cause preserved. No
+ * throws escape.
+ *
+ * Zod is imported dynamically the first time a Zod schema flows through:
+ * a workspace that never uses Zod never pays the import cost, and one
+ * that hasn't installed the peer dep gets a clean typed error instead of
+ * a module-resolution crash.
+ */
+export async function toJSONSchema(schema, io) {
+    if (!isZodSchema(schema)) {
+        return { kind: 'ok', value: schema };
+    }
+    const converterResult = await loadZodToJSONSchema();
+    if (converterResult.kind === 'err')
+        return converterResult;
+    try {
+        const converted = converterResult.value(schema, { io });
+        return { kind: 'ok', value: converted };
+    }
+    catch (cause) {
+        return {
+            kind: 'err',
+            error: {
+                code: 'invalid-zod-conversion',
+                message: `z.toJSONSchema() failed: ${cause instanceof Error ? cause.message : String(cause)}`,
+                cause,
+            },
+        };
+    }
+}
+/**
+ * Synchronous variant — for defineTool / defineGuardrail sites that must
+ * stay sync. Requires the caller to have already resolved the converter
+ * (via `loadZodConverter()`) at package init. When Zod is not installed
+ * but a Zod schema is passed, returns `err` with `peer-dep-missing`
+ * distinguishable by its `cause`.
+ */
+export function toJSONSchemaSync(schema, converter, io) {
+    if (!isZodSchema(schema)) {
+        return { kind: 'ok', value: schema };
+    }
+    if (converter === undefined) {
+        return {
+            kind: 'err',
+            error: {
+                code: 'invalid-zod-conversion',
+                message: 'Zod schema passed but the `zod` peer dependency is not installed. ' +
+                    'Install `zod` (>=4.0.0) or author with a JSON Schema object.',
+                cause: new Error('zod peer dep not installed'),
+            },
+        };
+    }
+    try {
+        const converted = converter(schema, { io });
+        return { kind: 'ok', value: converted };
+    }
+    catch (cause) {
+        return {
+            kind: 'err',
+            error: {
+                code: 'invalid-zod-conversion',
+                message: `z.toJSONSchema() failed: ${cause instanceof Error ? cause.message : String(cause)}`,
+                cause,
+            },
+        };
+    }
+}
+/**
+ * Parse a value with a Zod schema through its Standard Schema interface
+ * (`'~standard'.validate`): the parsed value — defaults filled,
+ * transforms and refinements applied — or the issues. What a handler
+ * typed with `z.infer` of the schema expects to receive.
+ */
+export async function parseWithSchema(schema, value) {
+    const standard = schema['~standard'];
+    const result = await standard.validate(value);
+    return result.issues !== undefined
+        ? {
+            kind: 'err',
+            issues: result.issues.map((i) => ({
+                message: i.message,
+                ...(i.path !== undefined && { path: [...i.path] }),
+            })),
+        }
+        : { kind: 'ok', value: result.value };
+}
+let cachedConverter = null;
+/**
+ * Load `z.toJSONSchema` from the `zod` peer dependency. Returns
+ * `undefined` when zod is not installed — callers decide whether that's
+ * an error or a silent no-op (JSON-Schema-only workspaces are legitimate).
+ *
+ * The result is cached — repeat calls resolve synchronously after the
+ * first.
+ */
+export async function loadZodConverter() {
+    if (cachedConverter !== null)
+        return cachedConverter;
+    try {
+        const zod = (await import('zod'));
+        if (typeof zod.toJSONSchema !== 'function') {
+            cachedConverter = undefined;
+            return undefined;
+        }
+        cachedConverter = zod.toJSONSchema;
+        return cachedConverter;
+    }
+    catch {
+        cachedConverter = undefined;
+        return undefined;
+    }
+}
+/**
+ * Synchronous variant of `loadZodConverter`. Uses Node's `createRequire`
+ * so sync authoring surfaces (`defineTool`, `defineGuardrail`) can stay
+ * sync even on their first Zod-authored call. Falls back cleanly when
+ * `zod` isn't installed: returns `undefined` and callers surface the
+ * missing peer dep as a typed error at the boundary.
+ *
+ * Runtime: Node ≥18 (both CJS and ESM entry points to zod resolve
+ * through the same `createRequire` handle). No behavior change for
+ * workspaces that never author with Zod — the first sync call to
+ * `loadZodConverterSync` returns `undefined` cheaply.
+ */
+export function loadZodConverterSync() {
+    if (cachedConverter !== null)
+        return cachedConverter;
+    try {
+        const zod = nodeRequire('zod');
+        if (typeof zod.toJSONSchema !== 'function') {
+            cachedConverter = undefined;
+            return undefined;
+        }
+        cachedConverter = zod.toJSONSchema;
+        return cachedConverter;
+    }
+    catch {
+        cachedConverter = undefined;
+        return undefined;
+    }
+}
+async function loadZodToJSONSchema() {
+    const converter = await loadZodConverter();
+    if (converter === undefined) {
+        return {
+            kind: 'err',
+            error: {
+                code: 'invalid-zod-conversion',
+                message: 'Zod schema passed but the `zod` peer dependency is not installed. ' +
+                    'Install `zod` (>=4.0.0) or author with a JSON Schema object.',
+                cause: new Error('zod peer dep not installed'),
+            },
+        };
+    }
+    return { kind: 'ok', value: converter };
+}
+/**
+ * Test-only: reset the cached converter so tests can exercise both the
+ * peer-dep-present and peer-dep-missing branches. Not part of the public
+ * API — callers outside this package must not depend on this being
+ * present.
+ *
+ * @internal
+ */
+export function __resetZodConverterCacheForTests() {
+    cachedConverter = null;
+}
+//# sourceMappingURL=zod.js.map

package/dist/zod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod.js","sourceRoot":"","sources":["../src/zod.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,64 @@
 {
   "name": "@kindgi/schema",
-  "version": "0.0.0-bootstrap.0",
-  "description": "Placeholder so a trusted publisher can be attached. Releases are published from https://github.com/kindgi/kindgi-sdk with provenance; use 0.1.0 or later.",
+  "version": "0.1.0",
+  "description": "JSON Schema utilities for Kindgi. Loads specs, provides Ajv-based validation, extracts schema versions. Consumers validate incoming data against the wire contracts in @kindgi/specs.",
   "license": "Apache-2.0",
-  "repository": { "type": "git", "url": "git+https://github.com/kindgi/kindgi-sdk.git" }
-}
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kindgi/kindgi-sdk.git",
+    "directory": "packages/schema"
+  },
+  "homepage": "https://github.com/kindgi/kindgi-sdk/tree/main/packages/schema#readme",
+  "bugs": {
+    "url": "https://github.com/kindgi/kindgi-sdk/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "SPEC.md",
+    "type-manifest.json"
+  ],
+  "dependencies": {
+    "@kindgi/types": "0.1.0",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@kindgi/specs": "0.1.0",
+    "@types/node": "^22.10.5",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8",
+    "zod": "^4.6.5"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
+}

package/src/canonical.ts

@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * Canonical JSON serialization — deterministic, reproducible byte-shape
+ * suitable for signing.
+ *
+ * A simplified RFC 8785 (JSON Canonicalization Scheme, JCS) implementation
+ * covering the subset of JSON the framework emits: primitives, arrays, and
+ * objects with sorted string keys.
+ *
+ * Rules:
+ *   - Object keys are sorted lexicographically.
+ *   - `undefined` values are omitted entirely (they're never signed).
+ *   - `null` is preserved.
+ *   - Numbers are serialized via `JSON.stringify` — sufficient for the
+ *     integer + normal-float range the framework emits; if callers ever
+ *     emit denormalized doubles or high-precision values, revisit.
+ *   - Strings use JSON escaping (again via `JSON.stringify`).
+ *   - No whitespace between tokens.
+ *
+ * This lives in the public `@kindgi/schema` package because:
+ *   - Signature verifiers on the SDK side must reproduce the exact
+ *     same bytes to check signatures — moving this to closed code
+ *     would break client-side verify.
+ *   - The algorithm is a public commitment: existing signatures become
+ *     unverifiable if this changes.
+ */
+export function canonicalize(value: unknown): string {
+  if (value === null) return 'null';
+  if (typeof value === 'boolean') return value ? 'true' : 'false';
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) {
+      throw new Error(`Cannot canonicalize non-finite number: ${String(value)}`);
+    }
+    return JSON.stringify(value);
+  }
+  if (typeof value === 'string') return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    const parts = value.map((item) => canonicalize(item));
+    return `[${parts.join(',')}]`;
+  }
+  if (typeof value === 'object') {
+    const obj = value as Readonly<Record<string, unknown>>;
+    const keys = Object.keys(obj)
+      .filter((k) => obj[k] !== undefined)
+      .sort();
+    const parts = keys.map((k) => `${JSON.stringify(k)}:${canonicalize(obj[k])}`);
+    return `{${parts.join(',')}}`;
+  }
+  throw new Error(`Cannot canonicalize value of type ${typeof value}`);
+}

package/src/errors.ts

@@ -0,0 +1,82 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * Typed errors emitted by @kindgi/schema.
+ *
+ * Every error carries:
+ *   - `code`  — machine-readable discriminator for `if (err.code === ...)` matching.
+ *   - `message` — human-readable summary.
+ *   - Case-specific fields (path, id, cause, errors[]).
+ *
+ * Consumers should switch on `code`, not on `message`. Message strings are
+ * documentation-grade but not part of the API contract.
+ */
+export type SchemaError =
+  | SchemaLoadError
+  | SchemaParseError
+  | SchemaCompileError
+  | SchemaNotFoundError
+  | ValidationError
+  | InvalidZodConversionError;
+
+/** Filesystem error while reading a schema file or specs directory. */
+export interface SchemaLoadError {
+  readonly code: 'schema-load-error';
+  readonly message: string;
+  readonly path: string;
+  readonly cause: unknown;
+}
+
+/** JSON parse error while reading a schema file. */
+export interface SchemaParseError {
+  readonly code: 'schema-parse-error';
+  readonly message: string;
+  readonly path: string;
+  readonly cause: unknown;
+}
+
+/**
+ * Ajv rejected the schema during registration/compilation.
+ * Also used when a schema is structurally invalid (missing `$id`, etc).
+ */
+export interface SchemaCompileError {
+  readonly code: 'schema-compile-error';
+  readonly message: string;
+  readonly id: string;
+  readonly cause: unknown;
+}
+
+/** Requested a schema by `$id` that isn't registered. */
+export interface SchemaNotFoundError {
+  readonly code: 'schema-not-found';
+  readonly message: string;
+  readonly id: string;
+}
+
+/**
+ * Data did not validate against the schema. `errors` holds Ajv's error report,
+ * intentionally typed as `unknown[]` — consumers must cast to `AjvError[]` if
+ * they want to inspect fields, so this package doesn't leak the Ajv API shape.
+ */
+export interface ValidationError {
+  readonly code: 'validation-error';
+  readonly message: string;
+  readonly id: string;
+  readonly errors: readonly unknown[];
+}
+
+/**
+ * A Zod schema was passed at an authoring boundary and either
+ *   - the `zod` peer dependency is not installed, or
+ *   - `z.toJSONSchema(schema)` threw (unrepresentable Zod construct —
+ *     e.g. `.transform()` targeting a runtime side-effect, function
+ *     schemas, uncontained cycles).
+ *
+ * `cause` is the underlying Error, preserved for surfacing to the author.
+ */
+export interface InvalidZodConversionError {
+  readonly code: 'invalid-zod-conversion';
+  readonly message: string;
+  readonly cause: unknown;
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+export { canonicalize } from './canonical.js';
+export type {
+  InvalidZodConversionError,
+  SchemaCompileError,
+  SchemaError,
+  SchemaLoadError,
+  SchemaNotFoundError,
+  SchemaParseError,
+  ValidationError,
+} from './errors.js';
+export { compileInlineSchema, createSpecRegistry, loadSpecRegistry } from './registry.js';
+export type { CompiledInlineSchema, SpecRegistry, ValidationErrorLike } from './registry.js';
+export { versionOf } from './version.js';
+export type { SchemaVersion } from './version.js';
+export {
+  isJsonSchemaObject,
+  isZodSchema,
+  loadZodConverter,
+  loadZodConverterSync,
+  parseWithSchema,
+  schemaKindOf,
+  toJSONSchema,
+  toJSONSchemaSync,
+} from './zod.js';
+export type {
+  AnySchema,
+  JSONSchemaObject,
+  SchemaIo,
+  SchemaIssue,
+  SchemaKind,
+  ZodConverter,
+  ZodLikeSchema,
+} from './zod.js';

package/src/registry.test.ts

@@ -0,0 +1,221 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { describe, expect, test } from 'vitest';
+
+import { compileInlineSchema, createSpecRegistry } from './registry.js';
+
+const flowSchema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  $id: 'https://kindgi.com/schemas/v1/test-flow.schema.json',
+  $comment: 'schema-version: 1.0.0',
+  title: 'TestGraph',
+  type: 'object',
+  additionalProperties: false,
+  required: ['id', 'nodes'],
+  properties: {
+    id: { type: 'string', minLength: 1 },
+    nodes: { type: 'array', items: { type: 'string' } },
+  },
+};
+
+const toolSchema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  $id: 'https://kindgi.com/schemas/v1/test-tool.schema.json',
+  $comment: 'schema-version: 1.0.0',
+  title: 'TestTool',
+  type: 'object',
+  additionalProperties: false,
+  required: ['id'],
+  properties: {
+    id: { type: 'string' },
+  },
+};
+
+// A pack schema that references the tool schema by $id — this exercises
+// cross-schema $ref resolution, the whole reason for two-pass registration.
+const packSchema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  $id: 'https://kindgi.com/schemas/v1/test-pack.schema.json',
+  $comment: 'schema-version: 1.0.0',
+  title: 'TestPack',
+  type: 'object',
+  additionalProperties: false,
+  required: ['id', 'tools'],
+  properties: {
+    id: { type: 'string' },
+    tools: {
+      type: 'array',
+      items: { $ref: 'https://kindgi.com/schemas/v1/test-tool.schema.json' },
+    },
+  },
+};
+
+describe('createSpecRegistry', () => {
+  test('empty registry succeeds with no schemas', () => {
+    const result = createSpecRegistry([]);
+    expect(result.kind).toBe('ok');
+    if (result.kind === 'ok') {
+      expect(result.value.ids()).toEqual([]);
+    }
+  });
+
+  test('registers schemas and exposes their $ids', () => {
+    const result = createSpecRegistry([flowSchema, toolSchema]);
+    expect(result.kind).toBe('ok');
+    if (result.kind === 'ok') {
+      expect(result.value.ids()).toEqual([
+        'https://kindgi.com/schemas/v1/test-flow.schema.json',
+        'https://kindgi.com/schemas/v1/test-tool.schema.json',
+      ]);
+    }
+  });
+
+  test('rejects a schema missing $id', () => {
+    const result = createSpecRegistry([{ type: 'object' }]);
+    expect(result.kind).toBe('err');
+    if (result.kind === 'err') {
+      expect(result.error.code).toBe('schema-compile-error');
+      expect(result.error.message).toContain('$id');
+    }
+  });
+
+  test('rejects a non-object schema', () => {
+    const result = createSpecRegistry(['not-a-schema']);
+    expect(result.kind).toBe('err');
+    if (result.kind === 'err') {
+      expect(result.error.code).toBe('schema-compile-error');
+    }
+  });
+
+  test('resolves cross-schema $refs when all schemas are registered together', () => {
+    const result = createSpecRegistry([toolSchema, packSchema]);
+    expect(result.kind).toBe('ok');
+    if (result.kind === 'ok') {
+      const packOk = result.value.validate('https://kindgi.com/schemas/v1/test-pack.schema.json', {
+        id: 'p',
+        tools: [{ id: 't1' }],
+      });
+      expect(packOk.kind).toBe('ok');
+    }
+  });
+});
+
+describe('compileInlineSchema', () => {
+  test('compiles a minimal valid schema', () => {
+    const r = compileInlineSchema({ type: 'object' });
+    expect(r.kind).toBe('ok');
+  });
+
+  test('returns err on a schema with an unknown keyword (strict mode)', () => {
+    const r = compileInlineSchema({ thisIsNotAJsonSchemaKeyword: true });
+    expect(r.kind).toBe('err');
+    if (r.kind === 'err') expect(r.error.code).toBe('schema-compile-error');
+  });
+
+  test('returns err on a non-object schema', () => {
+    const r = compileInlineSchema('not-a-schema');
+    expect(r.kind).toBe('err');
+    if (r.kind === 'err') expect(r.error.code).toBe('schema-compile-error');
+  });
+
+  test('validate() accepts conforming data', () => {
+    const r = compileInlineSchema({
+      type: 'object',
+      required: ['name'],
+      additionalProperties: false,
+      properties: { name: { type: 'string' } },
+    });
+    expect(r.kind).toBe('ok');
+    if (r.kind !== 'ok') return;
+    const ok = r.value.validate({ name: 'alice' });
+    expect(ok.kind).toBe('ok');
+  });
+
+  test('validate() rejects data that violates the schema', () => {
+    const r = compileInlineSchema({
+      type: 'object',
+      required: ['name'],
+      additionalProperties: false,
+      properties: { name: { type: 'string' } },
+    });
+    if (r.kind !== 'ok') throw new Error('compile failed');
+    const bad = r.value.validate({});
+    expect(bad.kind).toBe('err');
+    if (bad.kind === 'err') expect(bad.error.code).toBe('validation-error');
+  });
+
+  test('validate() returns the input value on success (identity, cast to T)', () => {
+    const r = compileInlineSchema({ type: 'object' });
+    if (r.kind !== 'ok') throw new Error('compile failed');
+    const input = { hello: 'world' };
+    const ok = r.value.validate<{ hello: string }>(input);
+    if (ok.kind === 'ok') {
+      expect(ok.value).toBe(input);
+      expect(ok.value.hello).toBe('world');
+    }
+  });
+
+  test('source is round-trippable', () => {
+    const schema = { type: 'object' };
+    const r = compileInlineSchema(schema);
+    if (r.kind !== 'ok') throw new Error('compile failed');
+    expect(r.value.source).toBe(schema);
+  });
+});
+
+describe('SpecRegistry.validate', () => {
+  test('accepts data that matches the schema', () => {
+    const setup = createSpecRegistry([flowSchema]);
+    if (setup.kind === 'err') throw new Error('setup failed');
+    const result = setup.value.validate('https://kindgi.com/schemas/v1/test-flow.schema.json', {
+      id: 'g1',
+      nodes: ['a', 'b'],
+    });
+    expect(result.kind).toBe('ok');
+  });
+
+  test('rejects data that fails the schema with a validation-error', () => {
+    const setup = createSpecRegistry([flowSchema]);
+    if (setup.kind === 'err') throw new Error('setup failed');
+    const result = setup.value.validate('https://kindgi.com/schemas/v1/test-flow.schema.json', {
+      id: '',
+      nodes: 'not-an-array',
+    });
+    expect(result.kind).toBe('err');
+    if (result.kind === 'err' && result.error.code === 'validation-error') {
+      expect(result.error.errors.length).toBeGreaterThan(0);
+    } else {
+      throw new Error('expected validation-error');
+    }
+  });
+
+  test('returns schema-not-found for an unknown $id', () => {
+    const setup = createSpecRegistry([flowSchema]);
+    if (setup.kind === 'err') throw new Error('setup failed');
+    const result = setup.value.validate('https://kindgi.com/schemas/v1/nope.schema.json', {});
+    expect(result.kind).toBe('err');
+    if (result.kind === 'err') {
+      expect(result.error.code).toBe('schema-not-found');
+    }
+  });
+});
+
+describe('SpecRegistry.getSchema', () => {
+  test('returns the raw schema for a known $id', () => {
+    const setup = createSpecRegistry([flowSchema]);
+    if (setup.kind === 'err') throw new Error('setup failed');
+    const result = setup.value.getSchema('https://kindgi.com/schemas/v1/test-flow.schema.json');
+    expect(result.kind).toBe('ok');
+    if (result.kind === 'ok') {
+      expect(result.value).toBe(flowSchema);
+    }
+  });
+
+  test('returns schema-not-found for an unknown $id', () => {
+    const setup = createSpecRegistry([]);
+    if (setup.kind === 'err') throw new Error('setup failed');
+    const result = setup.value.getSchema('https://kindgi.com/schemas/v1/nope.schema.json');
+    expect(result.kind).toBe('err');
+  });
+});