Enable writeOnly and test readOnly and deprecated

[tstirrat15]

Fixes #145
Depends on swaggest/jsonschema-go#125

Description

See #145. writeOnly wasn't being properly reflected in openAPI schemas generated by this library because of issues in jsonschema-go.

TODO

• Merge Add deprecated and writeOnly as part of schema jsonschema-go#125 and update this PR to point at that ref

Changes

• Use new code in jsonschema-go
• Change references to deprecated to use new field on Schema object rather than reading ExtraProperties
• Add test that ensures that writeOnly, readOnly, and deprecated are properly reflected

Testing

Review. See that tests pass.

[llamapreview]

Auto Pull Request Review from LlamaPReview

1. Overview

1.1 Core Changes

• Primary purpose and scope: This PR aims to fix the handling of writeOnly and deprecated properties in OpenAPI schema generation. It aligns the behavior with updates in the jsonschema-go library and resolves issue #145 by ensuring these properties are correctly reflected from struct tags.
• Key components modified:
  • openapi3/jsonschema.go: Updated logic for converting between openapi3.Schema and jsonschema.Schema, now using direct field access for writeOnly and deprecated instead of ExtraProperties.
  • openapi31/jsonschema.go: Simplified the isDeprecated helper function to use the direct Deprecated field.
  • openapi3/reflect_test.go: Added a new test case TestReadOnlyWriteOnlyDeprecated to verify the correct reflection of readOnly, writeOnly, and deprecated tags.
  • .gitignore: Added go.work and go.work.sum.
