feat: support for reusable pathItems definitions in components for OAS 3.1 (#26)

Author: makeev-pavel

src/define-origins-and-resolve-ref.ts

@@ -22,7 +22,7 @@ import {
   ResolveOptions,
   RichReference,
 } from './types'
-import { resolveSpec, SPEC_TYPE_GRAPH_API, SPEC_TYPE_OPEN_API_31 } from './spec-type'
+import { resolveSpec } from './spec-type'
 import { ErrorMessage } from './errors'
 import { createCycledJsoHandlerHook } from './cycle-jso'
 import { JSON_SCHEMA_PROPERTY_ALL_OF, JSON_SCHEMA_PROPERTY_REF } from './rules/jsonschema.const'
@@ -60,12 +60,14 @@ const IMPOSSIBLE_ORIGIN_PARENT: ChainItem = { parent: undefined, value: 'ERROR!!
 
 export const defineOriginsAndResolveRef = (value: unknown, options?: ResolveOptions) => {
   const spec = resolveSpec(value)
+  const source = options?.source ?? value
+
   const internalOptions = {
     resolveRef: DEFAULT_OPTION_RESOLVE_REF,
     originsAlreadyDefined: !!options?.originsFlag,
     ...options,
     originsFlag: options?.originsAlreadyDefined ? undefined : options?.originsFlag,
-    source: options?.source ?? value,
+    source,
     ignoreSymbols: new Set([
       ...(options?.originsFlag ? [options.originsFlag] : []),
       ...(options?.inlineRefsFlag ? [options.inlineRefsFlag] : []),
@@ -140,7 +142,13 @@ export const deDefineOriginsAndResolvedRefSymbols = (value: unknown, options?: R
 const createDefineOriginsAndResolveRefHook: (rootJso: unknown, options: InternalResolveOptions, cycleJsoHook: SyncCloneHook<DefineOriginsAndResolveRefState>) => DefineOriginsAndResolveRefSyncCloneHook = (rootJso, options, cycleJsoHook) => {
   const cyclingGuard: Set<unknown> = new Set()
   const syntheticTitleCache: Map<string, Record<PropertyKey, unknown>> = new Map()
-  const defineOriginsAndResolveRefHook: DefineOriginsAndResolveRefSyncCloneHook = ({ key, value, state, path, rules, }) => {
+  const defineOriginsAndResolveRefHook: DefineOriginsAndResolveRefSyncCloneHook = ({
+    key,
+    value,
+    state,
+    path,
+    rules,
+  }) => {
     if (state.ignoreTreeUnderSymbols) {
       return { value }
     }
@@ -189,7 +197,7 @@ const createDefineOriginsAndResolveRefHook: (rootJso: unknown, options: Internal
           }
           const reference = parseRef($ref)
 
-          const processWrapRefWithAllOfReference = (resolvedRefWithSibling: ResolvedRefWithSiblings)  => {
+          const processWrapRefWithAllOfReference = (resolvedRefWithSibling: ResolvedRefWithSiblings) => {
             const {
               refValue,
               origin,
@@ -282,9 +290,9 @@ const createDefineOriginsAndResolveRefHook: (rootJso: unknown, options: Internal
             }
           }
 
-          const processResolvedReference = (resolvedRefWithSibling: ResolvedRefWithSiblings) =>  {
+          const processResolvedReference = (resolvedRefWithSibling: ResolvedRefWithSiblings) => {
             if (hasChildrenOrigins(resolvedRefWithSibling)) {
-                return processReferenceWithChildren(resolvedRefWithSibling)
+              return processReferenceWithChildren(resolvedRefWithSibling)
             }
             return processWrapRefWithAllOfReference(resolvedRefWithSibling)
           }

src/normalize.ts

@@ -10,7 +10,7 @@ import {
   NormalizeOptions,
 } from './types'
 import { deDefineOriginsAndResolvedRefSymbols, defineOriginsAndResolveRef } from './define-origins-and-resolve-ref'
-import { validate } from './validate'
+import { preValidate, validate } from './validate'
 import { merge } from './merge'
 import { cleanUpSynthetic, deCleanUpSynthetic, deUnify, unify } from './unify'
 import { deHash, hash } from './hash'
@@ -19,7 +19,8 @@ import { removeOasExtensions } from './remove-oas-extensions'
 export const normalize = (value: unknown, options: NormalizeOptions = {}) => {
   const optionsWithDefaults = createOptionsWithDefaults(options)
   let spec = value
-  if (optionsWithDefaults.resolveRef || (!optionsWithDefaults.originsAlreadyDefined && optionsWithDefaults.originsFlag)) { spec = defineOriginsAndResolveRef(spec, optionsWithDefaults) }
+  if (optionsWithDefaults.validate) { preValidate(spec, options) }
+  if (optionsWithDefaults.resolveRef || (!optionsWithDefaults.originsAlreadyDefined && optionsWithDefaults.originsFlag)) {spec = defineOriginsAndResolveRef(spec, optionsWithDefaults)}
   if (optionsWithDefaults.validate) { spec = validate(spec, optionsWithDefaults) }
   if (optionsWithDefaults.mergeAllOf) { spec = merge(spec, optionsWithDefaults) }
   if (optionsWithDefaults.unify) { spec = unify(spec, optionsWithDefaults) }

src/rules/jsonschema.ts

@@ -438,7 +438,6 @@ export const jsonSchemaRules: (
     hashStrategy: CURRENT_DATA_LEVEL,
   },
   '/properties': {
-
     '/*': () => ({
       ...self(),
       newDataLayer: true,

src/rules/openapi.const.ts

@@ -47,6 +47,7 @@ export const OPEN_API_PROPERTY_SCHEMAS = 'schemas'
 export const OPEN_API_PROPERTY_SCHEMA = 'schema'
 export const OPEN_API_PROPERTY_LINKS = 'links'
 export const OPEN_API_PROPERTY_SECURITY_SCHEMAS = 'securitySchemes'
+export const OPEN_API_PROPERTY_PATH_ITEMS = 'pathItems'
 
 export const OPEN_API_PROPERTY_DESCRIPTION = 'description'
 export const OPEN_API_PROPERTY_SUMMARY = 'summary'

src/rules/openapi.ts

@@ -436,7 +436,7 @@ const customFor30JsonSchemaRulesFactory = (): NormalizationRules => {
       ...customFor30JsonSchemaRules,
       merge: resolvers.itemsMergeResolver,
       hashStrategy: CURRENT_DATA_LEVEL,
-      newDataLayer: true
+      newDataLayer: true,
     }),
     '/additionalItems': {
       validate: () => false,
@@ -704,10 +704,7 @@ const openApiPathItemRules = (version: OpenApiSpecVersion): NormalizationRules =
     validate: checkType(TYPE_OBJECT),
   }),
   '/parameters': openApiParametersRules(version),
-  referenceHandler: referenceObjectRuleFunction({
-    version,
-    allowedOverrides: [OPEN_API_PROPERTY_SUMMARY, OPEN_API_PROPERTY_DESCRIPTION],
-  }),
+  referenceHandler: referenceObjectResolver(),
   validate: checkType(TYPE_OBJECT),
   unify: pathItemsUnification,
 })
@@ -822,6 +819,18 @@ export const openApiRules = (version: OpenApiSpecVersion): NormalizationRules =>
         ...openApiExtensionRulesFunction(() => openApiPathItemRules(version)),
       },
     },
+    /**
+     * Note: For OAS 3.0, `components.pathItems` is not a valid property.
+     * We intentionally keep these rules and do not delete this path here
+     * because invalid `components.pathItems` entries are pre-processed and
+     * handled during pre-validation step.
+     * Additionally, the reference resolver contains checks that guard against
+     * misuse in OAS 3.0. See: validate.ts
+     */
+    '/pathItems': ({
+      ...openApiExtensionRulesFunction(openApiPathItemRules(version)),
+      validate: checkType(TYPE_OBJECT),
+    }),
     ...openApiExamplesRules(version),
     ...openApiExtensionRules,
     validate: checkType(TYPE_OBJECT),

src/validate.ts

@@ -7,10 +7,33 @@ import {
   ValidateSyncCloneHook,
 } from './types'
 import { isArray, isObject, JSON_ROOT_KEY, syncClone } from '@netcracker/qubership-apihub-json-crawl'
-import { resolveSpec } from './spec-type'
+import { resolveSpec, SPEC_TYPE_OPEN_API_30 } from './spec-type'
 import { createCycledJsoHandlerHook } from './cycle-jso'
 import { RULES } from './rules'
 import { cleanSeveralOrigins } from './origins'
+import { OPEN_API_PROPERTY_COMPONENTS, OPEN_API_PROPERTY_PATH_ITEMS } from './rules/openapi.const'
+
+/**
+ * Preprocesses an OpenAPI specification prior to reference resolution/origin definition.
+ *
+ * For OpenAPI 3.0 documents, `components.pathItems` is not a valid field (it was
+ * added in OAS 3.1). Some tools may still emit it. To keep the input compliant,
+ * deterministic, and to avoid misinterpreting invalid nodes as real API paths,
+ * this function removes `components.pathItems` for OAS 3.0 and emits an optional
+ * validation message via `options.onValidateError`.
+ */
+export function preValidate(source: unknown, options?: ValidateOptions & ResolveOptions): void {
+  const spec = resolveSpec(source)
+  if (spec.type !== SPEC_TYPE_OPEN_API_30 || !isObject(source)) {
+    return
+  }
+  if (OPEN_API_PROPERTY_COMPONENTS in source && isObject(source.components)) {
+    const components = source.components as Record<string, unknown>
+    if (Reflect.deleteProperty(components, OPEN_API_PROPERTY_PATH_ITEMS)) {
+      (options as ValidateOptions)?.onValidateError?.(`Invalid property 'components.pathItems' for OpenAPI 3.0. The property has been removed to maintain 3.0 compliance.`, ['components', 'pathItems'], 'pathItems')
+    }
+  }
+}
 
 const createValidationHook: (options: InternalValidationOptions) => ValidateSyncCloneHook = (options) => {
   const validateHook: ValidateSyncCloneHook = ({ key, path, value, rules, state }) => {

test/oas/path-items.test.ts

@@ -0,0 +1,48 @@
+import { normalize } from '../../src'
+import pathItemsOas30 from '../resources/pathitems/pathItems-oas-30.json'
+import pathItemsOas31 from '../resources/pathitems/pathItems-oas-31.json'
+
+const OPTIONS = { resolveRef: true, validate: true }
+describe('OAS 3.1 Path Item Object', () => {
+  it('validation must pass for the Item Object in components', () => {
+    const result = normalize(pathItemsOas31, OPTIONS) as any
+
+    expect(result.components.pathItems.componentsPathItem).not.toEqual({})
+  })
+
+  it('could define Path Item Object via ref', () => {
+    const result = normalize(pathItemsOas31, OPTIONS) as any
+
+    expect(result.paths['/path1'].post).toBe(result.components.pathItems.componentsPathItem.post)
+  })
+})
+
+describe('OAS 3.0 Path Item Object', () => {
+  let baseSpec: any
+
+  beforeEach(() => {
+    baseSpec = JSON.parse(JSON.stringify(pathItemsOas30))
+  })
+
+  it('validation should discard pathItems section in components', () => {
+    const result = normalize(baseSpec, OPTIONS) as any
+
+    expect(result).not.toHaveProperty(['components', 'pathItems'])
+  })
+
+  it('validation must raise error for the pathItem section in components', () => {
+    const errors: string[] = []
+    const result = normalize(baseSpec, {...OPTIONS, onValidateError: message => errors.push(message) }) as any
+
+    expect(errors).toMatchObject([
+      expect.stringMatching(/Invalid/),
+      expect.stringMatching(/match/),
+    ])
+  })
+
+  it('could not resolve Path Item from components via reference object', () => {
+    const result = normalize(baseSpec, OPTIONS) as any
+
+    expect(result).toHaveProperty(['paths', '/path1'], {})
+  })
+})