diff --git a/.github/analyze-issue.md b/.github/analyze-issue.md
new file mode 100644
index 0000000000..0069c67d4b
--- /dev/null
+++ b/.github/analyze-issue.md
@@ -0,0 +1,78 @@
+# Issue Analysis Template
+
+## Overview
+Analyze the GitHub issue for the swagger-parser project and provide a comprehensive assessment.
+
+## Analysis Structure
+
+### 1. Issue Summary
+- **Issue Number**: [Issue number from CSV]
+- **Title**: [Issue title]
+- **Type**: [Bug/Feature/Question/Enhancement]
+- **Status**: [Open/Closed]
+- **URL**: [GitHub issue URL]
+
+### 2. Problem Description
+Provide a clear and concise summary of the issue. What is the user trying to accomplish? What is not working as expected?
+
+### 3. Technical Analysis
+
+#### Affected Components
+List the specific modules, classes, or files that are likely affected:
+- Module/Package name
+- Specific classes or methods (if identifiable)
+- Configuration or parsing options involved
+
+#### Root Cause (if identifiable)
+Based on the issue description, what appears to be the underlying cause?
+
+#### Impact Assessment
+- **Severity**: Critical/High/Medium/Low
+- **User Impact**: How many users are likely affected?
+- **Workaround Available**: Yes/No - describe if available
+
+### 4. Reproduction
+Can this issue be reproduced based on the provided information?
+- **Reproducible**: Yes/No/Partial
+- **Steps**: List the reproduction steps if provided
+- **Test Case Available**: Yes/No
+
+### 5. Related Issues and Context
+
+#### Dependencies
+- Does this issue depend on or relate to other issues?
+- Are there similar or duplicate issues?
+
+#### Version Information
+- Affected version(s)
+- Fixed version (if closed)
+
+### 6. Solution Approach
+
+#### Proposed Solution
+Based on the issue description and analysis, what would be the recommended approach to address this?
+
+#### Implementation Complexity
+- **Effort Estimate**: Low/Medium/High
+- **Risks**: Any potential risks or breaking changes?
+
+#### Testing Requirements
+- Unit tests needed
+- Integration tests needed
+- Backward compatibility considerations
+
+### 7. Additional Notes
+Any other relevant observations, concerns, or recommendations.
+
+---
+
+## Instructions for Analysis
+
+1. Read the complete issue description including all comments
+2. Identify the core problem and any related symptoms
+3. Analyze the technical context (OpenAPI version, parser options, etc.)
+4. Assess the impact and priority
+5. Propose a solution approach if possible
+6. Note any missing information or clarifications needed
+
+Focus on providing accurate, actionable analysis that helps maintainers understand and prioritize the issue.
diff --git a/data/swagger-parser/issues.csv b/data/swagger-parser/issues.csv
new file mode 100644
index 0000000000..8440043c61
--- /dev/null
+++ b/data/swagger-parser/issues.csv
@@ -0,0 +1,34 @@
+number,title,state,url
+2275,[Feature]: Cache the result of deserialization when loading ref,open,https://github.com/swagger-api/swagger-parser/issues/2275
+2271,[Bug]: Validation behavior change between openapi-generator 7.13.0 and 7.14.0 against an OpenAPI 3.1 schema with external references,open,https://github.com/swagger-api/swagger-parser/issues/2271
+2216,[Bug]: Parameters components shouldn't be inlined with resolve option set to true,open,https://github.com/swagger-api/swagger-parser/issues/2216
+2149,OpenAPIV3Parser.resolve() should handle all errors in the entire spec,open,https://github.com/swagger-api/swagger-parser/issues/2149
+2148,Request for a Simplified Swagger Parser with Minimal Dependencies,open,https://github.com/swagger-api/swagger-parser/issues/2148
+2147,cannot deserialize from Object value (Grallvm native executable),open,https://github.com/swagger-api/swagger-parser/issues/2147
+2145,[Bug]: additionalProperties not resolved fully with resolveFully,open,https://github.com/swagger-api/swagger-parser/issues/2145
+2144,[Open API 3.1] Json31 is incorrectly assuming that property containing anyOf is of type: object,open,https://github.com/swagger-api/swagger-parser/issues/2144
+2134,Error: 'There are duplicate parameter values' encountered when parsing OpenAPI spec,open,https://github.com/swagger-api/swagger-parser/issues/2134
+2087,"Fix ref handling in CB, AnyOf & examples (fixes : #2086)",closed,https://github.com/swagger-api/swagger-parser/pull/2087
+2060,resolveFully breaks 3.0 spec for headers via $ref in request and response,open,https://github.com/swagger-api/swagger-parser/issues/2060
+2052,[Bug]: When using ResolveFully Schema references to other files are replaced twice,open,https://github.com/swagger-api/swagger-parser/issues/2052
+2032,[Bug]: Resolving fails when local component of a nested reference does not contain the #,open,https://github.com/swagger-api/swagger-parser/issues/2032
+2006,ResolveFully + ResolveAllOf doesn't fully resolve schema with type: object when allOf refs have items,open,https://github.com/swagger-api/swagger-parser/issues/2006
+1975,Referenced examples are never resolved,open,https://github.com/swagger-api/swagger-parser/issues/1975
+1958,[Bug]: Schema example gets dropped during parsing when using compose,open,https://github.com/swagger-api/swagger-parser/issues/1958
+1950,"[Bug]: Infinite loop when parsing openapi.yaml using ParseOptions(resolve:true, resolveFully:true, resolveCombinators:false)",open,https://github.com/swagger-api/swagger-parser/issues/1950
+1946,[Bug]: resolveFully option does not work with nullable allOf references,open,https://github.com/swagger-api/swagger-parser/issues/1946
+1938,[Bug]: swagger-parser doesn't handle not: properly when inside anyOf: / oneOf: / allOf:,open,https://github.com/swagger-api/swagger-parser/issues/1938
+1920,[Feature]: support examples by reference in parameters,open,https://github.com/swagger-api/swagger-parser/issues/1920
+1919,[Bug]: References in callbacks are not resolved when using ParseOptions.setResolve(true),open,https://github.com/swagger-api/swagger-parser/issues/1919
+1897,"[Bug]: Schema with oneOf/anyOf/allOf and type: string, null (OpenAPI 3.1) is resolved incorrectly",open,https://github.com/swagger-api/swagger-parser/issues/1897
+1874,Local refs between different files not being resolved,open,https://github.com/swagger-api/swagger-parser/issues/1874
+1861,[Bug]: Invalid $ref causes Exception instead of message,open,https://github.com/swagger-api/swagger-parser/issues/1861
+1857,Parser is mixing examples from multiple files,open,https://github.com/swagger-api/swagger-parser/issues/1857
+1854,Swagger parser resolves schemas more than once resulting in wrong refs,open,https://github.com/swagger-api/swagger-parser/issues/1854
+1843,[Bug]: Impossible to parse remote openapi definitions having circular reference without setting resolveFully to true,open,https://github.com/swagger-api/swagger-parser/issues/1843
+1798,resolveFully = true causes stackoverflow on circular refs,open,https://github.com/swagger-api/swagger-parser/issues/1798
+1793,[Bug]: ResolverFully discards formats when parsing anyOf/oneOf,open,https://github.com/swagger-api/swagger-parser/issues/1793
+1780,Unused $ref aren't resolved so components are not added,open,https://github.com/swagger-api/swagger-parser/issues/1780
+1778,Parser parses x- property as extension and converts value to string,open,https://github.com/swagger-api/swagger-parser/issues/1778
+1777,allOf resolution loses required,open,https://github.com/swagger-api/swagger-parser/issues/1777
+1776,OpenAPIResolver loses externalDocs reference,open,https://github.com/swagger-api/swagger-parser/issues/1776
diff --git a/swagger-parser/issues/README.md b/swagger-parser/issues/README.md
new file mode 100644
index 0000000000..08d10a0733
--- /dev/null
+++ b/swagger-parser/issues/README.md
@@ -0,0 +1,120 @@
+# Swagger Parser Issue Analysis
+
+This directory contains comprehensive analyses of GitHub issues from the swagger-parser project.
+
+## Overview
+
+The goal of this analysis is to:
+- Document the current state of open issues in the swagger-parser project
+- Provide technical analysis to help maintainers understand and prioritize issues
+- Identify root causes, impacts, and potential solutions
+- Group related issues and identify patterns
+
+## Analysis Structure
+
+Each analysis file follows a standardized template (defined in `/.github/analyze-issue.md`) that includes:
+
+1. **Issue Summary** - Basic metadata and classification
+2. **Problem Description** - Clear explanation of the issue
+3. **Technical Analysis** - Affected components, root cause, and impact assessment
+4. **Reproduction** - Steps to reproduce and test cases
+5. **Related Issues** - Dependencies and related problems
+6. **Solution Approach** - Proposed fixes and implementation guidance
+7. **Additional Notes** - Recommendations and priority assessment
+
+## Batch Organization
+
+Issues are analyzed in batches of 11 from the `data/swagger-parser/issues.csv` file:
+
+### Batch 1 (Issues 2275-2060) ✅ COMPLETE
+
+1. **parser-2275.md** - [Feature] Cache deserialization results for $ref
+2. **parser-2271.md** - [Bug] Validation regression in OpenAPI 3.1 external refs
+3. **parser-2216.md** - [Bug] Parameters incorrectly inlined with resolve=true
+4. **parser-2149.md** - Enhancement to collect all errors instead of stopping on first
+5. **parser-2148.md** - Feature request to reduce library dependencies
+6. **parser-2147.md** - [Bug] GraalVM native executable compatibility
+7. **parser-2145.md** - [Bug] additionalProperties not resolved with resolveFully
+8. **parser-2144.md** - [Bug] Json31 incorrectly adds type: object to anyOf schemas
+9. **parser-2134.md** - [Bug] False duplicate parameter errors
+10. **parser-2087.md** - [PR] Fix for discriminator mapping, callbacks, and examples
+11. **parser-2060.md** - [Bug] resolveFully breaks headers in OpenAPI 3.0
+
+### Batch 2 (Issues 2052-1897) - Pending
+
+To be analyzed in the second batch.
+
+### Batch 3 (Issues 1874-1776) - Pending
+
+To be analyzed in the third batch.
+
+## Key Findings
+
+### Common Themes
+
+Several patterns emerge from the first batch analysis:
+
+1. **Resolution Issues** (7 issues) - Problems with `resolve` and `resolveFully` options:
+ - Parameters being inlined instead of referenced (#2216)
+ - Headers containing invalid fields (#2060)
+ - additionalProperties not resolved (#2145)
+ - External refs with $defs failing (#2271)
+
+2. **Performance** (1 issue):
+ - Deserialization caching needed for large projects (#2275)
+
+3. **Validation/Error Handling** (2 issues):
+ - Collecting multiple errors instead of failing on first (#2149)
+ - False positive duplicate parameter errors (#2134)
+
+4. **Compatibility** (2 issues):
+ - GraalVM native image support (#2147)
+ - Dependency reduction request (#2148)
+
+5. **Schema Processing** (1 issue):
+ - anyOf schemas getting incorrect type inference (#2144)
+
+### Priority Assessment
+
+**High Priority Issues:**
+- #2271 - Regression affecting OpenAPI 3.1 validation
+- #2216 - Breaks documented resolve behavior
+- #2060 - Generates invalid OpenAPI 3.0 specs
+- #2134 - Blocks parsing of real-world APIs
+
+**Medium Priority Issues:**
+- #2275 - Significant performance impact for large projects
+- #2147 - Blocks GraalVM adoption
+- #2145 - resolveFully incomplete implementation
+
+**Lower Priority / Discussion:**
+- #2148 - Architectural discussion, not a bug
+- #2149 - Enhancement for better error reporting
+- #2144 - Edge case in schema processing
+
+## Using These Analyses
+
+Maintainers can use these analyses to:
+
+1. **Prioritize work** - Impact and severity assessments help identify critical issues
+2. **Understand problems** - Detailed technical analysis explains root causes
+3. **Plan solutions** - Proposed approaches provide implementation guidance
+4. **Identify patterns** - Related issues can be addressed together
+5. **Engage community** - Users willing to contribute are noted
+
+## Contributing
+
+If you'd like to help analyze issues:
+
+1. Follow the template in `/.github/analyze-issue.md`
+2. Fetch complete issue details including all comments
+3. Provide thorough technical analysis
+4. Identify affected components and root causes
+5. Propose actionable solutions
+
+## Notes
+
+- These analyses are for documentation and prioritization purposes
+- They do not represent official project priorities or roadmap
+- Some analyses cover pull requests that fix related issues
+- Analysis accuracy depends on available information in the issue
diff --git a/swagger-parser/issues/parser-2060.md b/swagger-parser/issues/parser-2060.md
new file mode 100644
index 0000000000..98172b4af2
--- /dev/null
+++ b/swagger-parser/issues/parser-2060.md
@@ -0,0 +1,376 @@
+# Issue Analysis: #2060
+
+## Overview
+Analysis of GitHub issue for the swagger-parser project.
+
+## 1. Issue Summary
+- **Issue Number**: 2060
+- **Title**: resolveFully breaks 3.0 spec for headers via $ref in request and response
+- **Type**: Bug
+- **Status**: Open
+- **URL**: https://github.com/swagger-api/swagger-parser/issues/2060
+- **Created**: 2024-02-26
+- **Author**: david0
+
+## 2. Problem Description
+When using `resolveFully=true` with OpenAPI 3.0.3, the parser creates an inconsistency in how headers are resolved compared to parameters. Specifically:
+
+1. **External header references in parameters** are correctly resolved inline (dereferenced completely)
+2. **External header references in response headers** are moved to `#/components/headers/` but retain the `in:` field
+3. The resulting spec contains headers with `in: header` field, which is **invalid per OpenAPI 3.0 spec** (headers should not have an `in` field)
+4. This creates a broken reference that cannot be resolved by downstream tools
+
+The user reports that switching to OpenAPI 3.1.0 fixes the issue, but they cannot use 3.1 because openapi-generator doesn't support it yet.
+
+**Example Problem:**
+```yaml
+# Input: headers.yml
+XRequestId:
+ in: header # Invalid for headers, valid for parameters
+ name: X-Request-Id
+ schema:
+ type: string
+ required: false
+
+# Output after resolveFully in 3.0.3
+components:
+ parameters:
+ XRequestId:
+ name: X-Request-Id
+ in: header # Valid here
+ required: false
+ schema:
+ type: string
+ # Missing headers section - ref points to nowhere!
+
+paths:
+ /users/:
+ get:
+ parameters:
+ - name: X-Request-Id
+ in: header # Correctly inlined
+ required: false
+ schema:
+ type: string
+ responses:
+ "200":
+ headers:
+ X-Request-Id:
+ $ref: '#/components/headers/XRequestId' # ❌ Broken ref!
+```
+
+## 3. Technical Analysis
+
+### Affected Components
+- **Module**: `swagger-parser-v3`
+- **Primary Classes**:
+ - `io.swagger.v3.parser.processors.HeaderProcessor` - Handles header reference resolution
+ - `io.swagger.v3.parser.processors.ParameterProcessor` - Handles parameter reference resolution (working correctly)
+ - `io.swagger.v3.parser.ResolverFully` - Coordinates full resolution (resolveFully=true)
+ - `io.swagger.v3.parser.util.OpenAPIDeserializer` - Deserializes headers (allows `in:` field but doesn't set it)
+- **Configuration**: `ParseOptions.setResolveFully(true)`
+
+### Root Cause
+The issue stems from a fundamental misunderstanding in how the source file defines the header:
+
+1. **The source file `headers.yml` defines a PARAMETER, not a HEADER**:
+ ```yaml
+ XRequestId:
+ in: header # ← This makes it a Parameter object
+ name: X-Request-Id
+ ```
+ The presence of `in:` field means this is a Parameter object per OpenAPI spec.
+
+2. **The parser correctly identifies this as a Parameter** when used in `parameters:` section and resolves it to `#/components/parameters/`
+
+3. **The parser ALSO tries to use it as a Header** when referenced in `headers:` section, but:
+ - Headers don't have an `in:` field per spec
+ - The reference `$ref: 'headers.yml#/XRequestId'` points to a Parameter, not a Header
+ - When resolveFully processes it, it creates `#/components/headers/XRequestId` reference, but the actual object is stored in `#/components/parameters/`
+
+4. **Core issue**: The parser allows mixing Parameter and Header definitions because:
+ - `OpenAPIDeserializer.HEADER_KEYS` includes `"in"` for backward compatibility
+ - `HeaderProcessor` doesn't validate that referenced objects are actually Headers
+ - No validation prevents using a Parameter definition as a Header
+
+### Impact Assessment
+- **Severity**: High (produces invalid OpenAPI spec, breaks downstream tools)
+- **User Impact**:
+ - Affects users migrating from OpenAPI 2.0 (Swagger) who used parameter definitions for headers
+ - Affects users trying to reuse header definitions in both parameters and response headers
+ - Blocks usage with openapi-generator which requires valid 3.0 specs
+- **Spec Compliance**: Produces **invalid OpenAPI 3.0** output
+- **Workaround Available**: Yes - multiple options:
+ 1. **Separate definitions**: Create separate Parameter and Header definitions
+ 2. **Upgrade to 3.1**: Use OpenAPI 3.1.0 (but openapi-generator doesn't support it)
+ 3. **Don't use resolveFully**: Keep references unresolved
+ 4. **Remove `in:` field**: Define headers without `in:` field in source
+
+## 4. Reproduction
+- **Reproducible**: Yes
+- **Steps**:
+ 1. Create an OpenAPI 3.0.3 spec file
+ 2. Create external file `headers.yml` with a parameter definition containing `in: header`
+ 3. Reference this definition in both `parameters:` and response `headers:` sections
+ 4. Parse with `resolveFully=true`
+ 5. Observe that response header creates broken reference to `#/components/headers/`
+
+- **Test Case Available**: Yes, provided in issue description
+- **Minimal Example**:
+ ```java
+ OpenAPIV3Parser parser = new OpenAPIV3Parser();
+ ParseOptions options = new ParseOptions();
+ options.setResolveFully(true);
+ var api = parser.read(file, null, options);
+ String content = Yaml.pretty(api);
+ // Output contains broken $ref: '#/components/headers/XRequestId'
+ // But component is stored in #/components/parameters/XRequestId
+ ```
+
+## 5. Related Issues and Context
+
+### Dependencies
+- Related to fundamental difference between Parameter and Header objects in OpenAPI spec
+- May relate to other issues involving mixed usage of Parameters and Headers
+- Connected to OpenAPI 2.0 → 3.0 migration (Swagger 2.0 used parameters for headers)
+
+### Version Information
+- **Affected versions**: All versions supporting OpenAPI 3.0
+- **Works in**: OpenAPI 3.1 (per user report)
+- **Reported on**: OpenAPI 3.0.3
+
+### Why 3.1 Works Differently
+Based on codebase analysis:
+- OpenAPI 3.1 has enhanced handling in `OpenAPI31Traverser.java`
+- 3.1 may be more lenient with `in:` field in headers
+- 3.1 processing might strip the `in:` field during resolution
+- 3.1 has different schema validation rules (aligned with JSON Schema)
+
+## 6. Solution Approach
+
+### Proposed Solutions
+
+#### Option 1: Validation and Error Reporting (Recommended)
+**Add validation to detect and report when Parameter definitions are used as Headers:**
+
+```java
+// In HeaderProcessor or ExternalRefProcessor
+public Header processRefToExternalHeader(String $ref, RefFormat refFormat, OpenAPI openAPI) {
+ // ... existing code ...
+
+ // Validate that referenced object is actually a Header, not a Parameter
+ if (resolvedHeader.getIn() != null) {
+ // This is a Parameter, not a Header
+ throw new IllegalArgumentException(
+ "Header reference points to a Parameter definition. " +
+ "Headers must not contain 'in' field. " +
+ "Referenced at: " + $ref
+ );
+ }
+
+ return resolvedHeader;
+}
+```
+
+**Pros**:
+- Clear error message helps users understand the problem
+- Enforces spec compliance
+- No ambiguity
+
+**Cons**:
+- Breaking change - existing (invalid) specs will fail to parse
+- Users must fix their specs
+
+#### Option 2: Auto-Convert Parameter to Header (Lenient)
+**Strip the `in:` field when a Parameter is used as a Header:**
+
+```java
+// In ResolverFully.resolveHeader() or HeaderProcessor
+private Header resolveHeader(Header header) {
+ // ... existing resolution code ...
+
+ // If resolved header has 'in' field, it's actually a Parameter
+ // Convert it to a proper Header by removing the 'in' field
+ if (resolvedHeader instanceof Parameter) {
+ Header convertedHeader = new Header();
+ convertedHeader.setDescription(resolvedHeader.getDescription());
+ convertedHeader.setRequired(resolvedHeader.getRequired());
+ convertedHeader.setDeprecated(resolvedHeader.getDeprecated());
+ convertedHeader.setSchema(resolvedHeader.getSchema());
+ // ... copy other compatible fields ...
+ // Note: NOT copying 'in' field
+ return convertedHeader;
+ }
+
+ return resolvedHeader;
+}
+```
+
+**Pros**:
+- Backward compatible - doesn't break existing specs
+- Helps users migrate from 2.0 patterns
+- User-friendly
+
+**Cons**:
+- Silently accepts invalid input
+- May hide real errors
+- Could mask specification mistakes
+
+#### Option 3: Consistent Component Storage
+**When resolveFully encounters a Parameter used as Header, store it in both locations:**
+
+```java
+// In ResolverFully or ComponentProcessor
+// When processing header $ref that points to parameter:
+if (resolvedObject instanceof Parameter && usedAsHeader) {
+ // Store in both components/parameters AND components/headers
+ components.addParameters(refName, (Parameter) resolvedObject);
+
+ // Create Header version (without 'in' field)
+ Header headerVersion = convertParameterToHeader((Parameter) resolvedObject);
+ components.addHeaders(refName, headerVersion);
+}
+```
+
+**Pros**:
+- Ensures references resolve correctly
+- Supports reuse patterns
+
+**Cons**:
+- Creates duplicate components
+- Hides the underlying spec issue
+- May confuse users about canonical source
+
+### Recommended Approach
+**Option 1 (Validation) with clear migration guidance:**
+
+1. **Add validation** that detects Parameter-as-Header usage
+2. **Provide helpful error messages** that explain:
+ - What went wrong (Parameter used as Header)
+ - How to fix it (create separate Header definition)
+ - Example of correct usage
+3. **Document migration path** from 2.0 to 3.0 header patterns
+4. **Consider deprecation period**:
+ - Phase 1: Warning only (log warning, continue processing)
+ - Phase 2: Error (fail parsing)
+
+### Implementation Complexity
+- **Effort Estimate**: Low-Medium
+ - Code change is localized to HeaderProcessor and validation
+ - Need comprehensive test coverage
+ - Need clear documentation and migration guide
+ - Error messages are critical for user experience
+
+- **Risks**:
+ - **Breaking change**: Existing invalid specs will fail
+ - **User friction**: Users must update their specs
+ - **Migration burden**: Need clear guidance and examples
+
+### Testing Requirements
+
+#### Unit Tests Needed
+- Test Parameter with `in: header` referenced from `parameters:` → should work
+- Test Parameter with `in: header` referenced from response `headers:` → should error/warn
+- Test proper Header (no `in:` field) referenced from `headers:` → should work
+- Test resolveFully with mixed valid/invalid usage
+- Test error message content and clarity
+
+#### Integration Tests Needed
+- End-to-end parsing with external parameter file
+- Cross-file references with both valid and invalid patterns
+- OpenAPI 3.0 vs 3.1 behavior differences
+- Interaction with openapi-generator and other downstream tools
+
+#### Backward Compatibility
+- **Document breaking change** in release notes
+- **Provide migration examples** in documentation
+- **Consider feature flag** to enable strict validation:
+ ```java
+ options.setStrictHeaderValidation(true); // Opt-in for now
+ ```
+- **Warn before breaking**: Log warnings in one version, make it error in next
+
+## 7. Additional Notes
+
+### Root Cause Summary
+This issue is fundamentally about **spec ambiguity and mixed usage patterns**:
+
+1. **OpenAPI 2.0 (Swagger)** used Parameter objects for headers
+2. **OpenAPI 3.0** separated Parameters and Headers into distinct types
+3. **User's source file** defines a Parameter (has `in:` field) but uses it as both
+4. **Parser allows this** because `HEADER_KEYS` includes `"in"` for compatibility
+5. **resolveFully exposes the problem** by trying to store it in components
+
+### Spec Compliance Details
+
+**OpenAPI 3.0.3 Specification:**
+- **Parameter Object** MUST have `in` field (query/header/path/cookie)
+- **Header Object** MUST NOT have `in` field (location is implicit in headers map)
+- A definition with `in:` field is a Parameter, not a Header
+
+**Why the user's file is problematic:**
+```yaml
+XRequestId:
+ in: header # ← Makes this a Parameter Object
+ name: X-Request-Id
+ schema:
+ type: string
+```
+
+**Correct approach for reuse:**
+```yaml
+# parameters.yml - for use in parameters:
+XRequestIdParam:
+ in: header
+ name: X-Request-Id
+ schema:
+ type: string
+
+# headers.yml - for use in headers:
+XRequestIdHeader:
+ # NO 'in' field!
+ description: Request ID for tracing
+ schema:
+ type: string
+```
+
+### OpenAPI 3.1 Behavior
+The user reports this works in 3.1. Possible reasons:
+1. 3.1 may strip/ignore the `in:` field in headers during processing
+2. 3.1 validation is more lenient with mixed usage
+3. 3.1 has better backward compatibility handling
+4. 3.1 spec allows more flexibility (aligned with JSON Schema)
+
+**Recommendation**: Investigate 3.1 codebase to understand what makes it work, and potentially backport the lenient handling to 3.0 with appropriate warnings.
+
+### Questions to Address
+1. Should swagger-parser enforce strict spec compliance or be lenient for migration?
+2. Is there value in supporting "Parameter as Header" pattern for 2.0 migration?
+3. Should resolveFully automatically convert/adapt incompatible references?
+4. What is the policy on breaking changes for spec compliance?
+
+### Priority Assessment
+- **Priority**: Medium-High
+- **Justification**:
+ - Blocks openapi-generator integration for affected users
+ - Produces invalid spec output
+ - Common pattern for users migrating from 2.0
+ - Clear spec violation that should be addressed
+- **User Pain**: High (blocks toolchain usage)
+- **Spec Impact**: High (produces invalid OpenAPI)
+
+### Recommendations
+1. **Short term**: Document the correct pattern and workarounds
+2. **Medium term**: Add validation with helpful error messages
+3. **Long term**: Consider lenient mode for backward compatibility
+4. **Investigate**: Study OpenAPI 3.1 handling to understand why it works there
+5. **Document**: Add migration guide for 2.0 → 3.0 header patterns
+
+### Community Engagement
+- User has identified the problem clearly
+- User found workaround (using 3.1) but can't use it
+- No comments/discussion yet on the issue
+- Should engage user to understand:
+ - Migration context (coming from 2.0?)
+ - Why they defined headers with `in:` field
+ - Whether separate definitions would work for their use case
diff --git a/swagger-parser/issues/parser-2087.md b/swagger-parser/issues/parser-2087.md
new file mode 100644
index 0000000000..e2533ccb66
--- /dev/null
+++ b/swagger-parser/issues/parser-2087.md
@@ -0,0 +1,287 @@
+# Issue Analysis: #2086 / PR #2087
+
+## Overview
+Analysis of GitHub issue #2086 and its corresponding fix in Pull Request #2087 for the swagger-parser project.
+
+## 1. Issue Summary
+- **Issue Number**: 2086 (Fixed by PR #2087)
+- **Title**: [Bug]: Conflicting refs are merged instead of creating a new inline component / Discriminator mapping refs (anyOf) & callback refs not processed
+- **Type**: Bug
+- **Status**: Closed (Fixed in PR #2087, merged 2024-10-23)
+- **URL**: https://github.com/swagger-api/swagger-parser/issues/2086
+- **PR URL**: https://github.com/swagger-api/swagger-parser/pull/2087
+- **Created**: 2024-05-01
+- **Closed**: 2024-10-23
+- **Author**: anthochristen
+- **Merged by**: frantuma
+
+## 2. Problem Description
+
+The issue identified several critical bugs in how swagger-parser handles $ref resolution in specific OpenAPI contexts:
+
+### Problem 1: Discriminator Mapping References Not Resolved for anyOf
+When using discriminator mappings with `anyOf` schemas that contain relative path references, the parser fails to update the discriminator mapping paths after resolving the schema references. This works correctly for `oneOf` but not for `anyOf`.
+
+**Example:**
+```json
+"requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {"$ref": "../components/schemas/adoption_request_for_bird.json"},
+ {"$ref": "../components/schemas/adoption_request_for_cat.json"}
+ ],
+ "discriminator": {
+ "propertyName": "animal_type",
+ "mapping": {
+ "BIRD": "../components/schemas/adoption_request_for_bird.json",
+ "CAT": "../components/schemas/adoption_request_for_cat.json"
+ }
+ }
+ }
+ }
+ }
+}
+```
+
+**Result after parsing:**
+- anyOf schemas correctly resolved to `#/components/schemas/adoption_request_for_bird`
+- BUT discriminator mappings remain as `../components/schemas/adoption_request_for_bird.json`
+- This causes code generation to fail with "ERRORUNKNOWN" classes
+
+### Problem 2: Callback Path Item References Not Resolved
+When callbacks contain $ref to external schema files, the parser searches for the schema relative to the main OpenAPI file instead of relative to the callback's location.
+
+**Example:**
+```json
+"callbacks": {
+ "myCallback": {
+ "{$request.body#/callback_url}/start": {
+ "put": {
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "../../../schemas/payload.json"
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+}
+```
+
+**Problem:** The `payload.json` schema is searched from the base OpenAPI file path, not from the callback's relative path.
+
+### Problem 3: Parameter Example References Not Resolved
+Parameter examples using $ref are not resolved relative to their location, similar to the callback issue.
+
+### Impact on Code Generation
+The discriminator mapping issue is particularly critical because it breaks code generation entirely. The generator cannot resolve the type mapping and creates invalid code with "ERRORUNKNOWN" classes that fail compilation.
+
+## 3. Technical Analysis
+
+### Affected Components
+- **Module**: `swagger-parser-v3`
+- **Primary Classes**:
+ - `io.swagger.v3.parser.processors.SchemaProcessor` - Handles schema and discriminator processing
+ - `io.swagger.v3.parser.processors.ExternalRefProcessor` - Handles external reference resolution
+ - `io.swagger.v3.parser.processors.ParameterProcessor` - Handles parameter resolution
+- **Specific Methods**:
+ - `SchemaProcessor`: oneOf/anyOf discriminator handling
+ - `ExternalRefProcessor.processRefToExternalPathItem()` - Path item reference resolution
+ - Parameter example reference resolution
+
+### Root Cause
+
+**Discriminator Mapping (anyOf):**
+The parser had special handling for discriminator mappings in `oneOf` schemas but not for `anyOf` schemas. The code updated discriminator mapping paths after resolving schema refs for oneOf, but this logic was missing for anyOf.
+
+**Callback References:**
+The `processRefToExternalPathItem` method was not handling path items within callbacks correctly. It wasn't properly tracking the context/location of the callback to resolve relative references.
+
+**Parameter Examples:**
+Similar to callbacks, parameter examples with $ref were not being resolved with the correct base path context.
+
+### Impact Assessment
+- **Severity**: Critical/High
+ - Discriminator mapping issue breaks code generation completely
+ - Affects enterprise adoption (PayPal blocked from OAS 3.0 upgrade)
+ - No workaround for discriminator issue except restructuring specs
+- **User Impact**:
+ - High - Affects anyone using:
+ - anyOf with discriminator mappings and external refs
+ - Callbacks with relative references
+ - Parameter examples with references
+ - PayPal enterprise initiative was blocked by this issue
+- **Workaround Available**:
+ - Callback/parameter refs: Change refs to be relative from base directory (not ideal)
+ - Discriminator mapping: No effective workaround - breaks code generation
+
+## 4. Reproduction
+- **Reproducible**: Yes
+- **Test Case Available**: Yes - PR includes integration tests
+- **Steps**:
+ 1. Create OpenAPI spec with anyOf + discriminator using external refs
+ 2. Use relative paths in discriminator mapping
+ 3. Parse the spec
+ 4. Observe that discriminator mappings are not updated
+ 5. Attempt code generation - fails with ERRORUNKNOWN
+
+**Note:** The author notes these issues are NOT present in the npm swagger-parser library, indicating this is specific to the Java implementation.
+
+## 5. Related Issues and Context
+
+### Dependencies
+- This PR addresses issue #2086
+- Multiple commits address different aspects:
+ 1. Discriminator mapping for anyOf
+ 2. Parameter example ref resolution
+ 3. Array items with complex schemas
+ 4. Callback path item ref resolution
+
+### Version Information
+- **Affected versions**: All versions prior to the merge (pre-October 2024)
+- **Fixed in**: Will be in next release after 2024-10-23 merge
+- **Comparison**: npm swagger-parser does not have these issues
+
+### Timeline
+- Issue reported: 2024-05-01
+- PR created: 2024-05-01 (same day)
+- Multiple follow-ups and pings: May-October 2024
+- Enterprise escalation (PayPal): 2024-10-21
+- Finally merged: 2024-10-23
+- ~6 months from report to merge
+
+### Enterprise Impact
+PayPal's Product Manager for Java Frameworks escalated this issue, stating:
+- Blocks enterprise-level OAS 3.0 upgrade initiative
+- Code generation tool crucial for REST API development
+- Affects virtually all OAS3 specs using examples, parameters, discriminators, and callbacks
+- Without fix, developers forced to use workarounds that hinder reusability
+- Prevents API Platform team from testing and meeting customer needs
+
+## 6. Solution Approach
+
+### Implemented Solution (PR #2087)
+
+The PR implements fixes across four main areas:
+
+**1. Discriminator Mapping for anyOf**
+- Extended discriminator mapping handling in `SchemaProcessor` to include `anyOf`
+- Made oneOf and anyOf handling inclusive (both are processed)
+- Updates discriminator mapping paths when anyOf refs are resolved
+
+**2. Parameter Example Ref Resolution**
+- Added ref path resolution for parameter examples
+- Ensures examples are resolved relative to their definition location
+
+**3. Complex Schema Array Items**
+- Handles ref path resolution for array items containing complex schemas
+- Ensures nested references in array schemas are properly resolved
+
+**4. Callback Path Item References**
+- Refactored `processRefToExternalPathItem` in `ExternalRefProcessor`
+- Made it usable for path items within callbacks
+- Properly tracks context for relative reference resolution
+
+### Implementation Details
+- Each fix was implemented in dedicated commits
+- Includes integration tests for all scenarios
+- Backwards compatible - doesn't break existing functionality
+
+### Implementation Complexity
+- **Effort Estimate**: Medium-High
+ - Multiple interconnected components affected
+ - Requires deep understanding of ref resolution pipeline
+ - Complex test scenarios needed
+ - Author noted some spillover between commits
+
+- **Risks**:
+ - **Regression**: Changes to core ref resolution logic could affect other areas
+ - **Performance**: Additional ref processing might impact large specs
+ - **Edge cases**: Complex interaction between different ref types
+ - **Validation**: Need to ensure fix doesn't break other discriminator scenarios
+
+### Testing Requirements
+- **Unit tests needed**: ✓ Implemented
+ - Discriminator mapping with anyOf
+ - Callback ref resolution
+ - Parameter example refs
+ - Array items with refs
+
+- **Integration tests needed**: ✓ Implemented
+ - "Blanket IT type test" initially created
+ - More comprehensive tests added during review
+ - End-to-end parsing scenarios
+
+- **Backward compatibility**: ✓ Maintained
+ - oneOf discriminator handling still works
+ - Existing ref resolution not broken
+ - Component-based refs continue to work
+
+## 7. Additional Notes
+
+### Merge and Review Process
+- PR was created promptly (same day as issue)
+- Long review period (~6 months) before merge
+- Author pinged maintainers multiple times (May, June, October)
+- Enterprise user (PayPal) escalation helped prioritize
+- Finally merged by frantuma on 2024-10-23
+
+### Key Observations
+
+1. **Parity with npm parser**: The author noted these bugs don't exist in the npm swagger-parser, suggesting the Java implementation has specific issues with ref resolution that the JavaScript version handles correctly.
+
+2. **Enterprise adoption blocker**: This bug prevented PayPal from upgrading to OAS 3.0, demonstrating real-world enterprise impact beyond just technical correctness.
+
+3. **Code generation impact**: The discriminator mapping bug specifically breaks downstream tools (code generators), not just the parser itself.
+
+4. **Maintenance concerns**: The long time to merge (6 months) despite clear reproduction and fix suggests potential resource constraints in project maintenance.
+
+### Recommendations
+1. **✓ Merged** - Fix has been successfully integrated
+2. **Release soon** - Enterprise users are waiting for this fix
+3. **Document breaking scenarios** - Add to documentation which ref patterns are now supported
+4. **Cross-reference npm parser** - Consider reviewing npm implementation for other potential parity issues
+5. **Improve response time** - Consider ways to accelerate PR review for critical bugs
+
+### Questions Addressed
+1. ✓ Does it work for anyOf like oneOf? - Yes, now handled consistently
+2. ✓ Are callbacks resolved correctly? - Yes, refactored to handle callback context
+3. ✓ Do parameter examples work? - Yes, ref resolution added
+4. ✓ Is it backward compatible? - Yes, existing functionality preserved
+
+### Priority Assessment
+- **Priority**: Critical (at time of report)
+- **Status**: ✓ Resolved and merged
+- **Justification**:
+ - Broke code generation workflows
+ - Blocked enterprise OAS 3.0 adoption
+ - No workarounds for discriminator issue
+ - Affected common OpenAPI patterns
+- **Effort vs Benefit**: High benefit with manageable complexity
+
+### Community Engagement
+- Contributor provided fix with issue report
+- Responsive to maintainer requests
+- Multiple follow-ups showing commitment
+- Enterprise user provided business case for urgency
+- Active collaboration until merge
+
+### Lessons Learned
+1. **Feature parity**: Java and npm parsers should have consistent behavior
+2. **Test coverage**: These scenarios should have been caught by tests earlier
+3. **Response time**: Critical bugs affecting enterprises need faster review cycles
+4. **OpenAPI features**: anyOf, callbacks, and parameter examples are important features that need full support
+5. **Community PRs**: Contributors who provide fixes should be engaged quickly to maintain momentum
+
+### Post-Merge Actions Needed
+1. Include in next release notes with prominent mention
+2. Update documentation with newly supported ref patterns
+3. Notify affected users (especially PayPal team)
+4. Consider additional test coverage for edge cases
+5. Monitor for any regression reports after release
diff --git a/swagger-parser/issues/parser-2134.md b/swagger-parser/issues/parser-2134.md
new file mode 100644
index 0000000000..5c32cb75ff
--- /dev/null
+++ b/swagger-parser/issues/parser-2134.md
@@ -0,0 +1,208 @@
+# Issue Analysis: #2134
+
+## Overview
+Analysis of GitHub issue for the swagger-parser project.
+
+## 1. Issue Summary
+- **Issue Number**: 2134
+- **Title**: Error: `There are duplicate parameter values` encountered when parsing OpenAPI spec
+- **Type**: Bug
+- **Status**: Open
+- **URL**: https://github.com/swagger-api/swagger-parser/issues/2134
+- **Created**: 2024-10-30
+- **Author**: ayeshLK
+
+## 2. Problem Description
+The user is developing a Ballerina client connector for the SmartSheet REST API and encounters "duplicate parameter values" errors when parsing the official OpenAPI specification provided by SmartSheet. The parser reports duplicate parameter errors across hundreds of endpoints in the specification, even though the parameters appear to be properly defined using $ref references.
+
+The error pattern shows duplicates in path-level and operation-level parameters:
+- paths.'/favorites'(get).parameters. There are duplicate parameter values
+- paths.'/favorites/{favoriteType}'. There are duplicate parameter values
+- And similar errors for 200+ other endpoints
+
+Upon examination of the SmartSheet OpenAPI spec, the issue appears to stem from how the parser resolves and validates parameter references when the same parameter is referenced multiple times through $ref pointers.
+
+## 3. Technical Analysis
+
+### Affected Components
+- **Module**: `swagger-parser-v3`
+- **Primary Classes**:
+ - `io.swagger.v3.parser.util.OpenAPIDeserializer` - Parameter parsing and validation
+ - `io.swagger.v3.parser.util.ParameterProcessor` - Parameter resolution and validation
+ - Parameter deduplication logic in path item and operation processing
+- **Specific Areas**:
+ - Parameter $ref resolution across operations
+ - Duplicate parameter detection logic
+ - Path-level vs operation-level parameter merging
+
+### Root Cause
+The SmartSheet OpenAPI spec uses a pattern where common parameters (like `page`, `pageSize`, `includeAll`, etc.) are defined in one operation and then referenced from other operations using JSON Pointer $refs:
+
+```json
+"/favorites": {
+ "get": {
+ "parameters": [
+ {"$ref": "#/paths/~1contacts/get/parameters/0"}, // includeAll
+ {"$ref": "#/paths/~1contacts/get/parameters/3"}, // page
+ {"$ref": "#/paths/~1contacts/get/parameters/4"}, // pageSize
+ {"name": "include", ...}
+ ]
+ }
+}
+```
+
+The parser's duplicate detection logic appears to incorrectly flag these referenced parameters as duplicates, likely because:
+1. The $ref resolution process may be creating multiple instances of the same parameter object
+2. The duplicate detection comparison logic may not properly handle dereferenced parameter objects
+3. There may be an issue with parameter identity checking when parameters come from external references
+
+This is unusual as the OpenAPI spec typically recommends defining reusable parameters in `#/components/parameters`, but the SmartSheet spec uses path-based references which is technically valid according to the OpenAPI 3.0 specification.
+
+### Impact Assessment
+- **Severity**: High - Prevents parsing of legitimate OpenAPI specifications
+- **User Impact**:
+ - Users cannot parse the official SmartSheet API specification
+ - Affects any OpenAPI spec that uses path-based parameter $refs for reusability
+ - Blocks code generation and validation workflows for affected specs
+- **Workaround Available**: Limited - Users would need to:
+ - Manually restructure the spec to move parameters to `#/components/parameters`
+ - Or create duplicate inline parameter definitions (defeats the purpose of $refs)
+ - Or use a different parser/validator
+
+## 4. Reproduction
+- **Reproducible**: Yes
+- **Steps**:
+ 1. Download the SmartSheet OpenAPI spec from the provided link
+ 2. Attempt to parse it using swagger-parser
+ 3. Observe hundreds of "duplicate parameter values" errors
+- **Test Case Available**: Yes - User provided the complete OpenAPI spec and error output
+- **Minimal Reproduction**:
+ ```json
+ {
+ "openapi": "3.0.3",
+ "paths": {
+ "/contacts": {
+ "get": {
+ "parameters": [
+ {"name": "page", "in": "query", "schema": {"type": "number"}}
+ ]
+ }
+ },
+ "/favorites": {
+ "get": {
+ "parameters": [
+ {"$ref": "#/paths/~1contacts/get/parameters/0"}
+ ]
+ }
+ }
+ }
+ }
+ ```
+
+## 5. Related Issues and Context
+
+### Dependencies
+- May relate to general $ref resolution issues in the parser
+- Could be connected to parameter validation and deduplication logic
+- No known duplicate issues at this time
+
+### Version Information
+- **Affected versions**: Not explicitly stated, but likely affects multiple versions
+- **Reported on**: Current version being used by reporter
+- This appears to be a long-standing issue with path-based parameter references
+
+### Related Specifications
+- OpenAPI 3.0.3 specification allows $ref in parameter arrays
+- JSON Pointer specification (RFC 6901) for reference resolution
+- SmartSheet API: https://smartsheet.redoc.ly/
+
+## 6. Solution Approach
+
+### Proposed Solution
+
+The fix should address how parameter references are resolved and compared for duplicate detection:
+
+**Option 1: Fix Duplicate Detection Logic (Recommended)**
+1. Modify the parameter duplicate detection to properly handle dereferenced parameters
+2. Use parameter identity based on the combination of `name` and `in` properties, not object reference equality
+3. Ensure that parameters resolved from $refs are properly compared by their semantic content
+
+**Option 2: Improve Parameter Resolution**
+1. Normalize all parameter $refs during the initial resolution phase
+2. Cache resolved parameter objects to avoid creating duplicate instances
+3. Update the duplicate detection to work with normalized parameters
+
+**Implementation Steps:**
+1. Locate the duplicate parameter validation logic in `OpenAPIDeserializer` or `ParameterProcessor`
+2. Modify the comparison logic to use parameter `name` + `in` combination as the uniqueness key
+3. Ensure dereferenced parameters are properly flattened before duplicate checking
+4. Add handling for path-based $refs in parameters (currently might only expect component-based refs)
+
+### Implementation Complexity
+- **Effort Estimate**: Medium
+ - Need to understand the current duplicate detection mechanism
+ - May need to refactor how parameters are resolved and stored
+ - Must ensure backward compatibility with component-based parameter refs
+ - Testing across various parameter reference patterns
+
+- **Risks**:
+ - **Breaking changes**: If the current behavior is relied upon to catch actual duplicates
+ - **Performance**: Additional parameter resolution and comparison logic might impact large specs
+ - **Edge cases**: Need to handle mixed path-based and component-based refs correctly
+ - **Spec compliance**: Must ensure solution aligns with OpenAPI 3.0 specification
+
+### Testing Requirements
+- **Unit tests needed**:
+ - Parameter duplicate detection with inline parameters
+ - Parameter duplicate detection with component-based $refs
+ - Parameter duplicate detection with path-based $refs
+ - Mixed parameter definitions (inline + refs)
+ - True duplicate detection (same name and 'in' location)
+ - Parameters with different 'in' locations (query, header, path, cookie)
+
+- **Integration tests needed**:
+ - Parse SmartSheet OpenAPI spec without errors
+ - Parse specs with various parameter reference patterns
+ - Validate that actual duplicates are still caught
+ - End-to-end parsing and validation workflow
+
+- **Backward compatibility**:
+ - Ensure existing specs with component-based refs continue to work
+ - Verify that legitimate duplicate parameter errors are still reported
+ - Test with various OpenAPI 3.0.x versions
+
+## 7. Additional Notes
+
+### Recommendations
+1. **Accept and prioritize** - This is a legitimate bug affecting real-world OpenAPI specifications
+2. **Validate against OpenAPI spec** - Ensure the fix aligns with the JSON Reference and OpenAPI 3.0 specifications
+3. **Consider parser consistency** - The user notes this issue may not exist in other parsers (like the npm swagger-parser), suggesting this is specific to the Java implementation
+4. **Add comprehensive tests** - Include the SmartSheet spec (or a minimal version) as a regression test
+
+### Questions to Address
+1. Why does the parser treat path-based parameter $refs differently than component-based $refs?
+2. Is the duplicate detection happening before or after $ref resolution?
+3. Are there performance implications of the current duplicate detection approach?
+4. Should we validate against the npm swagger-parser behavior for consistency?
+
+### Priority Assessment
+- **Priority**: High
+- **Justification**:
+ - Blocks parsing of legitimate, widely-used API specifications (SmartSheet)
+ - The error is a false positive that prevents valid use cases
+ - Affects developer workflows for code generation and API tooling
+- **Effort vs Benefit**: High benefit (enables parsing of real-world specs) with moderate implementation effort
+
+### Community Engagement
+- User has provided complete reproduction materials (spec + error log)
+- Clear error messages and affected endpoints documented
+- One positive reaction on the issue indicates others may be affected
+- Should request additional information:
+ - Exact swagger-parser version being used
+ - Whether this worked in any previous versions
+ - Java version and build environment details
+
+### Additional Context
+The SmartSheet OpenAPI spec's approach of using path-based references for parameter reuse is unconventional but valid according to the OpenAPI 3.0 specification. While the recommended practice is to use `#/components/parameters`, the spec explicitly allows $ref to point to any valid JSON Pointer location. The parser should handle both patterns correctly.
+
+This issue highlights the importance of supporting diverse OpenAPI authoring patterns, even when they deviate from common conventions, as long as they conform to the specification.
diff --git a/swagger-parser/issues/parser-2144.md b/swagger-parser/issues/parser-2144.md
new file mode 100644
index 0000000000..cb26b02a41
--- /dev/null
+++ b/swagger-parser/issues/parser-2144.md
@@ -0,0 +1,206 @@
+# Issue Analysis: #2144
+
+## Overview
+Analysis of GitHub issue for the swagger-parser project.
+
+## 1. Issue Summary
+- **Issue Number**: 2144
+- **Title**: [Open API 3.1] Json31 is incorrectly assuming that property containing `anyOf` is of type: object
+- **Type**: Bug
+- **Status**: Open
+- **URL**: https://github.com/swagger-api/swagger-parser/issues/2144
+- **Created**: 2024-12-12
+- **Author**: daniel-urrutia
+
+## 2. Problem Description
+When using `Json31.pretty()` to serialize an OpenAPI 3.1 schema, the parser is incorrectly adding `"type": "object"` to properties that contain `anyOf` but do not have an explicit type defined in the original schema. The user has a schema with a property that uses `anyOf` to allow either `string` or `null` types, but the serialized output includes an unexpected `"type": "object"` field that was not in the original schema definition.
+
+### Original Schema
+```json
+"image": {
+ "anyOf": [
+ {"type": "string"},
+ {"type": "null"}
+ ],
+ "title": "Image"
+}
+```
+
+### Incorrect Output
+```json
+"image": {
+ "type": "object",
+ "anyOf": [
+ {"type": "string"},
+ {"type": "null"}
+ ],
+ "title": "Image"
+}
+```
+
+## 3. Technical Analysis
+
+### Affected Components
+- **Module**: `swagger-core`
+- **Primary Class**: `io.swagger.v3.core.util.Json31`
+- **Specific Method**: `Json31.pretty()` method at line 38
+- **Related Component**: OpenAPI 3.1 JSON Schema serialization/deserialization
+- **Schema Type**: Properties using `anyOf`, `oneOf`, or `allOf` without explicit type
+
+### Root Cause
+The Json31 utility is likely applying default type inference logic that assumes properties without an explicit `type` field should be of type `object`. This is incorrect for OpenAPI 3.1 schemas where:
+1. JSON Schema 2020-12 allows schemas without explicit types
+2. `anyOf`, `oneOf`, `allOf` constructs define their own type constraints
+3. Adding `"type": "object"` conflicts with the actual types defined in `anyOf` (string and null)
+
+The issue appears to be in the serialization logic that tries to normalize or validate schemas but incorrectly applies object type as a default.
+
+### Impact Assessment
+- **Severity**: Medium-High (produces invalid/incorrect schema output)
+- **User Impact**: Users working with OpenAPI 3.1 schemas that use `anyOf`, `oneOf`, or `allOf` without explicit types will get incorrect schema output
+- **Data Correctness**: The serialized schema does not match the source schema, which could cause:
+ - Validation failures in downstream tools
+ - Incorrect code generation
+ - API contract mismatches
+- **Workaround Available**: No - users cannot prevent Json31 from adding the incorrect type field without modifying source code
+
+## 4. Reproduction
+- **Reproducible**: Yes
+- **Prerequisites**:
+ - OpenAPI 3.1 specification
+ - Schema with property using `anyOf`/`oneOf`/`allOf` without explicit type
+ - Call to `Json31.pretty()` for serialization
+- **Steps**:
+ 1. Create an OpenAPI 3.1 schema with a property containing `anyOf` but no `type` field
+ 2. Use `Json31.pretty()` to serialize the schema
+ 3. Observe that the output includes `"type": "object"` that wasn't in the original
+- **Test Case Available**: User provided schema example in issue
+
+### Minimal Reproduction
+```java
+// Schema with anyOf, no explicit type
+String schema = """
+{
+ "image": {
+ "anyOf": [
+ {"type": "string"},
+ {"type": "null"}
+ ],
+ "title": "Image"
+ }
+}
+""";
+
+// Use Json31.pretty()
+String output = Json31.pretty(schema);
+// Output incorrectly contains "type": "object"
+```
+
+## 5. Related Issues and Context
+
+### Dependencies
+- Related to OpenAPI 3.1 and JSON Schema 2020-12 support
+- May affect other schema composition keywords (`oneOf`, `allOf`)
+- Potentially related to other type inference issues in OpenAPI 3.1 handling
+
+### Version Information
+- **Affected versions**: Current version (issue reported on 2024-12-12)
+- **OpenAPI Version**: 3.1.x specifically (JSON Schema 2020-12 based)
+- **Fixed version**: Not yet fixed
+
+### Similar Issues
+- May be related to other OpenAPI 3.1 schema handling issues
+- Could be connected to type inference logic in schema processing
+
+## 6. Solution Approach
+
+### Proposed Solution
+The fix should ensure that `Json31.pretty()` and related serialization methods do not add implicit type fields to schemas that use composition keywords (`anyOf`, `oneOf`, `allOf`) without explicit types.
+
+**Implementation approach:**
+1. Identify where in Json31 (or related serialization code) the default `"type": "object"` is being added
+2. Add logic to detect when a schema uses composition keywords (`anyOf`, `oneOf`, `allOf`)
+3. Skip type inference/addition for schemas that:
+ - Have `anyOf`, `oneOf`, or `allOf` present
+ - Do not have an explicit `type` field
+ - Are following OpenAPI 3.1 / JSON Schema 2020-12 semantics
+4. Ensure the serialization preserves the exact schema structure without adding implicit types
+
+**Key considerations:**
+- OpenAPI 3.1 uses JSON Schema 2020-12 which allows schemas without types
+- Composition keywords (`anyOf`, `oneOf`, `allOf`) define their own type constraints
+- The serializer should be a lossless operation - output should match input structure
+
+### Implementation Complexity
+- **Effort Estimate**: Low-Medium
+ - Requires locating the type inference logic in Json31
+ - Need to add conditional logic to skip inference for composition schemas
+ - Should be a localized fix in serialization code
+ - Need to ensure no regression for schemas that legitimately need type inference
+
+- **Risks**:
+ - **Backward compatibility**: Need to ensure existing valid schemas still serialize correctly
+ - **Side effects**: Other parts of the code might depend on this type inference behavior
+ - **OpenAPI version handling**: Solution should only affect OpenAPI 3.1, not 3.0 or 2.0
+ - **Other composition keywords**: Fix should handle `oneOf` and `allOf` similarly
+
+### Testing Requirements
+- **Unit tests needed**:
+ - Schema with `anyOf` without type - should not add type field
+ - Schema with `oneOf` without type - should not add type field
+ - Schema with `allOf` without type - should not add type field
+ - Schema with explicit type and `anyOf` - should preserve explicit type
+ - Schema without composition keywords and without type - verify existing behavior
+
+- **Integration tests needed**:
+ - Full OpenAPI 3.1 spec with various `anyOf`/`oneOf`/`allOf` patterns
+ - Round-trip test: parse → serialize → parse → compare
+ - Verify serialized output matches original schema structure
+
+- **Regression tests needed**:
+ - OpenAPI 3.0 schemas should not be affected
+ - OpenAPI 2.0 (Swagger) schemas should not be affected
+ - Existing schemas that rely on type inference should still work
+
+- **Backward compatibility**:
+ - Ensure fix only applies to OpenAPI 3.1
+ - Verify no breaking changes for existing valid use cases
+ - Test with real-world OpenAPI 3.1 schemas
+
+## 7. Additional Notes
+
+### Recommendations
+1. **Accept as valid bug** - This is a clear schema corruption issue where output doesn't match input
+2. **Prioritize for OpenAPI 3.1 support** - Affects correctness of OpenAPI 3.1 schema handling
+3. **Investigate similar issues** - Check if other JSON Schema 2020-12 features are similarly affected
+4. **Add comprehensive tests** - Ensure robust handling of all composition keywords
+
+### Questions to Address
+1. Are other composition keywords (`oneOf`, `allOf`) affected similarly?
+2. Does this only affect `Json31.pretty()` or also other serialization methods?
+3. Is there similar type inference happening during parsing/deserialization?
+4. Should there be a configuration option to control type inference behavior?
+5. Are there other JSON Schema 2020-12 features that need similar fixes?
+
+### Priority Assessment
+- **Priority**: High
+- **Justification**:
+ - Produces incorrect/invalid schema output
+ - Affects OpenAPI 3.1 adoption and correctness
+ - No workaround available to users
+ - Relatively localized fix area
+- **Effort vs Benefit**: High benefit (correctness) for low-medium effort
+
+### OpenAPI 3.1 Considerations
+OpenAPI 3.1 adopted JSON Schema 2020-12 which has different semantics from the JSON Schema subset used in OpenAPI 3.0:
+- Schemas without `type` are valid
+- Composition keywords define their own constraints
+- Type inference should be avoided unless explicitly needed
+- The parser should preserve exact schema structure
+
+This issue highlights the importance of correctly implementing OpenAPI 3.1 / JSON Schema 2020-12 semantics rather than applying OpenAPI 3.0 assumptions.
+
+### Community Engagement
+- Issue is clear and well-documented with examples
+- Should engage with reporter if more details needed about their use case
+- Consider if this affects other users with similar schema patterns
diff --git a/swagger-parser/issues/parser-2145.md b/swagger-parser/issues/parser-2145.md
new file mode 100644
index 0000000000..c15ce4348a
--- /dev/null
+++ b/swagger-parser/issues/parser-2145.md
@@ -0,0 +1,338 @@
+# Issue Analysis: #2145
+
+## Overview
+Analysis of GitHub issue for the swagger-parser project regarding CLI tool's ability to convert Swagger 2.0 to OpenAPI 3.0.
+
+## 1. Issue Summary
+- **Issue Number**: 2145
+- **Title**: Feature Request (and design proposal): `swagger-parser-cli` to implement conversion of v2 to v3
+- **Type**: Feature Request / Enhancement
+- **Status**: Open
+- **URL**: https://github.com/swagger-api/swagger-parser/issues/2145
+- **Created**: 2024-12-15
+- **Author**: alexanderankin
+- **Labels**: Feature, 3.0 spec support, 2.0 support
+
+## 2. Problem Description
+The swagger-parser-cli module currently only supports parsing OpenAPI 3.0 specifications. It does not support converting Swagger 2.0 specifications to OpenAPI 3.0 format, even though the core parser library includes this functionality through the v2-converter module.
+
+Users who want to use the CLI tool to convert Swagger 2.0 specs to OpenAPI 3.0 must either:
+1. Write custom code using the programmatic API
+2. Use alternative tools
+3. Manually convert specifications
+
+The functionality exists in the codebase (via `SwaggerConverter` and `OpenAPIParser` classes) but is not exposed through the CLI tool.
+
+## 3. Technical Analysis
+
+### Affected Components
+- **Module**: `swagger-parser-cli`
+- **Primary Files**:
+ - `modules/swagger-parser-cli/src/main/java/io/swagger/v3/parser/SwaggerParser.java`
+ - `modules/swagger-parser-cli/pom.xml` (dependencies)
+- **Existing Infrastructure**:
+ - `io.swagger.parser.OpenAPIParser` (has v2 conversion logic)
+ - `io.swagger.v3.parser.converter.SwaggerConverter` (implements conversion)
+ - `io.swagger.v3.core.extensions.SwaggerParserExtension` (extension interface)
+
+### Root Cause
+Architectural decision - the CLI module was designed to only use `OpenAPIV3Parser` directly:
+
+**Current implementation:**
+```java
+final SwaggerParseResult result = new OpenAPIV3Parser()
+ .readLocation(args.get(INPUT_FILE), null, options);
+```
+
+**Available but unused pattern in OpenAPIParser:**
+```java
+for(SwaggerParserExtension extension : OpenAPIV3Parser.getExtensions()) {
+ output = extension.readLocation(url, auth, options);
+ if(output != null && output.getOpenAPI() != null) {
+ return output;
+ }
+}
+```
+
+The `SwaggerConverter` implements `SwaggerParserExtension` and would be automatically discovered if the CLI used the extension-based approach.
+
+### Impact Assessment
+- **Severity**: Low-Medium (feature gap, not a bug)
+- **User Impact**: CLI users cannot convert v2 to v3 specifications
+- **Use Case**: Migration projects, build pipelines, automation scripts
+- **Workaround Available**: Yes - use programmatic API or alternative tools
+
+## 4. Reproduction
+- **Reproducible**: Yes
+- **Steps**:
+ 1. Create a Swagger 2.0 specification file
+ 2. Run: `swagger-parser-cli -i swagger-2.0-file.yaml -o output.yaml`
+ 3. Observe: Parser fails to process Swagger 2.0 file
+ 4. Expected: Should convert to OpenAPI 3.0 and output result
+- **Test Case Available**: User provided complete implementation with test case
+- **Test File**: User included `fileWithSwagger.yaml` test resource
+
+## 5. Related Issues and Context
+
+### Dependencies
+- Requires adding `swagger-parser-v2-converter` dependency to CLI module
+- May relate to other feature requests for CLI enhancements
+- Aligns with multi-version support goals
+
+### Version Information
+- **Affected versions**: All current CLI versions
+- **Proposed for**: Next release
+- **Based on version**: 2.1.24 (user's implementation)
+
+### Design Proposal
+User provided detailed implementation proposal including:
+1. Dependency changes (pom.xml)
+2. Code changes (SwaggerParser.java)
+3. Test case (SwaggerParserCLITest.java)
+4. Test resource (fileWithSwagger.yaml)
+
+The proposal is production-ready and well-thought-out.
+
+## 6. Solution Approach
+
+### Proposed Solution
+
+The user's proposal involves three main changes:
+
+#### Change 1: Update Dependencies (pom.xml)
+Add two dependencies:
+```xml
+
+ io.swagger.parser.v3
+ swagger-parser
+ 2.1.24
+
+
+ io.swagger.parser.v3
+ swagger-parser-v2-converter
+ 2.1.24
+
+```
+
+Also change `slf4j-simple` scope from `test` to compile (for better logging).
+
+#### Change 2: Update Parser Logic (SwaggerParser.java)
+Replace direct `OpenAPIV3Parser` call with extension-based approach:
+
+```java
+SwaggerParseResult result;
+
+// Try parsing with all available extensions (v2 and v3)
+try {
+ result = new OpenAPIParser().readLocation(args.get(INPUT_FILE), null, options);
+} catch (Exception e) {
+ result = SwaggerParseResult.ofError(e.getMessage());
+}
+
+// Fallback to v3-only parser for familiar error messages
+if (result.getOpenAPI() == null) {
+ result = new OpenAPIV3Parser().readLocation(args.get(INPUT_FILE), null, options);
+}
+```
+
+This approach:
+- Tries all parser extensions (including v2 converter)
+- Falls back to v3-only parser for error reporting
+- Maintains backward compatibility
+- Minimal code changes
+
+#### Change 3: Add Test Coverage
+New test case:
+```java
+@Test
+public void validateOKWithSwaggerFormat(){
+ String[] args = new String[5];
+ args[0]="-i=src/test/resources/fileWithSwagger.yaml";
+ args[1]="-resolve";
+ args[2]="-resolveFully";
+ args[3]="-json";
+ args[4]="-o=target/test-classes/fileWithSwagger.json";
+
+ Path path = Paths.get(args[4].substring(3));
+ SwaggerParser.main(args);
+ Assert.assertTrue(Files.exists(path));
+}
+```
+
+### Implementation Complexity
+- **Effort Estimate**: Low
+ - Code changes: ~20 lines
+ - Dependency changes: ~10 lines
+ - Test additions: ~15 lines
+ - Total: Minimal changes, high impact
+
+- **Risks**:
+ - **Dependency size**: Additional dependencies increase CLI JAR size
+ - **Error handling**: Need to ensure error messages remain clear
+ - **Backward compatibility**: Must not break existing v3-only workflows
+ - **Performance**: Extension iteration adds minimal overhead
+ - **slf4j scope change**: Making slf4j-simple compile-scope may conflict with user's logging setup
+
+### Alternative Approaches
+
+#### Alternative 1: Explicit v2 Flag
+Add command-line flag for explicit v2 conversion:
+```bash
+swagger-parser-cli -i file.yaml -o output.yaml --convert-v2
+```
+
+**Pros:**
+- More explicit user intent
+- Can provide v2-specific options
+- Clearer error messages
+
+**Cons:**
+- More complex API
+- User must know input version
+- Additional code complexity
+
+#### Alternative 2: Auto-detection with Separate Command
+Create separate command for conversion:
+```bash
+swagger-parser-cli convert -i swagger-2.0.yaml -o openapi-3.0.yaml
+```
+
+**Pros:**
+- Clear separation of concerns
+- Can have conversion-specific options
+- Backward compatible
+
+**Cons:**
+- More code changes
+- CLI API expansion
+- Documentation updates needed
+
+### Recommended Approach
+**Use the user's proposal (extension-based auto-detection)** because:
+1. Minimal code changes
+2. Automatic version detection
+3. Maintains backward compatibility
+4. Leverages existing extension mechanism
+5. User already tested it
+6. Consistent with main parser API design
+
+### Testing Requirements
+- **Unit tests needed**:
+ - Test v2 to v3 conversion via CLI
+ - Test v3 parsing still works (regression)
+ - Test error handling for invalid files
+ - Test all CLI options work with v2 files (-resolve, -resolveFully, -json, -yaml)
+
+- **Integration tests needed**:
+ - End-to-end conversion with real Swagger 2.0 specs
+ - Test with referenced files
+ - Test with complex schemas
+ - Test output format options (JSON/YAML)
+
+- **Manual testing**:
+ - Build CLI JAR and test standalone
+ - Test with various Swagger 2.0 files from the wild
+ - Verify error messages are helpful
+ - Check JAR size increase is acceptable
+
+- **Backward compatibility**:
+ - Existing OpenAPI 3.0 files must parse identically
+ - All existing tests must pass
+ - Error messages should remain clear
+
+## 7. Additional Notes
+
+### Recommendations
+1. **Accept the feature request** - Well-defined, low-risk enhancement
+2. **Use the provided implementation** - User has done the work, review and merge
+3. **Consider slf4j-simple scope carefully** - May want to keep as 'test' or make it 'optional'
+4. **Add comprehensive documentation** - Document the v2 conversion capability
+5. **Consider adding version info to output** - Show which spec version was detected
+
+### Questions to Address
+1. **slf4j-simple scope**: Should it be compile or remain test/optional?
+ - User changed from `test` to compile
+ - This might conflict with user's own logging setup
+ - Consider making it `optional` instead
+
+2. **Error message clarity**: When v2 parsing fails, should we show:
+ - v2-specific error messages?
+ - Generic "unsupported format" message?
+ - Both v2 and v3 parser errors?
+
+3. **Documentation**: Where should v2 conversion be documented?
+ - README
+ - CLI help text
+ - User guide
+ - All of the above
+
+4. **Version detection**: Should the tool report which spec version it detected?
+ - Helpful for debugging
+ - Could be verbose flag option
+
+5. **JAR size**: Is the size increase acceptable?
+ - v2-converter adds dependencies
+ - Should measure before/after
+
+### Priority Assessment
+- **Priority**: Low-Medium
+- **Justification**:
+ - Nice-to-have feature enhancement
+ - Low implementation effort
+ - Community member provided working implementation
+ - Aligns with library capabilities
+ - Useful for migration scenarios
+- **Effort vs Benefit**: Very high benefit for minimal effort
+
+### Community Engagement
+- User alexanderankin provided complete implementation
+- No comments yet (issue is recent)
+- Should engage with user to:
+ - Review their implementation approach
+ - Discuss slf4j scope decision
+ - Get approval to use their code (contribution agreement)
+ - Ask for additional test cases
+
+### Implementation Checklist
+If accepting this feature:
+- [ ] Review user's implementation code
+- [ ] Decide on slf4j-simple scope (compile/test/optional)
+- [ ] Add user's code with proper attribution
+- [ ] Enhance test coverage beyond provided test
+- [ ] Update CLI help text
+- [ ] Update README documentation
+- [ ] Update CHANGELOG
+- [ ] Test JAR size increase
+- [ ] Manual testing with various Swagger 2.0 files
+- [ ] Ensure contribution agreement is signed
+
+### Technical Debt Considerations
+This change actually *reduces* technical debt by:
+1. Aligning CLI with library capabilities
+2. Using existing extension mechanism (proper architecture)
+3. Eliminating need for duplicate conversion tools
+4. Unifying v2 and v3 handling
+
+### Performance Considerations
+- Extension iteration adds minimal overhead (< 1ms typically)
+- v2 conversion has some overhead but is necessary for functionality
+- No performance regression for v3-only files
+- Could add caching if performance becomes issue
+
+### Security Considerations
+- No new security concerns
+- v2-converter already used in main library
+- Same validation and parsing rules apply
+- Should ensure error messages don't leak sensitive info
+
+### Related Tools and Ecosystem
+Similar functionality exists in:
+- Swagger Editor (web-based)
+- Swagger CLI (separate tool)
+- Various online converters
+
+Adding this to swagger-parser-cli provides:
+- Offline conversion
+- Scriptable/automatable
+- Single tool solution
+- Consistent with library API
diff --git a/swagger-parser/issues/parser-2147.md b/swagger-parser/issues/parser-2147.md
new file mode 100644
index 0000000000..9024d073b1
--- /dev/null
+++ b/swagger-parser/issues/parser-2147.md
@@ -0,0 +1,207 @@
+# Issue Analysis: #2147
+
+## Overview
+Analysis of GitHub issue for the swagger-parser project regarding GraalVM native executable compatibility.
+
+## 1. Issue Summary
+- **Issue Number**: 2147
+- **Title**: cannot deserialize from Object value (Grallvm native executable)
+- **Type**: Bug / Compatibility Issue
+- **Status**: Open
+- **URL**: https://github.com/swagger-api/swagger-parser/issues/2147
+- **Created**: 2024-12-29
+- **Author**: YunaBraska
+
+## 2. Problem Description
+When using swagger-parser in GraalVM native executables, the parser mostly returns empty OpenAPI objects without errors. In some cases, it throws deserialization errors indicating that Jackson cannot construct instances of swagger model classes (e.g., `io.swagger.v3.oas.models.media.ArraySchema`) due to missing reflection configuration. The error message specifically states "this appears to be a native image, in which case you may need to configure reflection for the class that is to be deserialized."
+
+The user attempted to initialize swagger models at runtime using `--initialize-at-run-time=io.swagger.v3.oas.models` but this did not resolve the issue.
+
+## 3. Technical Analysis
+
+### Affected Components
+- **Module**: Core swagger-parser and swagger-parser-v2-converter
+- **Primary Classes**:
+ - `io.swagger.v3.oas.models.media.ArraySchema`
+ - All model classes in `io.swagger.v3.oas.models.*` package
+ - `io.swagger.v3.parser.converter.SwaggerConverter` (line 1188)
+ - `com.fasterxml.jackson.databind.ObjectMapper` (deserialization)
+- **Configuration**: GraalVM native-image reflection configuration
+- **Parser Process**: Swagger 2.0 to OpenAPI 3.0 conversion during parsing
+
+### Root Cause
+GraalVM's native image compilation uses ahead-of-time (AOT) compilation and requires explicit configuration for reflection-based operations. Jackson's deserialization relies heavily on reflection to:
+1. Instantiate classes without no-arg constructors
+2. Discover and invoke property setters
+3. Handle polymorphic type resolution
+
+The swagger-parser library does not include GraalVM native-image metadata (reflect-config.json) for the model classes, causing Jackson to fail when deserializing YAML/JSON into model objects during native execution.
+
+### Impact Assessment
+- **Severity**: Medium-High (blocks GraalVM native image adoption)
+- **User Impact**: Users attempting to build native executables with GraalVM cannot use swagger-parser
+- **Use Case**: Increasingly important as GraalVM native images gain popularity for faster startup and lower memory footprint
+- **Workaround Available**: Yes - Manual reflection configuration required (see comment by YunaBraska)
+
+## 4. Reproduction
+- **Reproducible**: Yes
+- **Steps**:
+ 1. Create a Java project with swagger-parser dependency
+ 2. Build as GraalVM native executable using `native-image`
+ 3. Attempt to parse any OpenAPI 2.0 (Swagger) file
+ 4. Observe deserialization errors or empty OpenAPI objects
+- **Test Case Available**: User provided example YAML file (books.yaml)
+- **Environment**:
+ - GraalVM native-image
+ - Java 22 (based on stack trace)
+ - Swagger 2.0 specification format
+
+## 5. Related Issues and Context
+
+### Dependencies
+- Related to Jackson's GraalVM compatibility
+- May affect other Jackson-based parsing libraries
+- Similar issues likely exist in other swagger-api ecosystem tools
+
+### Version Information
+- **Affected versions**: All versions (no native-image metadata included)
+- **Reported on**: Latest version (as of 2024-12-29)
+- **Jackson version**: Uses current Jackson dependency
+
+### Community Solutions
+User YunaBraska shared a working solution in their project [api-doc-crafter](https://github.com/YunaBraska/api-doc-crafter):
+1. Custom reflection configuration file at `src/main/resources/META-INF/native-image/berlin.yuna/api-doc-crafter/reflect-config.json`
+2. Dependency exclusions to minimize reflection needs
+3. Successfully builds GraalVM native executables with swagger-parser
+
+Additional discussion from EnricoDamini:
+- Some Swagger 2.0 files fail even with reflection config
+- Error suggests YAML is being parsed as JSON in native mode
+- Inconsistent behavior between different Swagger files
+
+## 6. Solution Approach
+
+### Proposed Solution
+
+#### Option 1: Include Native Image Metadata (Recommended)
+Add GraalVM native-image metadata to the swagger-parser modules:
+
+1. **Add reflect-config.json** to each module under `META-INF/native-image/io.swagger.parser.v3//`:
+ - Register all model classes in `io.swagger.v3.oas.models.*`
+ - Include all constructors, fields, and methods
+ - Register Jackson-related annotations
+
+2. **Add resource-config.json** if needed for resource loading
+
+3. **Test with GraalVM native-image** to validate completeness
+
+#### Option 2: Documentation Enhancement
+Document the GraalVM native-image requirements:
+1. Provide complete reflection configuration template
+2. Document required initialization settings
+3. List dependency exclusions if needed
+4. Provide working example project
+
+#### Option 3: Hybrid Approach (Best)
+Combine both options:
+1. Include default reflection configuration in the library
+2. Document how to extend/customize for specific use cases
+3. Provide example projects demonstrating native compilation
+
+### Implementation Complexity
+- **Effort Estimate**: Medium
+ - Generating initial reflection config: Low (can use GraalVM tracing agent)
+ - Testing across all model classes: Medium
+ - Ensuring completeness: Medium-High (many model classes)
+ - Documentation: Low
+ - Ongoing maintenance: Low (config needs updating when models change)
+
+- **Risks**:
+ - **Incomplete configuration**: Missing classes will cause runtime errors
+ - **Large binary size**: Registering all classes may increase native image size
+ - **Maintenance overhead**: Config must be updated when model classes change
+ - **Testing complexity**: Need GraalVM CI/CD pipeline for validation
+
+### Testing Requirements
+- **Unit tests needed**:
+ - None directly (reflection config is declarative)
+
+- **Integration tests needed**:
+ - Native image build tests in CI/CD
+ - Parse various OpenAPI/Swagger files in native executable
+ - Test all major model classes are properly deserialized
+ - Test both OpenAPI 3.0 and Swagger 2.0 files
+
+- **Manual testing**:
+ - Build native executables on multiple platforms (Linux, macOS, Windows)
+ - Test with GraalVM Community and Enterprise editions
+ - Validate with complex real-world API specifications
+
+- **Backward compatibility**:
+ - No breaking changes - metadata is purely additive
+ - Regular JVM execution unaffected
+
+## 7. Additional Notes
+
+### Recommendations
+1. **High priority for GraalVM adoption** - Native images are increasingly popular
+2. **Community has working solutions** - Leverage YunaBraska's implementation
+3. **Use GraalVM tracing agent** - Automate reflection config generation:
+ ```bash
+ java -agentlib:native-image-agent=config-output-dir=META-INF/native-image \
+ -jar app.jar [test scenarios]
+ ```
+4. **Consider GraalVM reachability metadata** - Contribute to [GraalVM reachability metadata repository](https://github.com/oracle/graalvm-reachability-metadata)
+
+### Questions to Address
+1. Should reflection config be included in the library or published separately?
+2. Which GraalVM versions should be officially supported?
+3. Should native-image testing be added to CI/CD pipeline?
+4. Are there performance implications of reflection in native images?
+5. Should the library use GraalVM-specific optimizations (e.g., substitutions)?
+
+### Known Limitations from Comments
+1. **YAML vs JSON parsing issue**: Some Swagger 2.0 files fail with "Unrecognized token 'swagger'" suggesting YAML parser might not be properly configured in native mode
+2. **SwaggerCompatConverter issues**: The Swagger 1.x/2.x converter appears to have additional GraalVM compatibility issues
+3. **Inconsistent behavior**: Different Swagger files behave differently in native mode
+
+### Technical Details from Stack Trace
+Error occurs in:
+```
+com.fasterxml.jackson.databind.ObjectMapper.convertValue()
+ -> io.swagger.v3.parser.converter.SwaggerConverter.convert() (line 1188)
+```
+
+Specific error:
+```
+InvalidDefinitionException: Cannot construct instance of
+`io.swagger.v3.oas.models.media.ArraySchema`: cannot deserialize from
+Object value (no delegate- or property-based Creator)
+```
+
+This indicates Jackson cannot find appropriate constructor/creator methods due to missing reflection metadata.
+
+### Priority Assessment
+- **Priority**: Medium-High
+- **Justification**:
+ - Blocks GraalVM adoption (growing trend)
+ - Affects developer experience
+ - Community has demonstrated need and provided solutions
+ - Increasingly important for cloud-native applications
+- **Effort vs Benefit**: High benefit for moderate effort
+
+### Community Engagement
+- User YunaBraska has working solution and shared implementation details
+- EnricoDamini experiencing same issue, confirming it's not isolated
+- Community actively seeking solutions
+- Reference project available: [api-doc-crafter](https://github.com/YunaBraska/api-doc-crafter)
+- Should engage with users to:
+ - Test proposed reflection configurations
+ - Validate completeness across different use cases
+ - Gather feedback on documentation needs
+
+### Related Resources
+- GraalVM Reflection Guide: https://www.graalvm.org/22.2/reference-manual/native-image/guides/build-with-reflection/
+- Working example: https://github.com/YunaBraska/api-doc-crafter
+- Reflection config: https://github.com/YunaBraska/api-doc-crafter/blob/main/src/main/resources/META-INF/native-image/berlin.yuna/api-doc-crafter/reflect-config.json
+- Dependency management: https://github.com/YunaBraska/api-doc-crafter/blob/main/pom.xml#L76-L122
diff --git a/swagger-parser/issues/parser-2148.md b/swagger-parser/issues/parser-2148.md
new file mode 100644
index 0000000000..692fb97be9
--- /dev/null
+++ b/swagger-parser/issues/parser-2148.md
@@ -0,0 +1,308 @@
+# Issue Analysis: #2148
+
+## Overview
+Analysis of GitHub issue for the swagger-parser project.
+
+## 1. Issue Summary
+- **Issue Number**: 2148
+- **Title**: Request for a Simplified Swagger Parser with Minimal Dependencies
+- **Type**: Feature Request / Enhancement / Architectural Discussion
+- **Status**: Open
+- **URL**: https://github.com/swagger-api/swagger-parser/issues/2148
+- **Created**: 2024-12-31
+- **Author**: YunaBraska
+
+## 2. Problem Description
+The user expresses concern about the extensive dependency footprint of swagger-parser, reporting that the library adds over 50 dependencies to their project. They highlight specific dependencies they consider problematic or unnecessary:
+
+**Dependencies criticized:**
+1. **SLF4J** - Considered unnecessary for a parser; clutters logs
+2. **com.github.java-json-tools** - Appears to be inactive/unmaintained
+3. **jakarta.xml.bind and com.sun.activation.jakarta** - Outdated, unreliable with newer Java versions
+4. **org.mozilla:rhino** - JavaScript engine (purpose unclear to user)
+5. **apache.httpclient** - Use case unclear
+6. **com.google.guava**, **org.apache.commons:commons-lang3**, **commons-io** - Questioned necessity for basic parsing
+
+The user proposes rebuilding the parser with:
+- Plain Java with minimal dependencies
+- Only essential dependencies like SnakeYAML and ObjectMapper (Jackson)
+- No reflection
+- Removal of outdated/dead dependencies
+- Focus on simplicity and performance
+
+## 3. Technical Analysis
+
+### Affected Components
+- **All modules**: This is an architectural concern affecting the entire project
+- **Primary modules**:
+ - `swagger-parser-v3` - Main parser implementation
+ - `swagger-parser-core` - Core models and interfaces
+ - `swagger-parser-safe-url-resolver` - URL resolution
+ - `swagger-parser-v2-converter` - Swagger 2.0 to OAS 3.0 conversion
+
+### Current Dependency Analysis
+
+Based on actual dependency tree for `swagger-parser-v3` (compile scope):
+
+**Direct Dependencies:**
+1. `io.swagger.core.v3:swagger-models` - Required (core OpenAPI models)
+2. `io.swagger.core.v3:swagger-core` - Required (core functionality)
+3. `io.swagger.parser.v3:swagger-parser-core` - Required (internal)
+4. `io.swagger.parser.v3:swagger-parser-safe-url-resolver` - Required (internal)
+5. `commons-io:commons-io` (2.20.0) - File I/O utilities
+6. `org.yaml:snakeyaml` (2.4) - YAML parsing
+7. `com.fasterxml.jackson.core:jackson-annotations` (2.19.0) - JSON parsing
+8. `com.fasterxml.jackson.core:jackson-databind` (2.19.0) - JSON parsing
+9. `com.fasterxml.jackson.dataformat:jackson-dataformat-yaml` (2.19.0) - YAML parsing
+
+**Transitive Dependencies (from swagger-core):**
+1. `jakarta.xml.bind:jakarta.xml.bind-api` (2.3.3)
+2. `jakarta.activation:jakarta.activation-api` (1.2.2)
+3. `org.apache.commons:commons-lang3` (3.18.0)
+4. `org.slf4j:slf4j-api` (2.0.9)
+5. `com.fasterxml.jackson.datatype:jackson-datatype-jsr310` (2.19.2)
+6. `io.swagger.core.v3:swagger-annotations` (2.2.37)
+7. `jakarta.validation:jakarta.validation-api` (2.0.2)
+
+**Total compile dependencies**: Approximately 18 dependencies (far fewer than "50+" claimed)
+
+**Note**: The user may be counting test dependencies, or dependencies from a different module (e.g., swagger-parser with all modules, or including all transitive dependencies recursively).
+
+### Dependency Justification
+
+**Necessary dependencies:**
+- **Jackson** (databind, core, annotations, dataformat-yaml): Essential for JSON/YAML parsing - core functionality
+- **SnakeYAML**: YAML parsing - essential for OpenAPI spec parsing
+- **swagger-models/swagger-core**: Core OpenAPI models - cannot be removed
+- **SLF4J (slf4j-api)**: Logging facade - industry standard, allows users to choose logging implementation
+
+**Utility dependencies:**
+- **commons-io**: File I/O utilities - could potentially be replaced with Java NIO
+- **commons-lang3**: String utilities, common operations - could potentially be replaced with custom code or Java standard library
+
+**Jakarta dependencies (from swagger-core):**
+- **jakarta.xml.bind**: XML binding support for OpenAPI models
+- **jakarta.activation**: Required by JAXB
+- **jakarta.validation**: Bean validation annotations
+
+**Dependencies NOT found in current compile scope:**
+- **com.github.java-json-tools**: Not in current dependency tree
+- **org.mozilla:rhino**: Not in current dependency tree (may be in test scope or other modules)
+- **apache.httpclient**: Not in current dependency tree (may be for remote URL fetching in some configurations)
+- **com.google.guava**: Not in compile scope (only in test scope according to pom.xml)
+
+### Root Cause
+The perceived "excessive dependencies" stem from:
+1. **Transitive dependencies from swagger-core** - The parser depends on swagger-core which brings its own dependencies
+2. **Different module or scope being examined** - The user may be looking at test dependencies or a different module
+3. **Dependency conflict resolution** - Build tools may pull in additional versions/dependencies
+4. **Historical dependencies** - Some mentioned dependencies may have been removed in newer versions
+
+### Impact Assessment
+- **Severity**: Low-Medium (this is a feature request, not a bug)
+- **User Impact**:
+ - Users concerned about dependency footprint
+ - Users in constrained environments (size-sensitive deployments)
+ - Users with security scanning concerns (more dependencies = more CVE surface area)
+ - Users who value minimalism and simplicity
+- **Workaround Available**: Yes - users can:
+ - Use dependency exclusions in their build tool
+ - Use alternative OpenAPI parsers with fewer dependencies
+ - Fork and create their own minimal version
+
+## 4. Reproduction
+- **Reproducible**: Partial
+- **Prerequisites**:
+ - Add swagger-parser to a Maven/Gradle project
+ - Examine full dependency tree including transitives
+- **Steps**:
+ 1. Add swagger-parser dependency to project
+ 2. Run `mvn dependency:tree` or `gradle dependencies`
+ 3. Count total dependencies (including transitives)
+- **Actual Result**: The actual compile scope dependencies for swagger-parser-v3 are ~18, not "50+"
+- **User's Count**: Likely includes test dependencies or all modules together
+
+## 5. Related Issues and Context
+
+### Dependencies
+- Related to overall architecture and design philosophy
+- Related to swagger-core project (many dependencies come from there)
+- May relate to previous issues about dependency management
+- Connected to security/CVE concerns about dependencies
+
+### Version Information
+- **Current version**: 2.1.39-SNAPSHOT
+- **swagger-core version**: 2.2.37
+- Dependencies mentioned as "outdated" are in swagger-core, not directly in swagger-parser
+
+### Historical Context
+- OpenAPI/Swagger ecosystem has evolved significantly
+- Jakarta namespace transition from javax (Java EE to Jakarta EE)
+- Some dependencies may have historical reasons (backward compatibility, feature parity)
+
+## 6. Solution Approach
+
+### Proposed Solutions
+
+**Option A: Minimal Dependency Audit and Cleanup**
+- Audit all dependencies for necessity
+- Remove or make optional dependencies that aren't strictly required
+- Replace utility libraries (commons-io, commons-lang3) with Java standard library where possible
+- Document why each dependency is needed
+
+**Option B: Modular Architecture**
+- Create a minimal core module with only essential dependencies
+- Move optional features to separate modules (e.g., URL resolution, validation, conversion)
+- Allow users to choose which modules to include
+- Example: `swagger-parser-minimal` vs `swagger-parser-full`
+
+**Option C: Dependency Shading/Internalization**
+- Use Maven Shade plugin or similar to internalize dependencies
+- Reduces visible dependency count for users
+- Prevents dependency conflicts
+- Increases JAR size but reduces dependency management complexity
+
+**Option D: Provide Alternative Implementations**
+- Create a `swagger-parser-lite` module with minimal dependencies
+- Focus on basic parsing only (no validation, no resolution, no conversion)
+- Use only Jackson and SnakeYAML
+- Document limitations clearly
+
+**Option E: Status Quo with Better Documentation**
+- Document and justify each dependency
+- Provide guidance on dependency exclusions
+- Clarify which dependencies are truly required vs optional
+- Explain how to use the parser with minimal dependencies
+
+### Recommended Approach
+**Hybrid of A + E:**
+1. **Conduct dependency audit** - Review all dependencies for necessity
+2. **Remove genuinely unnecessary dependencies** - If any exist
+3. **Create comprehensive documentation** - Explain each dependency's purpose
+4. **Provide exclusion guide** - Help users minimize dependencies for their use case
+5. **Consider modularization for future major version** - Break into core + optional modules
+
+### Implementation Complexity
+- **Effort Estimate**: High
+ - **Audit**: Low-Medium (review all dependencies, their usage, and alternatives)
+ - **Removal**: Medium-High (replacing utility libraries with standard library code)
+ - **Modularization**: High (requires architectural changes, extensive testing)
+ - **Documentation**: Low (document current dependencies and their purposes)
+
+- **Risks**:
+ - **Breaking changes**: Removing dependencies might break users who depend on transitive dependencies
+ - **Maintenance burden**: Replacing utility libraries means maintaining more custom code
+ - **Feature loss**: Some functionality might be tied to specific dependencies
+ - **Testing complexity**: Need to ensure all functionality works with fewer dependencies
+ - **Swagger-core dependency**: Many dependencies come from swagger-core, which is outside this project's control
+ - **Performance**: Custom implementations may not be as optimized as mature libraries
+
+### Testing Requirements
+- **Unit tests needed**:
+ - All existing tests must continue to pass
+ - Test with minimal dependency set
+ - Test with excluded optional dependencies
+
+- **Integration tests needed**:
+ - Parse various OpenAPI specs with minimal dependencies
+ - Verify functionality across different Java versions
+ - Test in different deployment environments (classpath, module-path)
+
+- **Backward compatibility**:
+ - Critical - must not break existing users
+ - Consider versioning strategy (major version bump if breaking)
+ - Provide migration guide if dependencies change
+
+## 7. Additional Notes
+
+### Recommendations
+1. **Investigate the "50+ dependencies" claim** - Determine exactly where the user is seeing this number
+2. **Audit dependencies** - Review each dependency for necessity and modern alternatives
+3. **Improve documentation** - Create a dependency justification document
+4. **Address swagger-core dependencies separately** - Many dependencies come from swagger-core; consider filing issues there
+5. **Consider user's security concerns** - Dependencies with CVEs are a valid concern; keep dependencies updated
+6. **Provide guidance, not just code** - Help users understand how to minimize dependencies for their use case
+
+### Addressing Specific Concerns
+
+**SLF4J:**
+- Industry standard logging facade
+- Allows users to plug in their preferred logging implementation
+- Minimal overhead (just an API)
+- Removing it would require either no logging or coupling to a specific implementation
+- **Recommendation**: Keep (it's just an API, very lightweight)
+
+**com.github.java-json-tools:**
+- **Not found in current dependency tree** - May have been removed already or in different module
+- **Recommendation**: Verify if still used anywhere; remove if obsolete
+
+**jakarta.xml.bind and jakarta.activation:**
+- Come from swagger-core for JAXB support
+- Needed for XML binding of OpenAPI models
+- Part of Jakarta EE standards
+- **Recommendation**: Keep (controlled by swagger-core); document why needed
+
+**org.mozilla:rhino:**
+- **Not found in current compile dependency tree** - May be test dependency or in other modules
+- **Recommendation**: If present, document use case or consider removal
+
+**apache.httpclient:**
+- **Not found in current compile dependency tree** for swagger-parser-v3
+- May be in swagger-parser-safe-url-resolver or for remote spec fetching
+- **Recommendation**: Make optional if possible; not needed for local file parsing
+
+**com.google.guava:**
+- **Currently only in test scope** for swagger-parser-v3
+- **Recommendation**: Keep in test scope; ensure not leaked to compile scope
+
+**commons-lang3 and commons-io:**
+- commons-lang3: From swagger-core (3.18.0)
+- commons-io: Direct dependency (2.20.0)
+- **Recommendation**: Review usage; replace with Java standard library where feasible
+
+### Questions to Address
+1. Can we create a minimal variant without breaking existing users?
+2. Which dependencies are truly optional vs required?
+3. What is the acceptable trade-off between dependency minimalism and code complexity?
+4. Should we address this in swagger-core first (since many dependencies come from there)?
+5. What is the users's actual use case - do they need full parsing or just basic functionality?
+6. Is the security/CVE concern the primary driver, or is it JAR size/simplicity?
+
+### Priority Assessment
+- **Priority**: Low-Medium
+- **Justification**:
+ - This is a valid concern but not a bug
+ - Current dependency count (~18 compile) is reasonable for the functionality provided
+ - Many dependencies are transitive from swagger-core
+ - User can already use exclusions to minimize dependencies
+- **Effort vs Benefit**: High effort for potentially modest benefit; better to improve documentation first
+
+### Alternative Solutions for Users
+Users concerned about dependencies today can:
+
+1. **Use dependency exclusions**:
+```xml
+
+ io.swagger.parser.v3
+ swagger-parser-v3
+ 2.1.39-SNAPSHOT
+
+
+
+
+```
+
+2. **Use only the minimal modules** they need
+
+3. **Consider alternative parsers** if dependency count is critical constraint
+
+4. **Shade dependencies** in their own project to internalize them
+
+### Long-term Vision
+Consider for future major version (3.0):
+- Modular architecture with minimal core
+- Optional modules for advanced features
+- Clear separation of parsing vs validation vs resolution
+- Modern Java standards (Java 11+ APIs instead of utility libraries)
+- Reduced reliance on reflection where possible
+- Cleaner dependency tree with all dependencies justified and documented
diff --git a/swagger-parser/issues/parser-2149.md b/swagger-parser/issues/parser-2149.md
new file mode 100644
index 0000000000..17c732386e
--- /dev/null
+++ b/swagger-parser/issues/parser-2149.md
@@ -0,0 +1,191 @@
+# Issue Analysis: #2149
+
+## Overview
+Analysis of GitHub issue for the swagger-parser project.
+
+## 1. Issue Summary
+- **Issue Number**: 2149
+- **Title**: OpenAPIV3Parser.resolve() should handle all errors in the entire spec
+- **Type**: Enhancement / Bug Fix
+- **Status**: Open
+- **URL**: https://github.com/swagger-api/swagger-parser/issues/2149
+- **Created**: 2025-01-09
+- **Author**: verve111
+
+## 2. Problem Description
+The user reports that when `OpenAPIV3Parser.resolve()` encounters an error during spec validation (e.g., incorrect path or wrongly defined component), the exception is caught by the try-catch block and causes the entire parsing process to stop immediately. This prevents the parser from collecting all errors across the entire spec - only the first error encountered is reported. The user requests the ability to collect all validation errors rather than stopping at the first one, which would provide more comprehensive feedback for spec validation.
+
+## 3. Technical Analysis
+
+### Affected Components
+- **Module**: `swagger-parser-v3`
+- **Primary Class**: `io.swagger.v3.parser.OpenAPIV3Parser`
+- **Specific Method**: `private SwaggerParseResult resolve(SwaggerParseResult result, List auth, ParseOptions options, String location)` (lines 208-266)
+- **Related Classes**:
+ - `io.swagger.v3.parser.OpenAPIResolver` - performs actual path and component resolution
+ - `io.swagger.v3.parser.reference.OpenAPIDereferencer` - handles OAS 3.1 dereferencing
+ - `io.swagger.v3.parser.util.ResolverFully` - full resolution processing
+ - Processor classes (e.g., `PathsProcessor`, `ComponentsProcessor`)
+
+### Root Cause
+The current implementation has a top-level try-catch block around the entire resolution logic (lines 213-264) that catches any exception, logs it, adds the error message to the result, and returns. This means:
+
+1. **For OAS 3.0 specs**: The `OpenAPIResolver.resolve()` method is called, which internally calls `pathProcessor.processPaths()` and `componentsProcessor.processComponents()`. If any exception occurs during these operations, it bubbles up to the top-level catch block and stops processing.
+
+2. **For OAS 3.1 specs**: The dereferencing process uses `OpenAPIDereferencer`, and similarly any exception will propagate to the top-level catch block.
+
+The issue is that exceptions are not caught and handled at a granular level (per path, per component, per reference) but rather at the top level, causing early termination of validation.
+
+### Impact Assessment
+- **Severity**: Medium
+- **User Impact**:
+ - Developers validating OpenAPI specs get incomplete feedback
+ - Must fix errors iteratively: fix one error, re-run, discover next error, repeat
+ - Slows down development and debugging workflow
+ - Particularly problematic for large specs with multiple issues
+- **Workaround Available**: No - users must run validation multiple times, fixing one error at a time
+
+## 4. Reproduction
+- **Reproducible**: Yes
+- **Prerequisites**:
+ - OpenAPI spec with multiple validation errors
+ - Errors in different paths or components
+ - Use `OpenAPIV3Parser.resolve()` with resolution enabled
+- **Steps**:
+ 1. Create an OpenAPI spec with multiple errors (e.g., invalid path definition + invalid component reference)
+ 2. Call `OpenAPIV3Parser.readLocation()` or `OpenAPIV3Parser.readContents()` with `ParseOptions.setResolve(true)`
+ 3. Observe that only the first error is reported in `SwaggerParseResult.getMessages()`
+- **Test Case Available**: No - would need to be created
+
+## 5. Related Issues and Context
+
+### Dependencies
+- This is related to the overall error handling and validation strategy
+- May relate to other validation/resolution error reporting issues
+- Connected to how validation messages are collected in `SwaggerParseResult`
+
+### Version Information
+- **Affected versions**: All versions (appears to be original design)
+- **Current version**: 2.1.39-SNAPSHOT (as of analysis)
+
+## 6. Solution Approach
+
+### Proposed Solution
+Implement granular error handling that continues processing even when errors are encountered. This requires:
+
+1. **Refactor resolution logic** to catch exceptions at the component/path/reference level rather than at the top level
+2. **Modify processor classes** to handle errors gracefully and continue processing remaining items
+3. **Enhance error collection** to aggregate all errors found during the entire resolution process
+4. **Maintain backward compatibility** by ensuring the same result structure is returned
+
+**Implementation approach:**
+
+**Option A: Add error handling in processor methods**
+- Modify `OpenAPIResolver.resolve()` to wrap individual path/component processing in try-catch blocks
+- Continue processing remaining items even if one fails
+- Collect all errors and add them to `resolveValidationMessages`
+
+**Option B: Add a "lenient" or "continue-on-error" mode**
+- Add a flag in `ParseOptions` (e.g., `setContinueOnError(boolean)`)
+- When enabled, catch exceptions at granular levels and continue processing
+- When disabled, maintain current fail-fast behavior
+- Provides backward compatibility for users who may depend on current behavior
+
+**Option C: Hybrid approach**
+- Make granular error handling the default behavior (most useful)
+- Ensure existing validation message collection is used properly
+- Add comprehensive error context (which path/component/reference failed)
+
+### Implementation Complexity
+- **Effort Estimate**: Medium
+ - Need to identify all locations where exceptions might be thrown during resolution
+ - Must add granular error handling in multiple processor classes
+ - Need to ensure error messages provide good context about what failed
+ - Requires understanding of both OAS 3.0 and OAS 3.1 resolution paths
+ - Testing across different error scenarios is time-consuming
+
+- **Risks**:
+ - **Behavioral change**: Users expecting fail-fast behavior might be surprised
+ - **Error cascades**: One error might cause downstream errors; need to handle gracefully
+ - **Performance**: Continuing after errors might be slower in some cases
+ - **Partial validation**: Some errors might mask other errors (e.g., missing referenced component)
+ - **Breaking change potential**: If implemented as default behavior without option to disable
+
+### Testing Requirements
+- **Unit tests needed**:
+ - Multiple errors in paths - verify all are collected
+ - Multiple errors in components - verify all are collected
+ - Mixed errors in paths and components
+ - OAS 3.0 spec with multiple errors
+ - OAS 3.1 spec with multiple errors
+ - Verify error messages contain sufficient context
+ - Test that valid parts of spec are still processed correctly
+
+- **Integration tests needed**:
+ - Large specs with errors in multiple locations
+ - Specs with both schema errors and reference errors
+ - External reference resolution with errors
+ - Nested reference errors
+
+- **Backward compatibility**:
+ - Ensure existing tests still pass
+ - Verify that specs with single error behave the same
+ - Consider adding option for fail-fast mode if implementing as default behavior
+
+## 7. Additional Notes
+
+### Recommendations
+1. **Accept the enhancement request** - This is a reasonable request that improves developer experience
+2. **Implement as configurable behavior** - Add `ParseOptions.setContinueOnError(boolean)` to allow users to choose
+3. **Consider making it the default** - Most users would benefit from seeing all errors at once, but provide way to disable
+4. **Improve error messages** - When collecting multiple errors, ensure each error message clearly indicates which path/component/reference failed
+5. **Document the behavior** - Clearly document the new error handling behavior and options
+
+### Questions to Address
+1. Should this be the default behavior or opt-in?
+2. What level of granularity is appropriate for error handling (per-path, per-operation, per-property)?
+3. Should validation continue after reference resolution errors (missing $ref targets)?
+4. How to handle cascading errors (where one error causes subsequent errors)?
+5. Should there be a maximum error limit to prevent performance issues with badly broken specs?
+
+### Priority Assessment
+- **Priority**: Medium
+- **Justification**: Significantly improves developer experience for spec validation, particularly for large specs or during initial development
+- **Effort vs Benefit**: Medium effort with good benefit for users working with complex specs
+
+### Implementation Notes
+The key areas to modify:
+
+1. **OpenAPIV3Parser.resolve()** (lines 208-266):
+ - Refactor try-catch to be more granular or add error handling mode
+
+2. **OpenAPIResolver.resolve()** and **OpenAPIResolver.resolve()** methods:
+ - Add try-catch around `pathProcessor.processPaths()` call
+ - Add try-catch around `componentsProcessor.processComponents()` call
+ - Continue processing even if errors occur
+
+3. **Processor classes** (PathsProcessor, ComponentsProcessor, etc.):
+ - Add error handling within iteration loops
+ - Ensure errors are collected and added to validation messages
+ - Continue processing remaining items after error
+
+4. **Dereferencing logic** (for OAS 3.1):
+ - Review `OpenAPIDereferencer.dereference()` for similar issues
+ - Ensure granular error handling in dereferencing chain
+
+### Related Code Sections
+Current error handling in `OpenAPIV3Parser.resolve()`:
+```java
+try {
+ if (options != null) {
+ if (options.isResolve() || options.isResolveFully()) {
+ // ... resolution logic
+ }
+ }
+} catch (Exception e) {
+ LOGGER.warn("Exception while resolving:", e);
+ result.getMessages().add(e.getMessage());
+}
+```
+
+This needs to be refactored to allow errors at different stages to be collected while continuing execution.
diff --git a/swagger-parser/issues/parser-2216.md b/swagger-parser/issues/parser-2216.md
new file mode 100644
index 0000000000..7842cb5802
--- /dev/null
+++ b/swagger-parser/issues/parser-2216.md
@@ -0,0 +1,306 @@
+# Issue Analysis: #2216
+
+## Overview
+Analysis of GitHub issue for the swagger-parser project.
+
+## 1. Issue Summary
+- **Issue Number**: 2216
+- **Title**: [Bug]: Parameters components shouldn't be inlined with resolve option set to true
+- **Type**: Bug
+- **Status**: Open
+- **URL**: https://github.com/swagger-api/swagger-parser/issues/2216
+- **Created**: 2025-08-05
+- **Author**: Curs3W4ll
+
+## 2. Problem Description
+
+When using the `resolve` option set to `true` in the OpenAPI parser, parameter references (`$ref`) pointing to external files are being incorrectly inlined instead of maintaining the reference to the component. According to the documentation, the `resolve` option should only resolve external/relative references by copying them into the components section while keeping the `$ref` references intact. However, the current behavior replaces the `$ref` with an inline version of the parameter definition.
+
+This breaks code generators and other tools that rely on parameter references to identify reusable parameter definitions. The component is still correctly populated in the `components` section, but the usage site loses its reference and becomes fully inlined.
+
+## 3. Technical Analysis
+
+### Affected Components
+- **Module**: `swagger-parser-v3`
+- **Primary Package**: `io.swagger.v3.parser`
+- **Parsing Options**: `ParseOptions.setResolve(true)`
+- **Affected Element**: External parameter references in OpenAPI specifications
+- **Related Classes**:
+ - `OpenAPIV3Parser` - Main parser class
+ - `ParseOptions` - Configuration for parsing behavior
+ - Reference resolution logic for parameters
+
+### Root Cause
+
+The parser's reference resolution logic treats parameter references differently from other reference types (like schemas or responses). When `resolve=true` is set:
+
+**Current (incorrect) behavior for parameters:**
+1. External $ref is encountered (e.g., `./test-components.yml#/components/parameters/TestIdQueryParameter`)
+2. External content is loaded and added to components section ✓
+3. **Parameter reference is completely inlined at usage site** ✗ (should keep internal $ref)
+4. Result: `$ref = null`, parameter definition is duplicated inline
+
+**Expected behavior (consistent with other types):**
+1. External $ref is encountered
+2. External content is loaded and added to components section ✓
+3. **External $ref is replaced with internal $ref** ✓ (e.g., `#/components/parameters/TestIdQueryParameter`)
+4. Result: `$ref = "#/components/parameters/TestIdQueryParameter"`, no duplication
+
+This discrepancy suggests that the parameter resolution code path has different logic than schemas/responses, likely treating parameters as if `resolveFully=true` was set instead of just `resolve=true`.
+
+### Impact Assessment
+- **Severity**: High
+- **User Impact**: Affects all users with:
+ - Multi-file OpenAPI specifications with shared parameters
+ - Code generators that rely on parameter references for optimization
+ - Tools that analyze parameter reusability
+ - Projects using external parameter libraries
+- **Functional Impact**:
+ - Code generators may generate duplicate parameter code instead of reusable references
+ - Loss of semantic information about parameter reusability
+ - Bloated generated output/documentation
+- **Workaround Available**: No - the behavior cannot be configured differently
+ - Cannot use `resolve=false` as that doesn't merge external files
+ - Cannot use `resolveFully=true` as that would inline everything (by design)
+ - Only option is to avoid external parameter references entirely
+
+## 4. Reproduction
+
+- **Reproducible**: Yes
+- **Reproduction Complexity**: Low - clear minimal example provided
+
+### Steps to Reproduce:
+
+1. **Create test.yml:**
+```yaml
+openapi: 3.0.3
+info:
+ title: Test
+ description: Test
+ version: 0.0.1
+
+paths:
+ /test:
+ parameters:
+ - $ref: './test-components.yml#/components/parameters/TestIdQueryParameter'
+ get:
+ summary: Get all tests
+ description: List tests
+ responses:
+ '200':
+ description: OK
+```
+
+2. **Create test-components.yml:**
+```yaml
+openapi: 3.0.3
+info:
+ title: Portfolio Management API
+ description: API to manage games portfolio
+ version: 0.0.1
+
+components:
+ schemas:
+ TestId:
+ description: Test id
+ type: string
+ example: 1234
+ parameters:
+ TestIdQueryParameter:
+ name: testId
+ in: query
+ description: Test id
+ required: false
+ schema:
+ $ref: './test-components.yml#/components/schemas/TestId'
+```
+
+3. **Parse with resolve option:**
+```java
+ParseOptions options = new ParseOptions();
+options.setResolve(true);
+OpenAPI specs = new OpenAPIV3Parser().read("test.yml", null, options);
+```
+
+4. **Observe incorrect behavior:**
+ - Expected: `parameters[0].$ref = "#/components/parameters/TestIdQueryParameter"`
+ - Actual: `parameters[0].$ref = null` (parameter is inlined)
+
+- **Test Case Available**: Yes - complete reproduction code provided in issue
+
+## 5. Related Issues and Context
+
+### Dependencies
+- **Related to Issue #2211**: Nearly identical issue reported by nicolaideffremo
+ - Same root cause (parameter inlining with resolve=true)
+ - Issue #2211 was initially closed but is now recognized as valid
+ - Both issues confirm the same incorrect behavior
+- **PR #2254**: Active pull request to fix both #2216 and #2211
+ - Created by nicolaideffremo on 2025-12-01
+ - Status: Open, waiting for review
+ - PR has been updated to resolve merge conflicts (2026-01-13)
+ - Contains tests and fixes for the issue
+
+### Similar Patterns
+- This issue specifically affects **parameters**
+- Other reference types (schemas, responses) appear to work correctly
+- Suggests inconsistent implementation across different OpenAPI element types
+
+### Version Information
+- **Affected version**: 2.1.31 (and likely earlier versions)
+- **Historical context**: "Seems to never have worked as expected" per issue reporter
+- **Architecture issue**: Appears to be long-standing implementation bug, not a regression
+
+### Community Response
+- **Maintainer acknowledgment**: ewaostrowska confirmed the issue on 2025-08-12:
+ - "Indeed it seems that the current behavior is not correct for parameters with external refs"
+ - "Usage-site becomes fully inlined — which matches what resolveFully is supposed to do, not resolve"
+ - "This is as well not aligned with the behavior for other types (eg. responses)"
+ - Internal tracking issue created
+- **Active community interest**: Multiple follow-ups requesting status updates
+- **Solution in progress**: PR #2254 available but needs review and merge
+
+## 6. Solution Approach
+
+### Proposed Solution
+
+The fix requires aligning parameter reference resolution with the behavior of other reference types (schemas, responses). Based on the maintainer's analysis and PR #2254:
+
+**Implementation approach:**
+1. Identify the parameter reference resolution code path in the parser
+2. Modify logic to distinguish between `resolve=true` and `resolveFully=true`:
+ - For `resolve=true`: Copy external component to local components, replace external $ref with internal $ref
+ - For `resolveFully=true`: Copy and inline (current behavior for resolve, which is incorrect)
+3. Ensure parameter resolution follows the same pattern as schema/response resolution
+4. Update tests to verify correct behavior for both options
+
+**Key changes needed:**
+- Parameter reference resolver should create internal references instead of inlining
+- External content should still be copied to `#/components/parameters`
+- Only `resolveFully=true` should trigger full inlining
+
+### Implementation Complexity
+- **Effort Estimate**: Low-Medium
+ - PR #2254 already implements a solution
+ - Code changes appear localized to reference resolution logic
+ - Test cases already created in PR
+ - Main effort is code review and validation
+
+- **Risks**:
+ - **Breaking change for some users**: Users who inadvertently rely on the incorrect inlining behavior might see changes
+ - **Behavior alignment**: Need to ensure parameters behave consistently with other types
+ - **Edge cases**: Need to handle nested references, circular references, and complex parameter definitions
+ - **Backward compatibility**: This is technically a bug fix, but changes observable behavior
+
+### Testing Requirements
+
+- **Unit tests needed** (likely included in PR #2254):
+ - Parameter with external $ref using `resolve=true` → should keep internal $ref
+ - Parameter with external $ref using `resolveFully=true` → should inline
+ - Parameter with internal $ref using `resolve=true` → should remain unchanged
+ - Nested parameter references (parameter referencing schema that references another schema)
+ - Multiple parameters referencing same external definition
+
+- **Integration tests needed**:
+ - Multi-file OpenAPI specs with shared parameter libraries
+ - Mixed references (parameters, schemas, responses) to verify consistent behavior
+ - Code generator integration to verify parameter references are properly used
+
+- **Regression tests needed**:
+ - Verify other reference types (schemas, responses) still work correctly
+ - Verify `resolveFully=true` still fully inlines as expected
+ - Verify `resolve=false` doesn't change behavior
+
+- **Backward compatibility**:
+ - Document behavior change in release notes
+ - Consider if migration guide is needed for users depending on old behavior
+ - Evaluate if a configuration flag is needed (likely not - fixing a bug)
+
+## 7. Additional Notes
+
+### Recommendations
+
+1. **Merge PR #2254**:
+ - PR appears to address the issue directly
+ - Has been updated to resolve conflicts
+ - Community is waiting for this fix
+ - Review and merge should be prioritized
+
+2. **Documentation clarity**:
+ - Update ParseOptions documentation to clearly distinguish `resolve` vs `resolveFully`
+ - Add examples showing expected behavior for each option
+ - Document that parameters now behave consistently with schemas/responses
+
+3. **Release planning**:
+ - Include in release notes as a bug fix with behavior change
+ - Highlight that this fixes incorrect inlining of parameters
+ - Note that code generators may see different (correct) output
+
+4. **Testing coverage**:
+ - Ensure PR #2254 includes comprehensive tests
+ - Verify tests cover both path-level and operation-level parameters
+ - Test with various code generators to ensure compatibility
+
+### Questions to Address
+
+1. ✓ **Is the behavior confirmed as incorrect?**
+ - Yes - maintainer confirmed this is a bug
+
+2. ✓ **Is there a fix available?**
+ - Yes - PR #2254 addresses the issue
+
+3. **Should this be considered a breaking change?**
+ - Technically yes (changes behavior), but it's a bug fix
+ - Users relying on the incorrect behavior will need to update
+
+4. **Are there other reference types with similar issues?**
+ - Appears to be specific to parameters
+ - Schemas and responses reportedly work correctly
+
+### Priority Assessment
+
+- **Priority**: High
+- **Justification**:
+ - Confirmed bug affecting core functionality
+ - Breaks code generation workflows
+ - No workaround available
+ - Fix already available in PR #2254
+ - Multiple users impacted and requesting fix
+ - Long-standing issue that should be addressed
+
+- **Effort vs Benefit**: High benefit, low effort
+ - PR already exists and is updated
+ - Primarily needs review and merge
+ - Fixes architectural inconsistency
+ - Aligns behavior with documentation and user expectations
+
+### Community Engagement
+
+- Issue reporter provided clear reproduction case
+- Multiple users confirmed experiencing the same issue
+- Maintainer acknowledged and created internal tracking
+- Community contributor (nicolaideffremo) created PR with fix
+- Active follow-ups requesting merge of fix
+- Good example of community-driven bug reporting and resolution
+
+### Impact on Ecosystem
+
+**Code Generators:**
+- Currently generate incorrect code for parameters (duplicated instead of referenced)
+- Fix will enable proper parameter reuse in generated code
+- May require regeneration of client/server code
+
+**API Documentation Tools:**
+- Should correctly show parameter reusability after fix
+- Documentation will be more accurate and concise
+
+**OpenAPI Best Practices:**
+- Enables proper parameter reuse patterns
+- Supports DRY (Don't Repeat Yourself) principles
+- Encourages modular OpenAPI design with shared components
+
+---
+
+## Summary
+
+Issue #2216 reports a confirmed bug where the `resolve=true` option incorrectly inlines parameter references instead of maintaining internal `$ref` references to components. This behavior is inconsistent with how schemas and responses are handled and contradicts the documented purpose of the resolve option. A fix is available in PR #2254 and is awaiting review and merge. This is a high-priority bug that affects code generation workflows and has no workaround. The fix should be merged and released with appropriate documentation of the behavior change.
diff --git a/swagger-parser/issues/parser-2271.md b/swagger-parser/issues/parser-2271.md
new file mode 100644
index 0000000000..5e6122415a
--- /dev/null
+++ b/swagger-parser/issues/parser-2271.md
@@ -0,0 +1,265 @@
+# Issue Analysis: #2271
+
+## Overview
+Analysis of GitHub issue for the swagger-parser project.
+
+## 1. Issue Summary
+- **Issue Number**: 2271
+- **Title**: [Bug]: Validation behavior change between openapi-generator 7.13.0 and 7.14.0 against an OpenAPI 3.1 schema with external references
+- **Type**: Bug / Regression
+- **Status**: Open
+- **URL**: https://github.com/swagger-api/swagger-parser/issues/2271
+- **Created**: 2026-02-12
+- **Author**: thatsdone
+
+## 2. Problem Description
+A validation regression was introduced between swagger-parser versions 2.1.22 and 2.1.28 that affects OpenAPI 3.1 specifications using external `$ref` references to the OpenAPI schema itself. The issue specifically impacts users working with ISO SOVD (ISO 17978) specifications, which reference the upstream OpenAPI schema definition from the OAI GitHub repository.
+
+When an OpenAPI 3.1 spec contains a schema that references the complete OpenAPI schema definition file (e.g., `https://raw.githubusercontent.com/OAI/OpenAPI-Specification/refs/tags/3.1.1/schemas/v3.1/schema.yaml`), the parser fails to resolve internal `$defs` references within that external schema. This causes validation to fail with errors like "Could not find /$defs/info in contents of #/$defs/info".
+
+Interestingly, the issue does NOT occur when referencing a specific `$defs` fragment directly (e.g., `schema.yaml#/$defs/schema`), suggesting the problem is related to how the parser handles `$defs` within externally referenced complete schema documents.
+
+## 3. Technical Analysis
+
+### Affected Components
+- **Module**: `swagger-parser-v3`
+- **Primary Package**: `io.swagger.v3.parser.reference`
+- **Key Classes**:
+ - `ReferenceVisitor` (specifically the `resolveSchemaRef` method at line 253)
+ - `OpenAPI31Traverser` (methods: `traverseSchema`, `traverseSchemaMap`)
+ - `OpenAPIDereferencer31`
+- **Affected Functionality**: External reference resolution for OpenAPI 3.1 specifications
+- **Configuration**: Default parsing/validation configuration
+
+### Root Cause
+Based on the stack trace and error messages, the root cause appears to be in the `$defs` resolution logic when processing externally referenced schemas:
+
+1. When the parser loads the external OpenAPI schema file (which itself contains `$defs`), it correctly retrieves the content
+2. The external schema contains many `$defs` entries (e.g., `info`, `server`, `paths`, `path-item`, `components`, etc.)
+3. When the parser traverses this external schema, it encounters internal `$ref` pointers within the external document (e.g., `#/$defs/info`)
+4. **The bug**: The parser fails to resolve these internal references within the external document, treating the fragment `#/$defs/info` as if it should be found relative to the original document or with incorrect context
+5. Error message pattern: "Could not find /$defs/info in contents of #/$defs/info" suggests the parser is looking for the path `/$defs/info` but searching in the wrong context
+
+**Key observation from reproduction case:**
+- **Fails**: `$ref: "https://raw.githubusercontent.com/.../schema.yaml"` (references entire schema with internal `$defs`)
+- **Works**: `$ref: "https://raw.githubusercontent.com/.../schema.yaml#/$defs/schema"` (references specific fragment)
+
+This indicates the parser can properly handle fragment references but cannot properly resolve `$defs` that exist within an externally referenced document when the entire document is referenced.
+
+### Impact Assessment
+- **Severity**: High
+ - Breaks validation for legitimate OpenAPI 3.1 specifications
+ - Affects compliance with ISO standards (SOVD ISO 17978)
+ - Regression from previously working functionality
+- **User Impact**:
+ - Users of ISO SOVD specifications cannot validate or generate code
+ - Any OpenAPI 3.1 spec referencing complete external schema documents with `$defs` is affected
+ - Impacts openapi-generator users from version 7.14.0 onwards
+- **Workaround Available**: Partial
+ - Can reference specific `$defs` fragments instead of entire schema document
+ - Requires modifying specs to point to fragments (e.g., `schema.yaml#/$defs/schema`)
+ - May not be feasible if the spec is standardized/externally controlled
+
+## 4. Reproduction
+
+- **Reproducible**: Yes
+- **Prerequisites**:
+ - OpenAPI 3.1 specification
+ - External `$ref` to a complete schema document containing `$defs`
+ - swagger-parser version 2.1.28 or later (or openapi-generator 7.14.0+)
+
+- **Minimal Test Case**:
+```yaml
+openapi: 3.1.0
+info:
+ title: Test case for $defs resolution bug
+ version: 1.0.0
+paths:
+ /hello:
+ get:
+ operationId: hello
+ responses:
+ "200":
+ description: A successful response
+ $ref: '#/components/responses/Data'
+components:
+ responses:
+ Data:
+ description: Response with schema reference
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ schema:
+ $ref: "#/components/schemas/OpenApiSchema"
+ schemas:
+ OpenApiSchema:
+ # FAILS with swagger-parser 2.1.28+
+ $ref: "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/refs/tags/3.1.1/schemas/v3.1/schema.yaml"
+ # WORKS with all versions
+ #$ref: "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/refs/tags/3.1.1/schemas/v3.1/schema.yaml#/$defs/schema"
+```
+
+- **Steps to Reproduce**:
+ 1. Save the above YAML as `test.yaml`
+ 2. Run validation with openapi-generator-cli 7.13.0 (swagger-parser 2.1.22): `java -jar openapi-generator-cli-7.13.0.jar validate -i test.yaml`
+ 3. Result: ✅ "No validation issues detected."
+ 4. Run validation with openapi-generator-cli 7.14.0 (swagger-parser 2.1.28): `java -jar openapi-generator-cli-7.14.0.jar validate -i test.yaml`
+ 5. Result: ❌ Validation fails with 8 errors about missing `$defs`
+
+- **Test Case Available**: Yes - complete reproducible example provided
+
+## 5. Related Issues and Context
+
+### Dependencies
+- Related to: https://github.com/OpenAPITools/openapi-generator/issues/22948 (original report in openapi-generator repo)
+- This appears to be a swagger-parser specific regression that manifests in openapi-generator
+- May be related to changes in OpenAPI 3.1 `$defs` handling between versions 2.1.22 and 2.1.28
+
+### Version Information
+- **Working version**: swagger-parser 2.1.22 (openapi-generator 7.13.0)
+- **Broken versions**:
+ - swagger-parser 2.1.28 (openapi-generator 7.14.0)
+ - swagger-parser 2.1.37 (openapi-generator latest)
+- **Regression introduced**: Between versions 2.1.22 and 2.1.28
+- **OpenAPI Version**: OpenAPI 3.1.0
+
+### Likely Commit Range
+The regression was introduced between swagger-parser 2.1.22 and 2.1.28. Key areas to investigate:
+- Changes to `ReferenceVisitor.resolveSchemaRef()`
+- Changes to `$defs` handling in OpenAPI 3.1 dereferencer
+- Changes to external reference context management
+
+## 6. Solution Approach
+
+### Proposed Solution
+
+The core issue is that when an external schema document is loaded, the parser loses track of the proper context for resolving internal `$defs` references within that external document. The fix should ensure:
+
+1. **Maintain proper reference context**: When loading an external schema document, preserve its base URI/context
+2. **Resolve internal references correctly**: When encountering `#/$defs/...` references within an externally loaded document, resolve them relative to that external document, not the parent document
+3. **Handle complete vs fragment references**: Ensure both complete document references and fragment references work correctly
+
+**Implementation approach:**
+
+1. **Investigate `ReferenceVisitor.resolveSchemaRef()` around line 253**:
+ - Check how the reference context is maintained for external documents
+ - Verify that `$defs` within external documents have proper resolution scope
+
+2. **Check external document caching and context**:
+ - When an external document is loaded and cached, ensure its internal structure (including `$defs`) is properly indexed
+ - Ensure that references within the external document are resolved in the external document's context, not the original document's context
+
+3. **Review changes between 2.1.22 and 2.1.28**:
+ - Identify commits that modified `$defs` handling
+ - Look for changes to reference resolution logic
+ - Check for changes to OpenAPI 3.1 specific processing
+
+4. **Fix approach** (likely one of):
+ - **Option A**: Maintain a reference context stack that tracks the current document being processed
+ - **Option B**: When resolving `#/$defs/...` references, check if we're within an externally loaded document and adjust resolution accordingly
+ - **Option C**: Pre-process external documents to resolve their internal `$defs` before they're traversed
+
+### Implementation Complexity
+- **Effort Estimate**: Medium
+ - Requires understanding the reference resolution architecture
+ - Need to trace through the dereferencing logic
+ - Must maintain backward compatibility
+ - Complex test cases needed
+
+- **Risks**:
+ - **Breaking change potential**: Reference resolution is core functionality
+ - **Performance impact**: Additional context tracking may add overhead
+ - **Edge cases**: Complex nested external references need careful handling
+ - **OpenAPI 3.0 compatibility**: Must not break OpenAPI 3.0 parsing (uses `definitions` not `$defs`)
+
+### Testing Requirements
+
+- **Unit tests needed**:
+ - External `$ref` to complete schema document with internal `$defs`
+ - External `$ref` to specific `$defs` fragment (already works - regression test)
+ - Nested external references
+ - Multiple levels of external documents with `$defs`
+ - Mixed OpenAPI 3.0/3.1 handling
+
+- **Integration tests needed**:
+ - Real-world ISO SOVD specification validation
+ - OpenAPI 3.1 schema self-reference (as in the bug report)
+ - Complex multi-file projects with external schema references
+
+- **Regression tests needed**:
+ - Ensure fix works with swagger-parser 2.1.22 test cases
+ - Verify no regression in OpenAPI 3.0 handling
+ - Test all reference resolution scenarios from existing test suite
+
+- **Backward compatibility**:
+ - Ensure fix doesn't break any existing valid use cases
+ - Verify that workaround cases (fragment references) still work
+ - Test with both OpenAPI 3.0 and 3.1 specifications
+
+## 7. Additional Notes
+
+### Critical Observations
+
+1. **This is a regression, not a new feature request**: Previously working specifications now fail, which is a high-priority bug
+2. **Standards compliance issue**: Affects users trying to comply with ISO SOVD standard
+3. **Clear version boundaries**: Easy to bisect between 2.1.22 (works) and 2.1.28 (fails)
+4. **Narrow scope**: Issue is specific to `$defs` in external complete schema documents; fragment references work fine
+
+### Recommendations
+
+1. **Priority**: High - This is a regression affecting standards compliance
+2. **Bisect commits**: Compare changes between 2.1.22 and 2.1.28, specifically:
+ - Reference resolution logic
+ - `$defs` handling in OpenAPI 3.1
+ - Context management for external documents
+3. **Quick win check**: Review if any recent "fix" inadvertently broke this scenario
+4. **Engage with reporter**: User has good technical understanding and can help test fixes
+
+### Questions to Address
+
+1. What specific changes were made to `$defs` handling between 2.1.22 and 2.1.28?
+2. Is there existing test coverage for external schemas with internal `$defs`?
+3. Should the parser pre-process external documents to resolve internal references?
+4. How should circular references in external `$defs` be handled?
+5. Is the ISO SOVD use case (referencing the OpenAPI schema itself) a common pattern?
+
+### Debugging Strategy
+
+1. **Code archaeology**:
+ ```bash
+ git log --oneline --all --grep="defs" v2.1.22..v2.1.28
+ git log --oneline --all --grep="reference" v2.1.22..v2.1.28
+ git diff v2.1.22..v2.1.28 -- "*ReferenceVisitor*"
+ git diff v2.1.22..v2.1.28 -- "*Dereference*"
+ ```
+
+2. **Add debug logging**:
+ - Log when external documents are loaded
+ - Log the resolution context for each `$ref`
+ - Log the base URI used for resolving internal references
+
+3. **Reproduce locally**:
+ - Create minimal test case (provided in issue)
+ - Run with 2.1.22 and 2.1.28 in debugger
+ - Step through reference resolution logic
+ - Identify where context is lost
+
+### Priority Assessment
+- **Priority**: High
+- **Justification**:
+ - Regression from working functionality
+ - Blocks users of ISO standards
+ - Affects all versions since 2.1.28
+ - Clear reproduction case available
+- **Urgency**: Medium-High - Users cannot upgrade openapi-generator without workarounds
+- **Impact**: Significant for affected users, but likely limited to specific use case (external schema references)
+
+### Next Steps
+1. Review git history between v2.1.22 and v2.1.28 for reference resolution changes
+2. Create test case in swagger-parser test suite
+3. Debug with test case to identify exact failure point
+4. Implement fix with proper context management
+5. Verify fix doesn't introduce new regressions
+6. Add comprehensive test coverage for external `$defs` scenarios
diff --git a/swagger-parser/issues/parser-2275.md b/swagger-parser/issues/parser-2275.md
new file mode 100644
index 0000000000..7b090edc7a
--- /dev/null
+++ b/swagger-parser/issues/parser-2275.md
@@ -0,0 +1,136 @@
+# Issue Analysis: #2275
+
+## Overview
+Analysis of GitHub issue for the swagger-parser project.
+
+## 1. Issue Summary
+- **Issue Number**: 2275
+- **Title**: [Feature]: Cache the result of deserialization when loading ref
+- **Type**: Feature Request / Performance Enhancement
+- **Status**: Open
+- **URL**: https://github.com/swagger-api/swagger-parser/issues/2275
+- **Created**: 2026-02-20
+- **Author**: xmourgues
+
+## 2. Problem Description
+The ResolverCache currently only caches the raw string content when loading external $ref references, but still deserializes the entire tree on each reference. For projects with many references to the same file (especially large files), this causes significant performance degradation. The user has a project with 260+ OpenAPI spec files and a large "dictionary" YAML file with 1100+ fields that is referenced 3300+ times across specs. Each reference triggers deserialization of the entire file.
+
+## 3. Technical Analysis
+
+### Affected Components
+- **Module**: `swagger-parser-v3`
+- **Primary Class**: `io.swagger.v3.parser.ResolverCache`
+- **Specific Method/Line**: Line 170 in ResolverCache.java where deserialization occurs repeatedly
+- **Process**: External reference resolution and caching mechanism
+
+### Root Cause
+The current caching strategy only stores the raw file content (String) in the cache, but the deserialization from String to JsonNode happens on every access. This means:
+1. File read is cached ✓ (efficient)
+2. Deserialization to JsonNode is NOT cached ✗ (inefficient)
+
+For large files referenced many times, the deserialization overhead becomes the bottleneck.
+
+### Impact Assessment
+- **Severity**: Medium-High (significant performance impact for large projects)
+- **User Impact**: Users with large OpenAPI projects with many cross-file references experience slow build times
+- **Performance Impact**: User reports build time reduction from 4m49s to 58s (>80% improvement) with prototype fix
+- **Workaround Available**: No - users must accept slow build times or modify source code
+
+## 4. Reproduction
+- **Reproducible**: Yes
+- **Prerequisites**:
+ - Large OpenAPI project with multiple spec files
+ - Large shared schema/dictionary file
+ - Many $ref references to the same file
+- **Test Case Available**: User has working prototype demonstrating improvement
+- **Complexity**: Requires test setup with multiple large files and many references
+
+## 5. Related Issues and Context
+
+### Dependencies
+- This is a performance optimization, not a bug fix
+- May relate to other caching/resolution performance issues
+- No blocking dependencies identified
+
+### Version Information
+- **Affected versions**: All versions (appears to be original design)
+- **Reported on**: Not version-specific - architectural issue
+
+## 6. Solution Approach
+
+### Proposed Solution
+The user suggests caching the deserialized JsonNode tree in addition to (or instead of) the raw string:
+
+**Current flow:**
+```
+$ref encountered → Check cache → Get String from cache → Deserialize to JsonNode → Use
+```
+
+**Proposed flow:**
+```
+$ref encountered → Check cache → Get JsonNode from cache → Use
+```
+
+**Implementation approach:**
+1. Modify ResolverCache to store JsonNode objects instead of/alongside Strings
+2. Ensure thread safety if parser is used concurrently
+3. Consider memory implications - JsonNode trees use more memory than Strings
+4. Add configuration option to enable/disable JsonNode caching (backward compatibility)
+
+### Implementation Complexity
+- **Effort Estimate**: Low-Medium
+ - Code change is relatively localized to ResolverCache
+ - Need to ensure thread safety
+ - Need to consider memory management
+ - Need to handle cache invalidation correctly
+
+- **Risks**:
+ - **Memory consumption**: JsonNode trees consume more memory than raw strings
+ - **Thread safety**: Need to ensure cache is thread-safe for concurrent parsing
+ - **Cache invalidation**: Need proper cache clearing mechanisms
+ - **Backward compatibility**: Existing users might see different memory usage patterns
+
+### Testing Requirements
+- **Unit tests needed**:
+ - Cache hit/miss scenarios
+ - Multiple references to same file
+ - Large file deserialization
+ - Thread safety tests
+
+- **Performance tests needed**:
+ - Benchmark with many references to same file
+ - Memory usage profiling
+ - Concurrent parsing scenarios
+
+- **Integration tests needed**:
+ - End-to-end parsing with complex reference chains
+ - Large project simulation (multiple files, many refs)
+
+- **Backward compatibility**:
+ - Ensure existing functionality is not broken
+ - Consider configuration flag to opt-in/opt-out
+
+## 7. Additional Notes
+
+### Recommendations
+1. **Accept the feature request** - The performance improvement is significant and well-documented
+2. **Consider a configurable approach** - Allow users to choose between memory efficiency (string caching) and speed (JsonNode caching)
+3. **Measure memory impact** - Benchmark memory usage increase to document trade-offs
+4. **User willing to contribute** - The issue author offered to contribute a PR, which should be encouraged
+
+### Questions to Address
+1. Should JsonNode caching be opt-in or opt-out?
+2. What should be the default cache size limits?
+3. Should there be memory-based eviction policies?
+4. Are there other cache optimization opportunities in the same area?
+
+### Priority Assessment
+- **Priority**: Medium-High
+- **Justification**: Significant performance improvement for a common use case, with minimal risk if implemented correctly
+- **Effort vs Benefit**: High benefit relative to implementation effort
+
+### Community Engagement
+- User has already implemented and tested a prototype
+- User is willing to contribute PR
+- Clear use case with measurable improvements
+- Should engage with user to review their implementation approach