Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* OpenAPI 3.0.3 compatibility for JSON Schema produced against draft 2020-12.
*
* PortOS publishes 3.0.3 rather than 3.1 because the documents are consumed by
* agent tooling (tool-schema converters, validators, generators) whose 3.1
* support is still thin, while 3.0.3 is universally understood. The gap is
* narrow but real: `zodToOpenApiSchema` emits draft 2020-12, which uses
* constructs 3.0.3 rejects outright. `toOpenApi30Schema` rewrites them so a
* document labeled 3.0.3 actually validates as 3.0.3.
*
* APPLY THIS ONLY AT THE OPENAPI DOCUMENT BOUNDARY (`openapiSpec.js`), never
* inside `zodToOpenApiSchema` itself. Three other surfaces consume that helper's
* output as ORDINARY JSON SCHEMA — the AsyncAPI document's `payload`, the CoS
* provider tool definitions, and the semantic tool resource — and these rewrites
* are wrong there. `exclusiveMinimum: true` is a draft-4 spelling that a JSON
* Schema validator reads as a type error and ignores, silently widening
* `value > 0` to `value >= 0`; `nullable: true` is not a JSON Schema keyword at
* all, so the null branch is simply lost. Both turn a correct contract into a
* quietly wrong one.
*
* Rewrites applied:
* - a `null` branch in `anyOf`/`oneOf` becomes `nullable: true` on the
* surviving branches (3.0 has no `null` type); a sole survivor is inlined,
* with the PARENT's keywords winning any collision so an inner constraint
* can't widen an outer one
* - `type: ['string', 'null']` and a bare `type: 'null'` collapse the same way
* - numeric `exclusiveMinimum`/`exclusiveMaximum` become the 3.0 boolean form
* paired with `minimum`/`maximum`
* - `const: x` becomes `enum: [x]`
* - `examples: [...]` becomes `example: examples[0]`
* - `prefixItems` (a tuple) becomes `items: { anyOf: [...] }` plus
* `minItems`/`maxItems`, preserving arity and member types even though 3.0.3
* cannot express positional typing
* - `$schema` and `propertyNames` (no 3.0 equivalent) are dropped
*
* `$ref`/`$defs` are REFUSED rather than mangled — see `assertNoReferences`.
*
* KNOWN LOSSY CASE: 3.0's `nullable` only qualifies a `type` in the same Schema
* Object, so a nullable COMPOSED schema (`z.intersection(...).nullable()`, which
* collapses to `{allOf: [...], nullable: true}`) cannot express its null branch —
* 3.0 has no spelling for it. The flag is emitted anyway as the conventional
* best effort. No registered contract composes a nullable schema today.
*/
import { isPlainObject } from './objects.js';
/** The OpenAPI version every PortOS-generated document declares. */
export const OPENAPI_VERSION = '3.0.3';
// A `null` union member, in either the pre-conversion (`{type:'null'}`) or
// post-conversion (`{enum:[null], nullable:true}`) spelling — the second appears
// when a nested branch was converted before its parent union was collapsed.
// Only a BARE marker counts; a null branch carrying other keywords is left alone
// rather than silently dropping those keywords.
const NULL_MARKER_KEYS = new Set(['type', 'enum', 'nullable']);
const isNullBranch = (branch) => {
if (!isPlainObject(branch)) return false;
const keys = Object.keys(branch);
if (!keys.every((key) => NULL_MARKER_KEYS.has(key))) return false;
if (branch.type === 'null') return true;
// `{type:'string', nullable:true}` shares the key set but is not a null
// marker — a converted marker carries no type at all.
return branch.type === undefined
&& branch.nullable === true
&& Array.isArray(branch.enum)
&& branch.enum.every((value) => value === null);
};
const collapseNullableUnion = (schema, keyword) => {
const branches = schema[keyword];
if (!Array.isArray(branches) || !branches.some(isNullBranch)) return schema;
const survivors = branches.filter((branch) => !isNullBranch(branch));
const { [keyword]: _dropped, ...rest } = schema;
if (survivors.length === 0) return { ...rest, nullable: true };
// A single survivor inlines. The parent's own keywords are applied LAST so a
// branch constraint cannot overwrite (and possibly widen) an outer one, and
// an outer `description` survives an inner one.
if (survivors.length === 1) return { ...survivors[0], ...rest, nullable: true };
// Several survivors stay a union; 3.0 has no way to mark the union itself
// nullable, so each branch carries the flag.
return { ...rest, [keyword]: survivors.map((branch) => ({ ...branch, nullable: true })) };
};
const collapseNullableType = (schema) => {
if (schema.type === 'null') {
const { type: _dropped, ...rest } = schema;
// In 3.0 `nullable` only qualifies a `type` declared alongside it, so a
// null-only schema needs `enum: [null]` to actually accept null.
return { ...rest, ...(rest.enum === undefined ? { enum: [null] } : {}), nullable: true };
}
if (!Array.isArray(schema.type)) return schema;
const types = schema.type.filter((type) => type !== 'null');
const { type: _dropped, ...rest } = schema;
const nullable = types.length !== schema.type.length ? { nullable: true } : {};
// 3.0 allows exactly one `type`; a genuine multi-type union has no 3.0
// equivalent, so drop the constraint rather than emit an invalid document.
return types.length === 1 ? { ...rest, type: types[0], ...nullable } : { ...rest, ...nullable };
};
// Draft 2020-12 makes these numeric; 3.0.3 keeps draft-4's boolean flag beside
// `minimum`/`maximum`.
const convertExclusiveBounds = (schema) => {
const out = { ...schema };
if (typeof out.exclusiveMinimum === 'number') {
out.minimum = out.exclusiveMinimum;
out.exclusiveMinimum = true;
}
if (typeof out.exclusiveMaximum === 'number') {
out.maximum = out.exclusiveMaximum;
out.exclusiveMaximum = true;
}
return out;
};
// 3.0.3 has no positional array typing. `items: {anyOf: [...members]}` plus a
// fixed arity keeps every member type and the length, which is strictly better
// than dropping to "array of anything".
const convertTuple = (schema) => {
const { prefixItems, ...rest } = schema;
if (!Array.isArray(prefixItems)) return rest;
// A rest schema (`z.tuple([...]).rest(z.number())`) types every member past
// the prefix, so it joins the union rather than being overwritten by it —
// otherwise a valid tail element is rejected by the published contract.
const members = rest.items === undefined ? prefixItems : [...prefixItems, rest.items];
return {
...rest,
items: members.length === 1 ? members[0] : { anyOf: members },
minItems: rest.minItems ?? prefixItems.length,
// An open-ended rest means extra members are allowed, so only a closed
// tuple gets a maximum.
...(rest.items === undefined ? { maxItems: rest.maxItems ?? prefixItems.length } : {}),
};
};
/**
* Refuse a schema carrying `$ref`/`$defs` rather than publishing a broken one.
*
* Zod emits `$ref: '#'` for a self-recursive contract. Inlined into a path item
* that `#` resolves to the ROOT OPENAPI DOCUMENT, not the schema — a silently
* broken pointer for every consumer — and in 3.0.3 a `$ref` ignores its
* siblings, so an adjacent `nullable` is dropped too. Correctly supporting this
* means hoisting `$defs` into `#/components/schemas` and rewriting pointers;
* until a contract actually needs that, failing loudly at build time beats
* shipping a document whose references don't resolve.
*/
const assertNoReferences = (schema) => {
if (schema.$ref !== undefined || schema.$defs !== undefined) {
throw new Error(
'OpenAPI 3.0.3 downgrade cannot represent a $ref/$defs schema (recursive or reused Zod contract). '
+ 'Inline the contract, or add $defs hoisting to openapiDowngrade.js before registering it.',
);
}
};
// Keywords with no 3.0.3 Schema Object equivalent. The OAS 3.0 meta-schema
// CLOSES the Schema Object (`additionalProperties: false` plus an `^x-` escape
// hatch), so leaving any one of these in makes the whole document invalid — not
// just the subschema. `propertyNames`/`patternProperties` come from `z.record()`
// and their key constraints are not expressible in 3.0; `contentEncoding` /
// `contentMediaType` come from `z.base64()` / `z.file()`, whose `format` and
// `pattern` siblings survive and carry most of the meaning.
const UNSUPPORTED_KEYWORDS = ['$schema', 'propertyNames', 'patternProperties', 'contentEncoding', 'contentMediaType'];
const NESTED_SCHEMA_KEYS = ['items', 'not', 'additionalProperties'];
const NESTED_SCHEMA_LIST_KEYS = ['anyOf', 'oneOf', 'allOf'];
/**
* Rewrite a draft-2020-12 JSON Schema into the OpenAPI 3.0.3 Schema Object
* dialect. Returns a new object; the input is never mutated.
*
* @throws when the schema uses `$ref`/`$defs` (see `assertNoReferences`).
*/
export const toOpenApi30Schema = (schema) => {
if (Array.isArray(schema)) return schema.map(toOpenApi30Schema);
if (!isPlainObject(schema)) return schema;
assertNoReferences(schema);
let out = { ...schema };
for (const keyword of UNSUPPORTED_KEYWORDS) delete out[keyword];
if (out.const !== undefined) {
out.enum = [out.const];
delete out.const;
}
if (Array.isArray(out.examples)) {
if (out.example === undefined && out.examples.length > 0) out.example = out.examples[0];
delete out.examples;
}
out = convertTuple(out);
out = convertExclusiveBounds(out);
out = collapseNullableType(out);
for (const keyword of ['anyOf', 'oneOf']) out = collapseNullableUnion(out, keyword);
for (const key of NESTED_SCHEMA_KEYS) {
if (out[key] !== undefined && typeof out[key] !== 'boolean') out[key] = toOpenApi30Schema(out[key]);
}
for (const key of NESTED_SCHEMA_LIST_KEYS) {
if (Array.isArray(out[key])) out[key] = out[key].map(toOpenApi30Schema);
}
if (isPlainObject(out.properties)) {
out.properties = Object.fromEntries(
Object.entries(out.properties).map(([name, value]) => [name, toOpenApi30Schema(value)]),
);
}
// Converting the branches above can turn a nested `{type:'null'}` into the
// `{nullable:true}` marker, exposing a collapse the first pass couldn't see.
for (const keyword of ['anyOf', 'oneOf']) out = collapseNullableUnion(out, keyword);
return out;
};
// Every spot an OpenAPI Operation Object can carry a Schema Object.
const convertContent = (content) => (isPlainObject(content)
? Object.fromEntries(Object.entries(content).map(([mediaType, media]) => [
mediaType,
isPlainObject(media?.schema) ? { ...media, schema: toOpenApi30Schema(media.schema) } : media,
]))
: content);
const convertPayload = (payload) => (isPlainObject(payload?.content)
? { ...payload, content: convertContent(payload.content) }
: payload);
/**
* Downgrade every schema an OpenAPI operation carries — request body, response
* bodies, and parameters. This is the boundary the conversion belongs at: the
* operation is on its way into a document that declares 3.0.3, whereas the same
* contract schemas reach other consumers as plain JSON Schema.
*/
export const toOpenApi30Operation = (operation) => {
if (!isPlainObject(operation)) return operation;
const out = { ...operation };
if (out.requestBody) out.requestBody = convertPayload(out.requestBody);
if (isPlainObject(out.responses)) {
out.responses = Object.fromEntries(
Object.entries(out.responses).map(([status, response]) => [status, convertPayload(response)]),
);
}
if (Array.isArray(out.parameters)) {
out.parameters = out.parameters.map((parameter) => (isPlainObject(parameter?.schema)
? { ...parameter, schema: toOpenApi30Schema(parameter.schema) }
: parameter));
}
return out;
};