• Cross-component impacts: This PR has a critical dependency on an unmerged pull request in the swaggest/jsonschema-go repository (specifically, swaggest/jsonschema-go#125). The changes rely on writeOnly and deprecated being first-class fields in jsonschema.Schema.
• Business value alignment: Improves compliance with JSON Schema and OpenAPI specifications. Fixes a bug where writeOnly was not correctly reflected, enhancing the accuracy of generated API schemas. The move to strongly-typed fields improves code maintainability and reduces the risk of errors compared to using ExtraProperties.

1.2 Technical Architecture

• System design modifications: The primary architectural change is in how writeOnly and deprecated schema properties are accessed and propagated. Previously, these were often handled via the ExtraProperties map. This PR transitions to using dedicated, strongly-typed fields (e.g., js.WriteOnly, js.Deprecated) provided by the updated jsonschema-go library.
• Component interaction changes: The interaction between openapi-go and jsonschema-go regarding these properties is now more direct and type-safe.
• Integration points impact: Relies on the updated interface of jsonschema.Schema from the jsonschema-go library.
• Dependency changes and implications: Requires swaggest/jsonschema-go#125 to be merged and this PR's go.mod to be updated to point to a commit/version of swaggest/jsonschema-go that includes these changes. The addition of go.work and go.work.sum to .gitignore suggests local Go workspace usage, which is generally fine but should align with repository conventions.

2. Critical Findings

2.1 Must Fix (P0🔴)

Issue: Unmerged External Dependency

• Analysis Confidence: High
• Impact: The PR is currently dependent on swaggest/jsonschema-go#125, which is not yet merged. Attempting to merge this PR as-is will likely lead to build failures or runtime errors because the necessary fields (WriteOnly, Deprecated) on jsonschema.Schema will not exist in the version of jsonschema-go fetched by default.
• Resolution:
  1. Ensure swaggest/jsonschema-go#125 is merged into its base branch.
  2. Update the go.mod file in this PR to reference the new version or specific commit of swaggest/jsonschema-go that includes the merged changes.
  3. Remove any temporary replace directives in go.mod that might have been used for local development against the unmerged dependency.

Issue: Potential Breaking Change for Consumers Accessing ExtraProperties

• Analysis Confidence: High
• Impact: If any consumers of this library were indirectly relying on writeOnly or deprecated flags being present in the ExtraProperties map of jsonschema.Schema objects (which openapi-go uses internally), this change will break their code as these properties will now be exclusively in dedicated fields.
• Resolution: Clearly document this change in the release notes for the version that includes this PR. Advise users that writeOnly and deprecated are now handled via direct fields on openapi3.Schema (which are correctly populated from jsonschema.Schema's direct fields) and are no longer in ExtraProperties at the jsonschema-go level for these specific keywords.

2.2 Should Fix (P1🟡)

Issue: Missing Validation for Conflicting Schema Annotations

• Analysis Confidence: High
• Impact: The OpenAPI specification implies a property should not be both readOnly and writeOnly. While this PR correctly reflects these individual properties, it does not add validation or warnings if a struct field is tagged as both (e.g., readOnly:"true" writeOnly:"true"). This could lead to semantically confusing or incorrect OpenAPI schemas being generated.
• Suggested Solution: Implement logic, likely during schema reflection, to detect if a field is marked as both readOnly and writeOnly. If such a conflict is found, the library could:
  1. Log a warning.
  2. Prioritize one over the other (e.g., readOnly takes precedence).
  3. Make this behavior configurable, potentially erroring out.
     Also, add a test case to verify the handling of such conflicting tags.

Issue: Incomplete Documentation for Struct Tag Usage and Changes

• Analysis Confidence: Medium
• Impact: Developers using this library might not be fully aware of the correct struct tags for deprecated, readOnly, and writeOnly, or how their internal handling has changed (especially the move from ExtraProperties for deprecated and writeOnly). This can lead to incorrect usage or confusion.
• Suggested Solution: Update the library's documentation (e.g., README, GoDoc comments for relevant types/functions) to:
  1. Clearly list all supported struct tags for schema generation, including deprecated, readOnly, and writeOnly, with concise examples.
  2. Briefly mention the internal change that deprecated and writeOnly are now sourced from direct fields in the underlying jsonschema-go dependency, improving accuracy.

2.3 Consider (P2🟢)

Area: Test Coverage Expansion for Schema Properties

• Analysis Confidence: Medium
• Improvement Opportunity: The new test TestReadOnlyWriteOnlyDeprecated is good for positive cases. To further improve robustness, consider adding negative test cases:
  • A test to ensure that fields without readOnly, writeOnly, or deprecated tags do not have these properties set in the generated schema (i.e., no false positives).

Area: .gitignore additions of Go Workspace files

• Analysis Confidence: Low
• Improvement Opportunity: The addition of go.work and go.work.sum to .gitignore is generally acceptable as these are often user-specific or for local development in multi-module setups. Confirm this aligns with the repository's contribution guidelines or general policy on Go workspace files. If the repository is not typically managed as part of a Go workspace, these might be unnecessary.

2.4 Summary of Action Items

1. P0 (Blocker): Resolve the external dependency on swaggest/jsonschema-go#125 by ensuring it's merged and then updating this PR's go.mod accordingly. (Timeline: Before Merge)
2. P0: Document the breaking change related to ExtraProperties in release notes. (Timeline: Before Merge)
3. P1: Implement validation/handling for conflicting readOnly and writeOnly tags. (Timeline: Before Merge or High Priority Post-Merge)
4. P1: Update documentation regarding struct tag usage for `deprecated

---

💡 LlamaPReview Community
Have feedback on this AI Code review tool? Join our GitHub Discussions to share your thoughts and help shape the future of LlamaPReview.

[codecov]

Codecov Report

Attention: Patch coverage is 83.33333% with 1 line in your changes missing coverage. Please review.

Project coverage is 40.11%. Comparing base (b19848c) to head (6edc33f).
Report is 11 commits behind head on master.

Files with missing lines	Patch %	Lines
openapi3/jsonschema.go	80.00%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #146      +/-   ##
==========================================
- Coverage   40.72%   40.11%   -0.62%     
==========================================
  Files          16       16              
  Lines        6607    10383    +3776     
==========================================
+ Hits         2691     4165    +1474     
- Misses       3440     5708    +2268     
- Partials      476      510      +34     

Flag	Coverage Δ
unittests	40.11% <83.33%> (-0.62%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.