@visitportal/spec

The Portal spec. Two endpoints, one manifest, five error codes. Implementable from scratch in any language in under 200 lines.

This package ships: the JSON Schema (manifest.schema.json), 36 conformance vectors (conformance/vectors.json), an ajv-backed validator (runner.ts), and a zero-dependency lean validator (lean-validator.ts) kept in byte-for-byte parity with the ajv one via the self-test.

Tracks monorepo release v0.1.8. Normative spec document: docs/spec-v0.1.8.md.

30-second adopter check

import { runSmokeConformance } from '@visitportal/spec';
const report = await runSmokeConformance('https://my-service.com/portal');
console.log(report);
// { target, manifestOk, manifestErrors, notFoundOk, notFoundDetail }

If manifestOk && notFoundOk, your service passes the v0.1.8 smoke test.

Full offline validation

import { validateAgainstVectors } from '@visitportal/spec';
const report = validateAgainstVectors(myManifest);
// { manifest: {ok}, vectorSuite: {totals, failures} }

Runs the canonical test vectors offline. Zero network. Adopter-facing CI pre-flight.

Manifest schema import

import schema from '@visitportal/spec/schema' assert { type: 'json' };
// → JSON Schema draft-07

Lean validator (zero-dep for visitor SDKs)

import { leanValidate } from '@visitportal/spec/lean-validator';
const r = leanValidate(obj); // { ok: true } | { ok: false, errors: string[] }

Kept in lockstep with the ajv-backed validator via the spec self-test; visitor SDKs can use this to avoid shipping ajv to browsers.

Error codes

import { ERROR_CODES } from '@visitportal/spec';
// ['NOT_FOUND','INVALID_PARAMS','UNAUTHORIZED','RATE_LIMITED','INTERNAL']

Full spec

Frozen normative document: docs/spec-v0.1.8.md. Also rendered at https://visitportal.dev/docs. Repo: https://github.com/0motionguy/portal

License

Apache 2.0 (source) + CC0 (spec documents + vectors.json). See LICENSE.