Merge base #1921: route the union translation through the shared emitter

The base branch added `types` (the source union) and translated it per surface
at each call site. This branch replaced those call sites with one shared
emitter, so the translation moves into it: `attributeToSchema` emits the union
verbatim for MCP and `oneOf` for OpenAPI 3.0, which also makes it work at every
nesting level rather than only the top one.

Also expresses a `null`-only declaration as `{ nullable: true, enum: [null] }`
rather than dropping it — 3.0 has no `null` type, but it can say "only null".

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0188G62J9fZQg4J9rVuqLzjy

Author: nizzlenitz

components/mcp/tools/schemas/derive.ts

@@ -25,6 +25,8 @@ export interface HarperAttribute {
 	description?: string;
 	hidden?: boolean;
 	nullable?: boolean;
+	/** Source JSON-Schema type union from `static properties`; MCP accepts type arrays, so it passes through. */
+	types?: readonly string[];
 	isPrimaryKey?: boolean;
 	properties?: HarperAttribute[];
 	elements?: HarperAttribute;

resources/jsonSchemaTypes.ts

@@ -32,6 +32,8 @@ export interface JsonSchemaFragment {
 	const?: unknown;
 	/** Binary encoding of a string-typed value. Emitted on the MCP surface only — not a 3.0.3 keyword. */
 	contentEncoding?: string;
+	/** Emitted by the OpenAPI 3.0 projection for a genuine multi-type union; not authored directly. */
+	oneOf?: JsonSchemaFragment[];
 }
 
 /**
@@ -75,6 +77,12 @@ export interface AttributeLike {
 	assignCreatedTime?: boolean;
 	assignUpdatedTime?: boolean;
 	nullable?: boolean;
+	/**
+	 * The source JSON-Schema type union, verbatim, when `static properties` declared one. `type` holds
+	 * the first non-null member so single-type consumers keep working; surfaces that can express a
+	 * union (MCP passes it through, OpenAPI 3.0 translates it to `oneOf`) read this instead.
+	 */
+	types?: readonly string[];
 	elements?: AttributeLike;
 	/** Sub-attributes of a nested object field (the same array form `Table.validate` iterates). */
 	properties?: AttributeLike[];
@@ -111,6 +119,10 @@ export function attributeToFragment(attr: AttributeLike): JsonSchemaFragment {
 	} else if (attr.type === 'array' && attr.elements) {
 		fragment.type = 'array';
 		fragment.items = attributeToFragment(attr.elements);
+	} else if (attr.types) {
+		// A declared union round-trips verbatim; collapsing it to `attr.type` here would make the
+		// canonical `Table.properties` disagree with what the author wrote.
+		fragment.type = [...attr.types] as JsonSchemaType[];
 	} else {
 		const jsonType = attr.type ? DATA_TYPES[attr.type] : undefined;
 		if (jsonType) fragment.type = jsonType;
@@ -161,9 +173,11 @@ function fragmentToAttribute(name: string, fragment: JsonSchemaFragment): Attrib
 		// than misleadingly reusing the array field's own name.
 		attr.elements = fragmentToAttribute('', fragment.items);
 	} else if (Array.isArray(fragment.type)) {
-		// JSON-Schema union type. Fold a `'null'` member into `nullable` (the OpenAPI-expressible form)
-		// and keep the remaining member. A single non-null member is the common `['T','null']` case; a
-		// genuine multi-type union isn't expressible on an attribute, so the first member is kept.
+		// JSON-Schema union type. Keep the source union on `types` so surfaces that can express one
+		// (MCP natively, OpenAPI 3.0 via `oneOf`) don't have to reconstruct it, and fold a `'null'`
+		// member into `nullable` as well since that is the form OpenAPI needs. `type` carries the first
+		// non-null member for the single-type consumers (validation, query coercion) that read it.
+		attr.types = fragment.type;
 		const members = fragment.type.filter((t) => t !== 'null');
 		if (members.length !== fragment.type.length) attr.nullable = true;
 		if (members.length > 0) attr.type = members[0];
@@ -251,6 +265,17 @@ export function resolveDeclaredType(type: string | undefined, context?: string):
 	return undefined;
 }
 
+/**
+ * The non-null members of an attribute's declared type union, but only when there is more than one —
+ * `['string','null']` is nullability, not a union, and `type` already carries its single member.
+ * Returns undefined when the attribute has no union to translate.
+ */
+export function unionMembers(attr: { types?: readonly string[] }): string[] | undefined {
+	if (!attr.types) return undefined;
+	const members = attr.types.filter((member) => member !== 'null');
+	return members.length > 1 ? members : undefined;
+}
+
 /** Test hook: the unknown-type warning is once-per-process, which would leak across test cases. */
 export function _resetUnknownTypeWarningsForTest(): void {
 	warnedUnknownTypes.clear();
@@ -303,6 +328,14 @@ export function attributeToSchema(attr: AttributeLike, options: SchemaEmitOption
 			const items = attributeToSchema(attr.elements, childOptions);
 			if (items) fragment.items = items;
 		}
+	} else if (attr.types && options.dialect === 'json-schema') {
+		// JSON Schema has type unions — emit the author's declaration as written.
+		fragment.type = [...attr.types] as JsonSchemaType[];
+	} else if (unionMembers(attr)) {
+		// 3.0.3 has neither type arrays nor a `null` type, so a genuine union becomes `oneOf`. Each
+		// member still goes through the surface's own primitive mapping, so it is described exactly as
+		// the same type would be on its own.
+		fragment.oneOf = unionMembers(attr).map((member) => options.mapPrimitive(member, attr));
 	} else {
 		// Copy the mapper's result field by field rather than merging it wholesale: the set of keys a
 		// surface may contribute to a leaf schema is fixed, and spreading an arbitrary object here would
@@ -312,6 +345,8 @@ export function attributeToSchema(attr: AttributeLike, options: SchemaEmitOption
 		if (primitive.description !== undefined) fragment.description = primitive.description;
 		if (primitive.format !== undefined) fragment.format = primitive.format;
 		if (primitive.contentEncoding !== undefined) fragment.contentEncoding = primitive.contentEncoding;
+		if (primitive.nullable !== undefined) fragment.nullable = primitive.nullable;
+		if (primitive.enum !== undefined) fragment.enum = primitive.enum;
 	}
 
 	if (attr.nullable) applyNullability(fragment, options.dialect);
@@ -347,9 +382,15 @@ export function attributeToSchema(attr: AttributeLike, options: SchemaEmitOption
 }
 
 function applyNullability(fragment: JsonSchemaFragment, dialect: SchemaDialect): void {
-	// Both dialects express nullability as a modification of `type`, so neither has anything to say
-	// about a fragment that never resolved one.
-	if (!('type' in fragment) || fragment.type === undefined) return;
+	// Nullability qualifies a schema that says something; neither dialect has anything to add to a
+	// fragment that resolved neither a `type` nor a `oneOf`.
+	if ((!('type' in fragment) || fragment.type === undefined) && fragment.oneOf === undefined) return;
+	if (fragment.type === undefined) {
+		// A `oneOf` union. 3.0 takes `nullable` alongside it; JSON Schema takes a `null` branch.
+		if (dialect === 'openapi-3.0.3') fragment.nullable = true;
+		else fragment.oneOf = [...fragment.oneOf, { type: 'null' }];
+		return;
+	}
 	if (dialect === 'openapi-3.0.3') {
 		// OpenAPI 3.0.3 has no union types; `nullable` is the spec-provided expression.
 		fragment.nullable = true;

resources/openApi.ts

@@ -8,6 +8,7 @@ import {
 	attributeToSchema,
 	projectPropertiesToAttributes,
 	resolveDeclaredType,
+	unionMembers,
 } from './jsonSchemaTypes.ts';
 
 const OPENAPI_VERSION = '3.0.3';
@@ -34,7 +35,10 @@ function openApiPrimitive(type: string | undefined, attributeName: string | unde
 	if (!resolved) return {};
 	// 3.0.x has no `'null'` type — nullability is the `nullable` keyword, so a bare `type: 'null'`
 	// becomes an untyped nullable schema rather than a type the dialect can't express.
-	if (resolved === 'null') return {}; // 3.0 has no null type; a bare `nullable` on an untyped schema says nothing
+	// 3.0 has no `'null'` type. A bare `{ nullable: true }` constrains nothing, so express "only null"
+	// the one way the dialect can: a `null`-only enum. Dropping the declaration outright (#1921 review)
+	// left the document silent about a field the author did describe.
+	if (resolved === 'null') return { nullable: true, enum: [null] };
 	// Preserve the Harper type name as `format` for the types where it adds information, matching the
 	// top-level `Type()` emitter.
 	return Object.hasOwn(DATA_TYPES, type) ? (new Type(resolved, type) as JsonSchemaFragment) : { type: resolved };
@@ -168,6 +172,7 @@ export function generateJsonApi(resources: Resources, serverHttpURL: string) {
 		if (attributes) {
 			for (const attr of attributes) {
 				const { type, name, elements, relationship, definition, nullable, description, hidden } = attr;
+				const union = unionMembers(attr);
 				// @hidden field-level: suppress the attribute from props, query params, and required.
 				if (hidden) continue;
 				const def = definition ?? elements?.definition;
@@ -196,6 +201,10 @@ export function generateJsonApi(resources: Resources, serverHttpURL: string) {
 						// shared emitter (sub-properties recursed, @hidden suppressed at every level, hints
 						// carried); OpenAPI's table path uses $refs instead.
 						props[name] = attributeToOpenApiSchema(attr) ?? {};
+					} else if (union) {
+						// A genuine multi-type union (`['string','number']`). 3.0 has no type arrays, so the
+						// equivalent is `oneOf`; `attr.type` alone would drop every member but the first.
+						props[name] = { oneOf: union.map((member) => openApiPrimitive(member, name)) };
 					} else if (type === 'array') {
 						if (!elements) {
 							// `{ type: 'array' }` with no items — valid JSON Schema (array of anything).
@@ -227,6 +236,7 @@ export function generateJsonApi(resources: Resources, serverHttpURL: string) {
 						description?: string;
 						enum?: unknown[];
 						type?: unknown;
+						oneOf?: unknown;
 						format?: string;
 						const?: unknown;
 						nullable?: boolean;
@@ -241,9 +251,11 @@ export function generateJsonApi(resources: Resources, serverHttpURL: string) {
 					if (attr.const !== undefined) {
 						prop.enum = Array.isArray(prop.enum) ? prop.enum.filter((value) => value === attr.const) : [attr.const];
 					}
-					// Only a typed schema can be nullable — a bare `{ nullable: true }` says nothing in 3.0,
-					// matching the guard the shared emitter applies.
-					if (nullable && prop.nullable === undefined && prop.type !== undefined) prop.nullable = true;
+					// Only a schema that says something can be nullable — a bare `{ nullable: true }` says nothing
+					// in 3.0. A `oneOf` union qualifies alongside a plain `type`.
+					if (nullable && prop.nullable === undefined && (prop.type !== undefined || prop.oneOf !== undefined)) {
+						prop.nullable = true;
+					}
 					// 3.0's `nullable` does not widen an `enum`; without `null` in the list a validator
 					// rejects it regardless of the flag.
 					if (prop.nullable && Array.isArray(prop.enum) && !prop.enum.includes(null)) {

unitTests/components/mcp/tools/convergence.test.js

@@ -24,6 +24,7 @@ function makeResources() {
 	Widget.properties = {
 		id: { type: 'string', primaryKey: true },
 		label: { type: 'string', description: 'Human-readable label' },
+		mixed: { type: ['string', 'number'] },
 	};
 	for (const v of ['get', 'put', 'patch', 'delete', 'search', 'post']) Widget.prototype[v] = function () {};
 	Widget.get = async (t) => ({ id: t.id });
@@ -75,6 +76,22 @@ describe('mcp/openapi — #1920 description convergence across surfaces', () =>
 		// Convergence: the per-property description is identical on both surfaces.
 		assert.equal(create.inputSchema.properties.label.description, schema.properties.label.description);
 	});
+
+	it('expresses a declared type union on each surface in that surface’s own dialect', () => {
+		const resources = makeResources();
+
+		_setResourcesForTest(resources);
+		registerApplicationTools();
+		const create = getTool('create_Widget');
+		// MCP speaks JSON Schema, which has type unions — pass the author's declaration through.
+		assert.deepEqual(create.inputSchema.properties.mixed.type, ['string', 'number']);
+
+		// OpenAPI 3.0 has no type arrays; the equivalent is `oneOf`. Same declaration, two encodings —
+		// what must NOT happen is either surface narrowing it to `string`.
+		const schema = generateJsonApi(resources, 'https://harper.fast').components.schemas.Widget;
+		assert.deepEqual(schema.properties.mixed.oneOf, [{ type: 'string' }, { type: 'number' }]);
+		assert.equal(schema.properties.mixed.type, undefined);
+	});
 });
 
 // #1941 / #1942 — the two surfaces used to diverge below the top level: OpenAPI dropped hints inside

unitTests/resources/graphqlMetadata.test.js

@@ -199,5 +199,24 @@ describe('GraphQL parser — metadata capture (#1095)', () => {
 			assert.strictEqual(note.type, 'string');
 			assert.strictEqual(note.nullable, true, 'the null member must become nullable, not be dropped');
 		});
+
+		it('preserves a genuine multi-type union instead of keeping only the first member', () => {
+			const [mixed] = projectPropertiesToAttributes({ mixed: { type: ['string', 'number'] } });
+			assert.deepStrictEqual(mixed.types, ['string', 'number']);
+			assert.strictEqual(mixed.type, 'string', 'single-type consumers still see the first member');
+		});
+
+		it('round-trips a union back to the declared fragment (properties -> attributes -> properties)', () => {
+			const declared = { mixed: { type: ['string', 'number'] }, maybe: { type: ['string', 'null'] } };
+			const round = projectAttributesToProperties(projectPropertiesToAttributes(declared));
+			assert.deepStrictEqual(round.mixed.type, ['string', 'number']);
+			assert.deepStrictEqual(round.maybe.type, ['string', 'null']);
+		});
+
+		it('keeps a `["null"]`-only declaration nullable rather than silently untyped', () => {
+			const [nothing] = projectPropertiesToAttributes({ nothing: { type: ['null'] } });
+			assert.strictEqual(nothing.nullable, true);
+			assert.deepStrictEqual(nothing.types, ['null']);
+		});
 	});
 });

unitTests/resources/openApi.test.js

@@ -371,7 +371,16 @@ describe('openApi — declared dialect compliance (3.0.3)', () => {
 			kind: { type: 'string', const: 'widget' },
 			nothing: { type: 'null' },
 			maybe: { type: ['string', 'null'] },
-			nested: { type: 'object', properties: { inner: { type: 'string', const: 'x' }, deepNull: { type: 'null' } } },
+			mixed: { type: ['string', 'number'] },
+			mixedMaybe: { type: ['string', 'integer', 'null'] },
+			nested: {
+				type: 'object',
+				properties: {
+					inner: { type: 'string', const: 'x' },
+					deepNull: { type: 'null' },
+					deepMixed: { type: ['string', 'number'] },
+				},
+			},
 			list: { type: 'array', items: { type: 'string', const: 'y' } },
 			nullableEnum: { type: 'string', enum: ['a', 'b'], nullable: true },
 			nullableConst: { type: 'string', const: 'fixed', nullable: true },
@@ -488,9 +497,58 @@ describe('openApi — declared dialect compliance (3.0.3)', () => {
 		expect(body.properties.status.enum, 'nullable enum admits null').to.deep.equal(['a', 'b', null]);
 	});
 
+	it('carries nullability onto the emitted scalar schema', () => {
+		// The walk assertions above only prove `type: 'null'` and unions are gone; they would pass just as
+		// happily if nullability were dropped instead of translated.
+		const props = buildDocument().components.schemas.Widget.properties;
+		expect(props.maybe).to.deep.equal({ type: 'string', nullable: true });
+		expect(props.nothing.nullable).to.equal(true);
+	});
+
+	it('widens a nullable `enum` with `null` (3.0 `nullable` does not do it)', () => {
+		const props = buildDocument().components.schemas.Widget.properties;
+		expect(props.nullableEnum.nullable).to.equal(true);
+		expect(props.nullableEnum.enum).to.deep.equal(['a', 'b', null]);
+		// `const` + `nullable`: the single-value enum still has to admit null.
+		expect(props.nullableConst.enum).to.deep.equal(['fixed', null]);
+	});
+
+	it('translates a genuine multi-type union to `oneOf`', () => {
+		// 3.0 has no type arrays. Keeping only the first member would narrow the contract silently —
+		// a client would be told `mixed` is a string when the resource also accepts a number.
+		const props = buildDocument().components.schemas.Widget.properties;
+		expect(props.mixed).to.deep.equal({ oneOf: [{ type: 'string' }, { type: 'number' }] });
+		expect(props.mixed).to.not.have.property('type');
+	});
+
+	it('carries nullability alongside a union', () => {
+		const props = buildDocument().components.schemas.Widget.properties;
+		expect(props.mixedMaybe.oneOf).to.deep.equal([{ type: 'string' }, { type: 'integer' }]);
+		expect(props.mixedMaybe.nullable).to.equal(true);
+	});
+
+	it('translates a union nested inside an object, not just at the top level', () => {
+		// The nested path is the one #1941/#1942 exist to keep in step with the top-level one; a union
+		// declared two levels down has to reach the same `oneOf`.
+		const nested = buildDocument().components.schemas.Widget.properties.nested;
+		expect(nested.properties.deepMixed.oneOf).to.deep.equal([{ type: 'string' }, { type: 'number' }]);
+		expect(nested.properties.deepMixed).to.not.have.property('type');
+	});
+
 	it('emits the properties under test (guards the walk assertions against an empty document)', () => {
 		const props = buildDocument().components.schemas.Widget.properties;
-		for (const key of ['kind', 'nothing', 'maybe', 'nested', 'list', 'nullableEnum', 'nullableConst', 'when']) {
+		for (const key of [
+			'kind',
+			'nothing',
+			'maybe',
+			'mixed',
+			'mixedMaybe',
+			'nested',
+			'list',
+			'nullableEnum',
+			'nullableConst',
+			'when',
+		]) {
 			expect(props, `fixture property ${key} missing — walk assertions would pass vacuously`).to.have.property(key);
 		}
 	});