bug: inconsistent types for OAS3_1 schemas

[jeremyfiel]

redocly-cli/packages/core/src/typings/openapi.ts

Lines 160 to 164 in f11ebcb

	export interface Oas3_1Schema extends Oas3XSchemaBase<Oas3_1Schema> {
	type?: string | string[];
	examples?: any[];
	prefixItems?: Oas3_1Schema[];
	}

redocly-cli/packages/core/src/types/oas3_1.ts

Lines 90 to 185 in f11ebcb

	const Schema: NodeType = {
	properties: {
	$id: { type: 'string' },
	$anchor: { type: 'string' },
	id: { type: 'string' },
	$schema: { type: 'string' },
	definitions: 'NamedSchemas',
	$defs: 'NamedSchemas',
	$vocabulary: { type: 'string' },
	externalDocs: 'ExternalDocs',
	discriminator: 'Discriminator',
	title: { type: 'string' },
	multipleOf: { type: 'number', minimum: 0 },
	maximum: { type: 'number' },
	minimum: { type: 'number' },
	exclusiveMaximum: { type: 'number' },
	exclusiveMinimum: { type: 'number' },
	maxLength: { type: 'integer', minimum: 0 },
	minLength: { type: 'integer', minimum: 0 },
	pattern: { type: 'string' },
	maxItems: { type: 'integer', minimum: 0 },
	minItems: { type: 'integer', minimum: 0 },
	uniqueItems: { type: 'boolean' },
	maxProperties: { type: 'integer', minimum: 0 },
	minProperties: { type: 'integer', minimum: 0 },
	required: { type: 'array', items: { type: 'string' } },
	enum: { type: 'array' },
	type: (value: any) => {
	if (Array.isArray(value)) {
	return {
	type: 'array',
	items: { enum: ['object', 'array', 'string', 'number', 'integer', 'boolean', 'null'] },
	};
	} else {
	return {
	enum: ['object', 'array', 'string', 'number', 'integer', 'boolean', 'null'],
	};
	}
	},
	allOf: listOf('Schema'),
	anyOf: listOf('Schema'),
	oneOf: listOf('Schema'),
	not: 'Schema',
	if: 'Schema',
	then: 'Schema',
	else: 'Schema',
	dependentSchemas: listOf('Schema'),
	prefixItems: listOf('Schema'),
	contains: 'Schema',
	minContains: { type: 'integer', minimum: 0 },
	maxContains: { type: 'integer', minimum: 0 },
	patternProperties: { type: 'object' },
	propertyNames: 'Schema',
	unevaluatedItems: (value: unknown) => {
	if (typeof value === 'boolean') {
	return { type: 'boolean' };
	} else {
	return 'Schema';
	}
	},
	unevaluatedProperties: (value: unknown) => {
	if (typeof value === 'boolean') {
	return { type: 'boolean' };
	} else {
	return 'Schema';
	}
	},
	summary: { type: 'string' },
	properties: 'SchemaProperties',
	items: (value: any) => {
	if (typeof value === 'boolean') {
	return { type: 'boolean' };
	} else {
	return 'Schema';
	}
	},
	additionalProperties: (value: any) => {
	return typeof value === 'boolean' ? { type: 'boolean' } : 'Schema';
	},
	description: { type: 'string' },
	format: { type: 'string' },
	contentEncoding: { type: 'string' },
	contentMediaType: { type: 'string' },
	default: null,
	readOnly: { type: 'boolean' },
	writeOnly: { type: 'boolean' },
	xml: 'Xml',
	examples: { type: 'array' },
	example: { isExample: true },
	deprecated: { type: 'boolean' },
	const: null,
	$comment: { type: 'string' },
	'x-tags': { type: 'array', items: { type: 'string' } },
	},
	extensionsPrefix: 'x-',
	};

Should these two separate typings be refactored to use only one of them across the core package? The openapi.ts typing does not include the unevaluated* keywords required for OAS 3.1.x /JSON Schema 2020-12 schemas.

I think this relates to #1546 where an unexpected keyword is throwing an error, but it is indeed valid for JSON Schema 2020-12 schemas to define any arbitrary properties.

In the previous version of OpenAPI 3.0.x, the schema object was strictly defined as a superset and subset of a JSON Schema draft-04 schema, and thus not all JSON Schema related behaviors applied. The interface design of OAS3_1Schema does not allow arbitrary properties.

[tatomyr]

Good question. They are somewhat different as the first one is using for the code typing while the second one is for an OAS description typing. Ideally they should be synchronised, but I cannot come up with a reliable solution to enforce that.