` contains characters that are not URL-friendly",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err, "unmarshal should succeed")
+
+ rule := &rules.OperationIDValidInURLRule{}
+ config := &linter.RuleConfig{}
+
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+ require.Len(t, errs, 1, "should have one lint error")
+ assert.Equal(t, tt.expectedError, errs[0].Error(), "error message should match exactly")
+ })
+ }
+}
+
+func TestOperationIDValidInURLRule_RuleMetadata(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.OperationIDValidInURLRule{}
+
+ assert.Equal(t, "semantic-operation-id-valid-in-url", rule.ID())
+ assert.Equal(t, rules.CategorySemantic, rule.Category())
+ assert.NotEmpty(t, rule.Description())
+ assert.NotEmpty(t, rule.Link())
+ assert.Equal(t, validation.SeverityError, rule.DefaultSeverity())
+ assert.Nil(t, rule.Versions())
+}
diff --git a/openapi/linter/rules/operation_singular_tag.go b/openapi/linter/rules/operation_singular_tag.go
new file mode 100644
index 00000000..457454b7
--- /dev/null
+++ b/openapi/linter/rules/operation_singular_tag.go
@@ -0,0 +1,78 @@
+package rules
+
+import (
+ "context"
+ "fmt"
+ "strings"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/validation"
+)
+
+const RuleStyleOperationSingularTag = "style-operation-singular-tag"
+
+type OperationSingularTagRule struct{}
+
+func (r *OperationSingularTagRule) ID() string { return RuleStyleOperationSingularTag }
+func (r *OperationSingularTagRule) Category() string { return CategoryStyle }
+func (r *OperationSingularTagRule) Description() string {
+ return "Operations should be associated with only a single tag to maintain clear organizational boundaries. Multiple tags can create ambiguity about where an operation belongs in the API structure and complicate documentation organization."
+}
+func (r *OperationSingularTagRule) Summary() string {
+ return "Operations should have no more than one tag."
+}
+func (r *OperationSingularTagRule) HowToFix() string {
+ return "Limit each operation to a single tag."
+}
+func (r *OperationSingularTagRule) Link() string {
+ return "https://github.com/speakeasy-api/openapi/blob/main/openapi/linter/README.md#style-operation-singular-tag"
+}
+func (r *OperationSingularTagRule) DefaultSeverity() validation.Severity {
+ return validation.SeverityWarning
+}
+func (r *OperationSingularTagRule) Versions() []string {
+ return nil // Applies to all OpenAPI versions
+}
+
+func (r *OperationSingularTagRule) Run(ctx context.Context, docInfo *linter.DocumentInfo[*openapi.OpenAPI], config *linter.RuleConfig) []error {
+ if docInfo == nil || docInfo.Document == nil || docInfo.Index == nil {
+ return nil
+ }
+
+ var errs []error
+
+ // Use index to iterate through all operations
+ for _, opNode := range docInfo.Index.Operations {
+ operation := opNode.Node
+
+ // Check if operation has more than one tag
+ opTags := operation.GetTags()
+ if len(opTags) <= 1 {
+ continue
+ }
+
+ // Get operation identifier (prefer operationId, fallback to method + path)
+ opIdentifier := operation.GetOperationID()
+ if opIdentifier == "" {
+ method, path := openapi.ExtractMethodAndPath(opNode.Location)
+ if method != "" {
+ opIdentifier = fmt.Sprintf("`%s` operation at path `%s`", strings.ToUpper(method), path)
+ }
+ } else {
+ opIdentifier = fmt.Sprintf("`%s` operation", opIdentifier)
+ }
+ if opIdentifier == "" {
+ continue
+ }
+
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleStyleOperationSingularTag,
+ fmt.Errorf("the %s contains more than one tag (%d is too many)", opIdentifier, len(opTags)),
+ operation.GetCore().Tags.ValueNode,
+ ))
+ }
+
+ return errs
+}
diff --git a/openapi/linter/rules/operation_singular_tag_test.go b/openapi/linter/rules/operation_singular_tag_test.go
new file mode 100644
index 00000000..9e720dd9
--- /dev/null
+++ b/openapi/linter/rules/operation_singular_tag_test.go
@@ -0,0 +1,213 @@
+package rules_test
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/openapi/linter/rules"
+ "github.com/speakeasy-api/openapi/references"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestOperationSingularTagRule_ValidCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "operation with single tag",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ tags:
+ - users
+ responses:
+ '200':
+ description: ok
+`,
+ },
+ {
+ name: "operation with no tags",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ },
+ {
+ name: "multiple operations each with single tag",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ tags:
+ - users
+ responses:
+ '200':
+ description: ok
+ /products:
+ get:
+ tags:
+ - products
+ responses:
+ '200':
+ description: ok
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OperationSingularTagRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+ assert.Empty(t, errs)
+ })
+ }
+}
+
+func TestOperationSingularTagRule_Violations(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ expectedError string
+ }{
+ {
+ name: "operation with two tags",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ tags:
+ - users
+ - admin
+ responses:
+ '200':
+ description: ok
+`,
+ expectedError: "[10:9] warning style-operation-singular-tag the `GET` operation at path `/users` contains more than one tag (2 is too many)",
+ },
+ {
+ name: "operation with three tags",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ tags:
+ - users
+ - admin
+ - public
+ responses:
+ '200':
+ description: ok
+`,
+ expectedError: "[10:9] warning style-operation-singular-tag the `GET` operation at path `/users` contains more than one tag (3 is too many)",
+ },
+ {
+ name: "operation with operationId and multiple tags",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ operationId: listUsers
+ tags:
+ - users
+ - admin
+ responses:
+ '200':
+ description: ok
+`,
+ expectedError: "[11:9] warning style-operation-singular-tag the `listUsers` operation contains more than one tag (2 is too many)",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OperationSingularTagRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ require.Len(t, errs, 1)
+ assert.Equal(t, tt.expectedError, errs[0].Error())
+ })
+ }
+}
+
+func TestOperationSingularTagRule_RuleMetadata(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.OperationSingularTagRule{}
+
+ assert.Equal(t, "style-operation-singular-tag", rule.ID())
+ assert.Equal(t, rules.CategoryStyle, rule.Category())
+ assert.NotEmpty(t, rule.Description())
+ assert.NotEmpty(t, rule.Link())
+ assert.Equal(t, validation.SeverityWarning, rule.DefaultSeverity())
+ assert.Nil(t, rule.Versions())
+}
diff --git a/openapi/linter/rules/operation_success_response.go b/openapi/linter/rules/operation_success_response.go
new file mode 100644
index 00000000..4a73ce74
--- /dev/null
+++ b/openapi/linter/rules/operation_success_response.go
@@ -0,0 +1,171 @@
+package rules
+
+import (
+ "context"
+ "fmt"
+ "strconv"
+ "strings"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/validation"
+ "gopkg.in/yaml.v3"
+)
+
+const RuleStyleOperationSuccessResponse = "style-operation-success-response"
+
+type OperationSuccessResponseRule struct{}
+
+func (r *OperationSuccessResponseRule) ID() string { return RuleStyleOperationSuccessResponse }
+
+func (r *OperationSuccessResponseRule) Category() string { return CategoryStyle }
+
+func (r *OperationSuccessResponseRule) Description() string {
+ return "Operations should define at least one 2xx or 3xx response code to indicate successful execution. Success responses are essential for API consumers to understand what data they'll receive when requests complete successfully."
+}
+
+func (r *OperationSuccessResponseRule) Summary() string {
+ return "Operations must define at least one 2xx or 3xx response."
+}
+
+func (r *OperationSuccessResponseRule) HowToFix() string {
+ return "Add at least one 2xx or 3xx response code definition per operation."
+}
+
+func (r *OperationSuccessResponseRule) Link() string {
+ return "https://github.com/speakeasy-api/openapi/blob/main/openapi/linter/README.md#style-operation-success-response"
+}
+
+func (r *OperationSuccessResponseRule) DefaultSeverity() validation.Severity {
+ return validation.SeverityWarning
+}
+
+func (r *OperationSuccessResponseRule) Versions() []string { return nil }
+
+func (r *OperationSuccessResponseRule) Run(ctx context.Context, docInfo *linter.DocumentInfo[*openapi.OpenAPI], config *linter.RuleConfig) []error {
+ if docInfo == nil || docInfo.Document == nil || docInfo.Index == nil {
+ return nil
+ }
+
+ doc := docInfo.Document
+ isOAS3 := strings.HasPrefix(doc.GetOpenAPI(), "3.")
+
+ var errs []error
+
+ // Use the pre-computed Operations index
+ for _, opNode := range docInfo.Index.Operations {
+ op := opNode.Node
+
+ responses := op.GetResponses()
+ responseSeen := false
+ responseInvalidType := false
+ invalidCodes := []int{}
+
+ if responses != nil {
+ for code := range responses.All() {
+ codeVal, err := strconv.Atoi(code)
+ if err == nil && codeVal >= 200 && codeVal < 400 {
+ responseSeen = true
+ }
+ }
+
+ if isOAS3 {
+ responseInvalidType, invalidCodes = findIntegerResponseCodes(op)
+ if responseInvalidType {
+ responseSeen = true
+ }
+ }
+ }
+
+ if !responseSeen || responseInvalidType {
+ opName := op.GetOperationID()
+ if opName == "" {
+ opName = "undefined operation (no operationId)"
+ }
+
+ errNode := getOperationResponsesKeyNode(op, doc)
+
+ if !responseSeen {
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleStyleOperationSuccessResponse,
+ fmt.Errorf("operation `%s` must define at least a single `2xx` or `3xx` response", opName),
+ errNode,
+ ))
+ }
+
+ if responseInvalidType {
+ for _, code := range invalidCodes {
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleStyleOperationSuccessResponse,
+ fmt.Errorf("operation `%s` uses an `integer` instead of a `string` for response code `%d`", opName, code),
+ errNode,
+ ))
+ }
+ }
+ }
+ }
+
+ return errs
+}
+
+func getOperationResponsesKeyNode(op *openapi.Operation, doc *openapi.OpenAPI) *yaml.Node {
+ if op == nil {
+ if doc != nil {
+ return doc.GetRootNode()
+ }
+ return nil
+ }
+
+ core := op.GetCore()
+ if core != nil && core.Responses.Present && core.Responses.KeyNode != nil {
+ return core.Responses.KeyNode
+ }
+
+ if core != nil && core.GetRootNode() != nil {
+ return core.GetRootNode()
+ }
+
+ if doc != nil {
+ return doc.GetRootNode()
+ }
+
+ return nil
+}
+
+func findIntegerResponseCodes(op *openapi.Operation) (bool, []int) {
+ core := op.GetCore()
+ if core == nil || !core.Responses.Present || core.Responses.ValueNode == nil {
+ return false, nil
+ }
+
+ valueNode := core.Responses.ValueNode
+ if valueNode.Kind != yaml.MappingNode {
+ return false, nil
+ }
+
+ invalidCodes := []int{}
+ for i := 0; i < len(valueNode.Content); i += 2 {
+ keyNode := valueNode.Content[i]
+ if keyNode == nil || keyNode.Kind != yaml.ScalarNode {
+ continue
+ }
+
+ if keyNode.Tag != "!!int" {
+ continue
+ }
+
+ codeVal, err := strconv.Atoi(keyNode.Value)
+ if err != nil {
+ continue
+ }
+ invalidCodes = append(invalidCodes, codeVal)
+ }
+
+ if len(invalidCodes) == 0 {
+ return false, nil
+ }
+
+ return true, invalidCodes
+}
diff --git a/openapi/linter/rules/operation_success_response_test.go b/openapi/linter/rules/operation_success_response_test.go
new file mode 100644
index 00000000..81beddaf
--- /dev/null
+++ b/openapi/linter/rules/operation_success_response_test.go
@@ -0,0 +1,244 @@
+package rules_test
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/openapi/linter/rules"
+ "github.com/speakeasy-api/openapi/references"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestOperationSuccessResponseRule_ValidCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "operation with 2xx response",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ operationId: listUsers
+ responses:
+ '200':
+ description: ok
+`,
+ },
+ {
+ name: "operation with 3xx response",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ operationId: listUsers
+ responses:
+ '302':
+ description: redirect
+`,
+ },
+ {
+ name: "operation with mixed responses",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ operationId: listUsers
+ responses:
+ '204':
+ description: no content
+ '404':
+ description: missing
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+
+ ctx := t.Context()
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err, "unmarshal should succeed")
+
+ rule := &rules.OperationSuccessResponseRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+ assert.Empty(t, errs, "should have no lint errors")
+ })
+ }
+}
+
+func TestOperationSuccessResponseRule_Violations(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ expectedErrors []string
+ }{
+ {
+ name: "missing success response",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ operationId: listUsers
+ responses:
+ '404':
+ description: missing
+`,
+ expectedErrors: []string{
+ "[10:7] warning style-operation-success-response operation `listUsers` must define at least a single `2xx` or `3xx` response",
+ },
+ },
+ {
+ name: "missing responses",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ operationId: listUsers
+`,
+ expectedErrors: []string{
+ "[9:7] warning style-operation-success-response operation `listUsers` must define at least a single `2xx` or `3xx` response",
+ },
+ },
+ {
+ name: "missing success response without operationId",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '500':
+ description: error
+`,
+ expectedErrors: []string{
+ "[9:7] warning style-operation-success-response operation `undefined operation (no operationId)` must define at least a single `2xx` or `3xx` response",
+ },
+ },
+ {
+ name: "integer response code in OAS3",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ operationId: listUsers
+ responses:
+ 200:
+ description: ok
+`,
+ expectedErrors: []string{
+ "[10:7] warning style-operation-success-response operation `listUsers` uses an `integer` instead of a `string` for response code `200`",
+ },
+ },
+ {
+ name: "missing success response and integer response codes",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ operationId: listUsers
+ responses:
+ 404:
+ description: missing
+`,
+ expectedErrors: []string{
+ "[10:7] warning style-operation-success-response operation `listUsers` uses an `integer` instead of a `string` for response code `404`",
+ },
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+
+ ctx := t.Context()
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err, "unmarshal should succeed")
+
+ rule := &rules.OperationSuccessResponseRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+ require.NotEmpty(t, errs, "should have lint errors")
+
+ var errMsgs []string
+ for _, err := range errs {
+ errMsgs = append(errMsgs, err.Error())
+ }
+
+ assert.ElementsMatch(t, tt.expectedErrors, errMsgs)
+ })
+ }
+}
+
+func TestOperationSuccessResponseRule_RuleMetadata(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.OperationSuccessResponseRule{}
+
+ assert.Equal(t, "style-operation-success-response", rule.ID())
+ assert.Equal(t, rules.CategoryStyle, rule.Category())
+ assert.NotEmpty(t, rule.Description())
+ assert.NotEmpty(t, rule.Link())
+ assert.Equal(t, validation.SeverityWarning, rule.DefaultSeverity())
+ assert.Nil(t, rule.Versions())
+}
diff --git a/openapi/linter/rules/operation_tag_defined.go b/openapi/linter/rules/operation_tag_defined.go
new file mode 100644
index 00000000..9862bef2
--- /dev/null
+++ b/openapi/linter/rules/operation_tag_defined.go
@@ -0,0 +1,87 @@
+package rules
+
+import (
+ "context"
+ "fmt"
+ "strings"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/validation"
+)
+
+const RuleStyleOperationTagDefined = "style-operation-tag-defined"
+
+type OperationTagDefinedRule struct{}
+
+func (r *OperationTagDefinedRule) ID() string { return RuleStyleOperationTagDefined }
+func (r *OperationTagDefinedRule) Category() string { return CategoryStyle }
+func (r *OperationTagDefinedRule) Description() string {
+ return "Operation tags should be declared in the global tags array at the specification root. Pre-defining tags ensures consistency, enables tag-level documentation, and helps maintain a well-organized API structure."
+}
+func (r *OperationTagDefinedRule) Summary() string {
+ return "Operation tags should be defined in the global tags list."
+}
+func (r *OperationTagDefinedRule) HowToFix() string {
+ return "Add each operation tag to the top-level tags array."
+}
+func (r *OperationTagDefinedRule) Link() string {
+ return "https://github.com/speakeasy-api/openapi/blob/main/openapi/linter/README.md#style-operation-tag-defined"
+}
+func (r *OperationTagDefinedRule) DefaultSeverity() validation.Severity {
+ return validation.SeverityWarning
+}
+func (r *OperationTagDefinedRule) Versions() []string {
+ return nil // Applies to all OpenAPI versions
+}
+
+func (r *OperationTagDefinedRule) Run(ctx context.Context, docInfo *linter.DocumentInfo[*openapi.OpenAPI], config *linter.RuleConfig) []error {
+ if docInfo == nil || docInfo.Document == nil || docInfo.Index == nil {
+ return nil
+ }
+
+ var errs []error
+
+ // Build map of global tags
+ globalTags := make(map[string]bool)
+ for _, tagNode := range docInfo.Index.Tags {
+ tag := tagNode.Node
+ if tag.Name != "" {
+ globalTags[tag.Name] = true
+ }
+ }
+
+ // Use index to iterate through all operations
+ for _, opNode := range docInfo.Index.Operations {
+ operation := opNode.Node
+
+ // Get operation identifier (prefer operationId, fallback to method + path)
+ opIdentifier := operation.GetOperationID()
+ if opIdentifier == "" {
+ method, path := openapi.ExtractMethodAndPath(opNode.Location)
+ if method != "" {
+ opIdentifier = fmt.Sprintf("`%s` %s", strings.ToUpper(method), path)
+ }
+ }
+ if opIdentifier == "" {
+ continue
+ }
+
+ // Check each tag in the operation
+ opTags := operation.GetTags()
+ for i, tagName := range opTags {
+ if tagName != "" && !globalTags[tagName] {
+ errs = append(errs, validation.NewSliceError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleStyleOperationTagDefined,
+ fmt.Errorf("tag `%s` for %s operation is not defined as a global tag", tagName, opIdentifier),
+ operation.GetCore(),
+ operation.GetCore().Tags,
+ i,
+ ))
+ }
+ }
+ }
+
+ return errs
+}
diff --git a/openapi/linter/rules/operation_tag_defined_test.go b/openapi/linter/rules/operation_tag_defined_test.go
new file mode 100644
index 00000000..afe71b1e
--- /dev/null
+++ b/openapi/linter/rules/operation_tag_defined_test.go
@@ -0,0 +1,254 @@
+package rules_test
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/openapi/linter/rules"
+ "github.com/speakeasy-api/openapi/references"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestOperationTagDefinedRule_ValidCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "all operation tags are defined globally",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+tags:
+ - name: users
+ - name: products
+paths:
+ /users:
+ get:
+ tags:
+ - users
+ responses:
+ '200':
+ description: ok
+ /products:
+ get:
+ tags:
+ - products
+ responses:
+ '200':
+ description: ok
+`,
+ },
+ {
+ name: "operations without tags",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ },
+ {
+ name: "no global tags but no operation tags",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ },
+ {
+ name: "multiple tags all defined",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+tags:
+ - name: users
+ - name: admin
+paths:
+ /users:
+ get:
+ tags:
+ - users
+ - admin
+ responses:
+ '200':
+ description: ok
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OperationTagDefinedRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+ assert.Empty(t, errs)
+ })
+ }
+}
+
+func TestOperationTagDefinedRule_Violations(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ expectedError string
+ }{
+ {
+ name: "operation tag not defined globally",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+tags:
+ - name: users
+paths:
+ /products:
+ get:
+ tags:
+ - products
+ responses:
+ '200':
+ description: ok
+`,
+ expectedError: "[12:11] warning style-operation-tag-defined tag `products` for `GET` /products operation is not defined as a global tag",
+ },
+ {
+ name: "one of multiple tags not defined",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+tags:
+ - name: users
+paths:
+ /users:
+ get:
+ tags:
+ - users
+ - admin
+ responses:
+ '200':
+ description: ok
+`,
+ expectedError: "[13:11] warning style-operation-tag-defined tag `admin` for `GET` /users operation is not defined as a global tag",
+ },
+ {
+ name: "no global tags but operation has tag",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ tags:
+ - users
+ responses:
+ '200':
+ description: ok
+`,
+ expectedError: "[10:11] warning style-operation-tag-defined tag `users` for `GET` /users operation is not defined as a global tag",
+ },
+ {
+ name: "operation with operationId uses id in error message",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ operationId: listUsers
+ tags:
+ - admin
+ responses:
+ '200':
+ description: ok
+`,
+ expectedError: "[11:11] warning style-operation-tag-defined tag `admin` for listUsers operation is not defined as a global tag",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OperationTagDefinedRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ require.Len(t, errs, 1)
+ assert.Equal(t, tt.expectedError, errs[0].Error())
+ })
+ }
+}
+
+func TestOperationTagDefinedRule_RuleMetadata(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.OperationTagDefinedRule{}
+
+ assert.Equal(t, "style-operation-tag-defined", rule.ID())
+ assert.Equal(t, rules.CategoryStyle, rule.Category())
+ assert.NotEmpty(t, rule.Description())
+ assert.NotEmpty(t, rule.Link())
+ assert.Equal(t, validation.SeverityWarning, rule.DefaultSeverity())
+ assert.Nil(t, rule.Versions())
+}
diff --git a/openapi/linter/rules/operation_tags.go b/openapi/linter/rules/operation_tags.go
new file mode 100644
index 00000000..17be43b3
--- /dev/null
+++ b/openapi/linter/rules/operation_tags.go
@@ -0,0 +1,83 @@
+package rules
+
+import (
+ "context"
+ "fmt"
+ "strings"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/validation"
+)
+
+const RuleStyleOperationTags = "style-operation-tags"
+
+type OperationTagsRule struct{}
+
+func (r *OperationTagsRule) ID() string {
+ return RuleStyleOperationTags
+}
+
+func (r *OperationTagsRule) Description() string {
+ return "Operations should have at least one tag to enable logical grouping and organization in documentation. Tags help developers navigate the API by categorizing related operations together."
+}
+
+func (r *OperationTagsRule) Summary() string {
+ return "Operations should have at least one tag."
+}
+
+func (r *OperationTagsRule) HowToFix() string {
+ return "Add at least one tag to each operation."
+}
+
+func (r *OperationTagsRule) Category() string {
+ return CategoryStyle
+}
+
+func (r *OperationTagsRule) DefaultSeverity() validation.Severity {
+ return validation.SeverityWarning
+}
+
+func (r *OperationTagsRule) Link() string {
+ return "https://github.com/speakeasy-api/openapi/blob/main/openapi/linter/README.md#style-operation-tags"
+}
+
+func (r *OperationTagsRule) Versions() []string {
+ return nil // applies to all versions
+}
+
+func (r *OperationTagsRule) Run(ctx context.Context, docInfo *linter.DocumentInfo[*openapi.OpenAPI], config *linter.RuleConfig) []error {
+ if docInfo == nil || docInfo.Document == nil || docInfo.Index == nil {
+ return nil
+ }
+
+ var errs []error
+
+ for _, opNode := range docInfo.Index.Operations {
+ operation := opNode.Node
+ if operation == nil {
+ continue
+ }
+
+ tags := operation.GetTags()
+ if len(tags) == 0 {
+ // Get operation identifier (prefer operationId, fallback to method + path)
+ opIdentifier := operation.GetOperationID()
+ if opIdentifier == "" {
+ method, path := openapi.ExtractMethodAndPath(opNode.Location)
+ if method != "" {
+ opIdentifier = fmt.Sprintf("`%s` %s", strings.ToUpper(method), path)
+ }
+ }
+
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleStyleOperationTags,
+ fmt.Errorf("the %s is missing tags", opIdentifier),
+ operation.GetRootNode(),
+ ))
+ }
+ }
+
+ return errs
+}
diff --git a/openapi/linter/rules/operation_tags_test.go b/openapi/linter/rules/operation_tags_test.go
new file mode 100644
index 00000000..801fc7b5
--- /dev/null
+++ b/openapi/linter/rules/operation_tags_test.go
@@ -0,0 +1,209 @@
+package rules_test
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/openapi/linter/rules"
+ "github.com/speakeasy-api/openapi/references"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestOperationTagsRule_ValidCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "operation with tags",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ tags:
+ - users
+ responses:
+ '200':
+ description: ok
+`,
+ },
+ {
+ name: "operation with multiple tags",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ tags:
+ - users
+ - public
+ responses:
+ '200':
+ description: ok
+`,
+ },
+ {
+ name: "all operations have tags",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ tags:
+ - users
+ responses:
+ '200':
+ description: ok
+ post:
+ tags:
+ - users
+ responses:
+ '201':
+ description: created
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+
+ rule := &rules.OperationTagsRule{}
+ config := &linter.RuleConfig{}
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+ assert.Empty(t, errs)
+ })
+ }
+}
+
+func TestOperationTagsRule_Violations(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ expectedError string
+ }{
+ {
+ name: "operation without tags",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ expectedError: "[9:7] warning style-operation-tags the `GET` /users is missing tags",
+ },
+ {
+ name: "operation with operationId but no tags",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ post:
+ operationId: createUser
+ responses:
+ '201':
+ description: created
+`,
+ expectedError: "[9:7] warning style-operation-tags the createUser is missing tags",
+ },
+ {
+ name: "one operation with tags, one without",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ tags:
+ - users
+ responses:
+ '200':
+ description: ok
+ post:
+ responses:
+ '201':
+ description: created
+`,
+ expectedError: "[15:7] warning style-operation-tags the `POST` /users is missing tags",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+
+ rule := &rules.OperationTagsRule{}
+ config := &linter.RuleConfig{}
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ require.NotEmpty(t, errs)
+ assert.Equal(t, tt.expectedError, errs[0].Error())
+ })
+ }
+}
+
+func TestOperationTagsRule_RuleMetadata(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.OperationTagsRule{}
+
+ assert.Equal(t, "style-operation-tags", rule.ID())
+ assert.Equal(t, rules.CategoryStyle, rule.Category())
+ assert.NotEmpty(t, rule.Description())
+ assert.NotEmpty(t, rule.Link())
+ assert.Equal(t, validation.SeverityWarning, rule.DefaultSeverity())
+ assert.Nil(t, rule.Versions())
+}
diff --git a/openapi/linter/rules/owasp_additional_properties_constrained.go b/openapi/linter/rules/owasp_additional_properties_constrained.go
new file mode 100644
index 00000000..cf538e18
--- /dev/null
+++ b/openapi/linter/rules/owasp_additional_properties_constrained.go
@@ -0,0 +1,110 @@
+package rules
+
+import (
+ "context"
+ "errors"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/validation"
+)
+
+const RuleOwaspAdditionalPropertiesConstrained = "owasp-additional-properties-constrained"
+
+type OwaspAdditionalPropertiesConstrainedRule struct{}
+
+func (r *OwaspAdditionalPropertiesConstrainedRule) ID() string {
+ return RuleOwaspAdditionalPropertiesConstrained
+}
+func (r *OwaspAdditionalPropertiesConstrainedRule) Category() string {
+ return CategorySecurity
+}
+func (r *OwaspAdditionalPropertiesConstrainedRule) Description() string {
+ return "Schemas with additionalProperties set to true or a schema should define maxProperties to limit object size. Without size limits, APIs are vulnerable to resource exhaustion attacks where clients send excessively large objects."
+}
+func (r *OwaspAdditionalPropertiesConstrainedRule) Summary() string {
+ return "Schemas with additionalProperties should define maxProperties."
+}
+func (r *OwaspAdditionalPropertiesConstrainedRule) HowToFix() string {
+ return "When additionalProperties is true or a schema, add a maxProperties limit to bound object size."
+}
+func (r *OwaspAdditionalPropertiesConstrainedRule) Link() string {
+ return "https://github.com/speakeasy-api/openapi/blob/main/openapi/linter/README.md#owasp-additional-properties-constrained"
+}
+func (r *OwaspAdditionalPropertiesConstrainedRule) DefaultSeverity() validation.Severity {
+ return validation.SeverityHint
+}
+func (r *OwaspAdditionalPropertiesConstrainedRule) Versions() []string {
+ return []string{"3.0", "3.1"}
+}
+
+func (r *OwaspAdditionalPropertiesConstrainedRule) Run(ctx context.Context, docInfo *linter.DocumentInfo[*openapi.OpenAPI], config *linter.RuleConfig) []error {
+ if docInfo == nil || docInfo.Document == nil || docInfo.Index == nil {
+ return nil
+ }
+
+ var errs []error
+
+ // Check all schemas in the document
+ for _, schemaNode := range docInfo.Index.GetAllSchemas() {
+ refSchema := schemaNode.Node
+ schema := refSchema.GetSchema()
+ if schema == nil {
+ continue
+ }
+
+ // Check if type contains "object"
+ types := schema.GetType()
+ hasObjectType := false
+ for _, typ := range types {
+ if typ == "object" {
+ hasObjectType = true
+ break
+ }
+ }
+
+ if !hasObjectType {
+ continue
+ }
+
+ // Check additionalProperties
+ additionalProps := schema.GetAdditionalProperties()
+ if additionalProps == nil {
+ // Not set - no constraint needed
+ continue
+ }
+
+ // Check if additionalProperties allows additional properties
+ // (either as a schema object or as true)
+ allowsAdditional := false
+
+ if additionalProps.IsBool() {
+ // It's a boolean value
+ boolVal := additionalProps.GetBool()
+ if boolVal != nil && *boolVal {
+ // additionalProperties: true
+ allowsAdditional = true
+ }
+ } else {
+ // It's a schema object - allows additional properties
+ allowsAdditional = true
+ }
+
+ // If additional properties are allowed, maxProperties should be defined
+ if allowsAdditional {
+ maxProps := schema.GetMaxProperties()
+ if maxProps == nil {
+ if rootNode := refSchema.GetRootNode(); rootNode != nil {
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleOwaspAdditionalPropertiesConstrained,
+ errors.New("schema should define maxProperties when additionalProperties is set to true or a schema"),
+ rootNode,
+ ))
+ }
+ }
+ }
+ }
+
+ return errs
+}
diff --git a/openapi/linter/rules/owasp_additional_properties_constrained_test.go b/openapi/linter/rules/owasp_additional_properties_constrained_test.go
new file mode 100644
index 00000000..b14c7b59
--- /dev/null
+++ b/openapi/linter/rules/owasp_additional_properties_constrained_test.go
@@ -0,0 +1,250 @@
+package rules_test
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/openapi/linter/rules"
+ "github.com/speakeasy-api/openapi/references"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestOwaspAdditionalPropertiesConstrainedRule_ValidCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "object without additionalProperties",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ User:
+ type: object
+ properties:
+ name:
+ type: string
+ maxLength: 100
+paths: {}
+`,
+ },
+ {
+ name: "object with additionalProperties false",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ User:
+ type: object
+ properties:
+ name:
+ type: string
+ maxLength: 100
+ additionalProperties: false
+paths: {}
+`,
+ },
+ {
+ name: "object with additionalProperties true and maxProperties",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Config:
+ type: object
+ properties:
+ setting:
+ type: string
+ maxLength: 50
+ additionalProperties: true
+ maxProperties: 10
+paths: {}
+`,
+ },
+ {
+ name: "object with additionalProperties schema and maxProperties",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Config:
+ type: object
+ properties:
+ name:
+ type: string
+ maxLength: 100
+ additionalProperties:
+ type: string
+ maxLength: 50
+ maxProperties: 20
+paths: {}
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspAdditionalPropertiesConstrainedRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+ assert.Empty(t, errs)
+ })
+ }
+}
+
+func TestOwaspAdditionalPropertiesConstrainedRule_Violations(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ expectedCount int
+ }{
+ {
+ name: "object with additionalProperties true without maxProperties",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Config:
+ type: object
+ properties:
+ setting:
+ type: string
+ maxLength: 50
+ additionalProperties: true
+paths: {}
+`,
+ expectedCount: 1,
+ },
+ {
+ name: "object with additionalProperties schema without maxProperties",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Config:
+ type: object
+ properties:
+ name:
+ type: string
+ maxLength: 100
+ additionalProperties:
+ type: string
+ maxLength: 50
+paths: {}
+`,
+ expectedCount: 1,
+ },
+ {
+ name: "multiple objects with violations",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Config1:
+ type: object
+ properties:
+ setting:
+ type: string
+ maxLength: 50
+ additionalProperties: true
+ Config2:
+ type: object
+ properties:
+ value:
+ type: string
+ maxLength: 100
+ additionalProperties:
+ type: integer
+ format: int32
+paths: {}
+`,
+ expectedCount: 2,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspAdditionalPropertiesConstrainedRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ require.Len(t, errs, tt.expectedCount)
+ for _, err := range errs {
+ assert.Contains(t, err.Error(), "maxProperties")
+ }
+ })
+ }
+}
+
+func TestOwaspAdditionalPropertiesConstrainedRule_RuleMetadata(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.OwaspAdditionalPropertiesConstrainedRule{}
+
+ assert.Equal(t, "owasp-additional-properties-constrained", rule.ID())
+ assert.Equal(t, rules.CategorySecurity, rule.Category())
+ assert.NotEmpty(t, rule.Description())
+ assert.NotEmpty(t, rule.Link())
+ assert.Equal(t, validation.SeverityHint, rule.DefaultSeverity())
+ assert.Equal(t, []string{"3.0", "3.1"}, rule.Versions())
+}
diff --git a/openapi/linter/rules/owasp_array_limit.go b/openapi/linter/rules/owasp_array_limit.go
new file mode 100644
index 00000000..340b18f9
--- /dev/null
+++ b/openapi/linter/rules/owasp_array_limit.go
@@ -0,0 +1,85 @@
+package rules
+
+import (
+ "context"
+ "errors"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/validation"
+)
+
+const RuleOwaspArrayLimit = "owasp-array-limit"
+
+type OwaspArrayLimitRule struct{}
+
+func (r *OwaspArrayLimitRule) ID() string {
+ return RuleOwaspArrayLimit
+}
+func (r *OwaspArrayLimitRule) Category() string {
+ return CategorySecurity
+}
+func (r *OwaspArrayLimitRule) Description() string {
+ return "Array schemas must specify `maxItems` to prevent resource exhaustion attacks. Without array size limits, malicious clients could send extremely large arrays that consume excessive memory or processing time."
+}
+func (r *OwaspArrayLimitRule) Summary() string {
+ return "Array schemas must specify `maxItems`."
+}
+func (r *OwaspArrayLimitRule) HowToFix() string {
+ return "Add a `maxItems` constraint to array schemas to cap the allowed number of items."
+}
+func (r *OwaspArrayLimitRule) Link() string {
+ return "https://github.com/speakeasy-api/openapi/blob/main/openapi/linter/README.md#owasp-array-limit"
+}
+func (r *OwaspArrayLimitRule) DefaultSeverity() validation.Severity {
+ return validation.SeverityError
+}
+func (r *OwaspArrayLimitRule) Versions() []string {
+ return []string{"3.0", "3.1"} // OAS3 only
+}
+
+func (r *OwaspArrayLimitRule) Run(ctx context.Context, docInfo *linter.DocumentInfo[*openapi.OpenAPI], config *linter.RuleConfig) []error {
+ if docInfo == nil || docInfo.Document == nil || docInfo.Index == nil {
+ return nil
+ }
+
+ var errs []error
+
+ // Check all schemas
+ for _, schemaNode := range docInfo.Index.GetAllSchemas() {
+ refSchema := schemaNode.Node
+ schema := refSchema.GetSchema()
+ if schema == nil {
+ continue
+ }
+
+ // Check if type contains "array"
+ types := schema.GetType()
+ hasArrayType := false
+ for _, typ := range types {
+ if typ == "array" {
+ hasArrayType = true
+ break
+ }
+ }
+
+ if !hasArrayType {
+ continue
+ }
+
+ // Check if maxItems is defined
+ maxItems := schema.GetMaxItems()
+ if maxItems == nil {
+ if rootNode := refSchema.GetRootNode(); rootNode != nil {
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleOwaspArrayLimit,
+ errors.New("schema of type `array` must specify `maxItems`"),
+ rootNode,
+ ))
+ }
+ }
+ }
+
+ return errs
+}
diff --git a/openapi/linter/rules/owasp_array_limit_test.go b/openapi/linter/rules/owasp_array_limit_test.go
new file mode 100644
index 00000000..e2df7d60
--- /dev/null
+++ b/openapi/linter/rules/owasp_array_limit_test.go
@@ -0,0 +1,282 @@
+package rules_test
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/openapi/linter/rules"
+ "github.com/speakeasy-api/openapi/references"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestOwaspArrayLimitRule_ValidCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "array with maxItems",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Items:
+ type: array
+ maxItems: 100
+ items:
+ type: string
+paths: {}
+`,
+ },
+ {
+ name: "non-array schema without maxItems",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ User:
+ type: object
+ properties:
+ name:
+ type: string
+paths: {}
+`,
+ },
+ {
+ name: "string schema without maxItems",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Name:
+ type: string
+paths: {}
+`,
+ },
+ {
+ name: "array in response with maxItems",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ content:
+ application/json:
+ schema:
+ type: array
+ maxItems: 50
+ items:
+ type: object
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspArrayLimitRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+ assert.Empty(t, errs)
+ })
+ }
+}
+
+func TestOwaspArrayLimitRule_Violations(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ expectedCount int
+ expectedText string
+ }{
+ {
+ name: "array without maxItems in component",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Items:
+ type: array
+ items:
+ type: string
+paths: {}
+`,
+ expectedCount: 1,
+ expectedText: "maxItems",
+ },
+ {
+ name: "array without maxItems in response",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ type: object
+`,
+ expectedCount: 1,
+ expectedText: "maxItems",
+ },
+ {
+ name: "multiple arrays without maxItems",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Items:
+ type: array
+ items:
+ type: string
+ Tags:
+ type: array
+ items:
+ type: string
+paths: {}
+`,
+ expectedCount: 2,
+ expectedText: "",
+ },
+ {
+ name: "array in request body without maxItems",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ post:
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ type: object
+ responses:
+ '201':
+ description: Created
+`,
+ expectedCount: 1,
+ expectedText: "maxItems",
+ },
+ {
+ name: "nested array without maxItems",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ User:
+ type: object
+ properties:
+ tags:
+ type: array
+ items:
+ type: string
+paths: {}
+`,
+ expectedCount: 1,
+ expectedText: "maxItems",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspArrayLimitRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ require.Len(t, errs, tt.expectedCount)
+ for _, err := range errs {
+ assert.Contains(t, err.Error(), "array")
+ if tt.expectedText != "" {
+ assert.Contains(t, err.Error(), tt.expectedText)
+ }
+ }
+ })
+ }
+}
+
+func TestOwaspArrayLimitRule_RuleMetadata(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.OwaspArrayLimitRule{}
+
+ assert.Equal(t, "owasp-array-limit", rule.ID())
+ assert.Equal(t, rules.CategorySecurity, rule.Category())
+ assert.NotEmpty(t, rule.Description())
+ assert.NotEmpty(t, rule.Link())
+ assert.Equal(t, validation.SeverityError, rule.DefaultSeverity())
+ assert.Equal(t, []string{"3.0", "3.1"}, rule.Versions())
+}
diff --git a/openapi/linter/rules/owasp_auth_insecure_schemes.go b/openapi/linter/rules/owasp_auth_insecure_schemes.go
new file mode 100644
index 00000000..0bfb8188
--- /dev/null
+++ b/openapi/linter/rules/owasp_auth_insecure_schemes.go
@@ -0,0 +1,97 @@
+package rules
+
+import (
+ "context"
+ "fmt"
+ "strings"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/speakeasy-api/openapi/yml"
+)
+
+const RuleOwaspAuthInsecureSchemes = "owasp-auth-insecure-schemes"
+
+type OwaspAuthInsecureSchemesRule struct{}
+
+func (r *OwaspAuthInsecureSchemesRule) ID() string { return RuleOwaspAuthInsecureSchemes }
+func (r *OwaspAuthInsecureSchemesRule) Category() string { return CategorySecurity }
+func (r *OwaspAuthInsecureSchemesRule) Description() string {
+ return "Authentication schemes using outdated or insecure methods must be avoided or upgraded. Insecure authentication schemes like API keys in query parameters or `HTTP Basic` over `HTTP` expose credentials and create security vulnerabilities."
+}
+func (r *OwaspAuthInsecureSchemesRule) Summary() string {
+ return "Security schemes must not use outdated or insecure HTTP schemes."
+}
+func (r *OwaspAuthInsecureSchemesRule) HowToFix() string {
+ return "Replace insecure `HTTP` schemes (`negotiate`/`oauth`) with modern authentication like `OAuth 2.0` or `bearer` tokens."
+}
+func (r *OwaspAuthInsecureSchemesRule) Link() string {
+ return "https://github.com/speakeasy-api/openapi/blob/main/openapi/linter/README.md#owasp-auth-insecure-schemes"
+}
+func (r *OwaspAuthInsecureSchemesRule) DefaultSeverity() validation.Severity {
+ return validation.SeverityError
+}
+func (r *OwaspAuthInsecureSchemesRule) Versions() []string {
+ return nil // Applies to all OpenAPI versions
+}
+
+func (r *OwaspAuthInsecureSchemesRule) Run(ctx context.Context, docInfo *linter.DocumentInfo[*openapi.OpenAPI], config *linter.RuleConfig) []error {
+ if docInfo == nil || docInfo.Document == nil {
+ return nil
+ }
+
+ doc := docInfo.Document
+ components := doc.GetComponents()
+ if components == nil {
+ return nil
+ }
+
+ securitySchemes := components.GetSecuritySchemes()
+ if securitySchemes == nil {
+ return nil
+ }
+
+ var errs []error
+
+ // Iterate through all security schemes
+ for name, scheme := range securitySchemes.All() {
+ if scheme == nil {
+ continue
+ }
+
+ // Get the security scheme object
+ secScheme := scheme.GetObject()
+ if secScheme == nil {
+ continue
+ }
+
+ // Check if this is an HTTP type security scheme
+ schemeType := secScheme.GetType()
+ if schemeType != "http" {
+ continue
+ }
+
+ // Get the scheme value (basic, bearer, negotiate, oauth, etc.)
+ httpScheme := secScheme.GetScheme()
+ httpSchemeLower := strings.ToLower(httpScheme)
+
+ // Check if it's negotiate or oauth (both insecure/outdated)
+ if httpSchemeLower == "negotiate" || httpSchemeLower == "oauth" {
+ // Get the root node to find the scheme key
+ if rootNode := secScheme.GetRootNode(); rootNode != nil {
+ _, schemeValueNode, found := yml.GetMapElementNodes(ctx, rootNode, "scheme")
+ if found && schemeValueNode != nil {
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleOwaspAuthInsecureSchemes,
+ fmt.Errorf("security scheme `%s` uses `%s` which is outdated or insecure - use modern authentication like `OAuth 2.0` or `bearer` tokens", name, httpScheme),
+ schemeValueNode,
+ ))
+ }
+ }
+ }
+ }
+
+ return errs
+}
diff --git a/openapi/linter/rules/owasp_auth_insecure_schemes_test.go b/openapi/linter/rules/owasp_auth_insecure_schemes_test.go
new file mode 100644
index 00000000..da282b7e
--- /dev/null
+++ b/openapi/linter/rules/owasp_auth_insecure_schemes_test.go
@@ -0,0 +1,268 @@
+package rules_test
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/openapi/linter/rules"
+ "github.com/speakeasy-api/openapi/references"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestOwaspAuthInsecureSchemesRule_ValidCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "bearer authentication",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ securitySchemes:
+ bearerAuth:
+ type: http
+ scheme: bearer
+ bearerFormat: JWT
+paths: {}
+`,
+ },
+ {
+ name: "digest authentication",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ securitySchemes:
+ digestAuth:
+ type: http
+ scheme: digest
+paths: {}
+`,
+ },
+ {
+ name: "oauth2 authentication (not http oauth)",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ securitySchemes:
+ oauth:
+ type: oauth2
+ flows:
+ implicit:
+ authorizationUrl: https://example.com/oauth/authorize
+ scopes:
+ read: Read access
+paths: {}
+`,
+ },
+ {
+ name: "api key authentication",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ securitySchemes:
+ apiKey:
+ type: apiKey
+ in: header
+ name: X-API-Key
+paths: {}
+`,
+ },
+ {
+ name: "no security schemes",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths: {}
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspAuthInsecureSchemesRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+ assert.Empty(t, errs)
+ })
+ }
+}
+
+func TestOwaspAuthInsecureSchemesRule_Violations(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ expectedCount int
+ expectedText string
+ }{
+ {
+ name: "negotiate authentication",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ securitySchemes:
+ negotiateAuth:
+ type: http
+ scheme: negotiate
+paths: {}
+`,
+ expectedCount: 1,
+ expectedText: "negotiate",
+ },
+ {
+ name: "oauth authentication (http type)",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ securitySchemes:
+ oauthAuth:
+ type: http
+ scheme: oauth
+paths: {}
+`,
+ expectedCount: 1,
+ expectedText: "oauth",
+ },
+ {
+ name: "multiple insecure schemes",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ securitySchemes:
+ negotiateAuth:
+ type: http
+ scheme: negotiate
+ oauthAuth:
+ type: http
+ scheme: oauth
+paths: {}
+`,
+ expectedCount: 2,
+ expectedText: "",
+ },
+ {
+ name: "case insensitive - NEGOTIATE",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ securitySchemes:
+ negotiateAuth:
+ type: http
+ scheme: NEGOTIATE
+paths: {}
+`,
+ expectedCount: 1,
+ expectedText: "NEGOTIATE",
+ },
+ {
+ name: "case insensitive - OAuth",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ securitySchemes:
+ oauthAuth:
+ type: http
+ scheme: OAuth
+paths: {}
+`,
+ expectedCount: 1,
+ expectedText: "OAuth",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspAuthInsecureSchemesRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ require.Len(t, errs, tt.expectedCount)
+ for _, err := range errs {
+ assert.Contains(t, err.Error(), "outdated or insecure")
+ if tt.expectedText != "" {
+ assert.Contains(t, err.Error(), tt.expectedText)
+ }
+ }
+ })
+ }
+}
+
+func TestOwaspAuthInsecureSchemesRule_RuleMetadata(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.OwaspAuthInsecureSchemesRule{}
+
+ assert.Equal(t, "owasp-auth-insecure-schemes", rule.ID())
+ assert.Equal(t, rules.CategorySecurity, rule.Category())
+ assert.NotEmpty(t, rule.Description())
+ assert.NotEmpty(t, rule.Link())
+ assert.Equal(t, validation.SeverityError, rule.DefaultSeverity())
+ assert.Nil(t, rule.Versions())
+}
diff --git a/openapi/linter/rules/owasp_define_error_responses_401.go b/openapi/linter/rules/owasp_define_error_responses_401.go
new file mode 100644
index 00000000..dec24447
--- /dev/null
+++ b/openapi/linter/rules/owasp_define_error_responses_401.go
@@ -0,0 +1,124 @@
+package rules
+
+import (
+ "context"
+ "fmt"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/speakeasy-api/openapi/yml"
+)
+
+const RuleOwaspDefineErrorResponses401 = "owasp-define-error-responses-401"
+
+type OwaspDefineErrorResponses401Rule struct{}
+
+func (r *OwaspDefineErrorResponses401Rule) ID() string { return RuleOwaspDefineErrorResponses401 }
+func (r *OwaspDefineErrorResponses401Rule) Category() string {
+ return CategorySecurity
+}
+func (r *OwaspDefineErrorResponses401Rule) Description() string {
+ return "Operations should define a 401 Unauthorized response with a proper schema to handle authentication failures. Documenting authentication error responses helps clients implement proper error handling and understand when credentials are invalid or missing."
+}
+func (r *OwaspDefineErrorResponses401Rule) Summary() string {
+ return "Operations should define a 401 Unauthorized response with a schema."
+}
+func (r *OwaspDefineErrorResponses401Rule) HowToFix() string {
+ return "Add a 401 response with a response body schema to each secured operation."
+}
+func (r *OwaspDefineErrorResponses401Rule) Link() string {
+ return "https://github.com/speakeasy-api/openapi/blob/main/openapi/linter/README.md#owasp-define-error-responses-401"
+}
+func (r *OwaspDefineErrorResponses401Rule) DefaultSeverity() validation.Severity {
+ return validation.SeverityWarning
+}
+func (r *OwaspDefineErrorResponses401Rule) Versions() []string {
+ return nil // Applies to all OpenAPI versions
+}
+
+func (r *OwaspDefineErrorResponses401Rule) Run(ctx context.Context, docInfo *linter.DocumentInfo[*openapi.OpenAPI], config *linter.RuleConfig) []error {
+ if docInfo == nil || docInfo.Document == nil || docInfo.Index == nil {
+ return nil
+ }
+
+ var errs []error
+
+ // Check all operations
+ for _, opNode := range docInfo.Index.Operations {
+ op := opNode.Node
+ if op == nil {
+ continue
+ }
+
+ // Get operation details for error messages
+ method := ""
+ path := ""
+ for _, loc := range opNode.Location {
+ switch openapi.GetParentType(loc) {
+ case "Paths":
+ if loc.ParentKey != nil {
+ path = *loc.ParentKey
+ }
+ case "PathItem":
+ if loc.ParentKey != nil {
+ method = *loc.ParentKey
+ }
+ }
+ }
+
+ responses := op.GetResponses()
+ if responses == nil {
+ // No responses at all - report missing 401
+ if rootNode := op.GetRootNode(); rootNode != nil {
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleOwaspDefineErrorResponses401,
+ fmt.Errorf("operation %s %s is missing 401 Unauthorized error response", method, path),
+ rootNode,
+ ))
+ }
+ continue
+ }
+
+ // Check if 401 response exists
+ response401, has401 := responses.Get("401")
+ if !has401 {
+ // Missing 401 response
+ if rootNode := responses.GetRootNode(); rootNode != nil {
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleOwaspDefineErrorResponses401,
+ fmt.Errorf("operation %s %s is missing 401 Unauthorized error response", method, path),
+ rootNode,
+ ))
+ }
+ continue
+ }
+
+ // 401 exists, check if it has content with schema
+ if response401 != nil {
+ responseObj := response401.GetObject()
+ if responseObj != nil {
+ content := responseObj.GetContent()
+ if content == nil || content.Len() == 0 {
+ // 401 exists but has no content/schema
+ if rootNode := responseObj.GetRootNode(); rootNode != nil {
+ _, responseValueNode, found := yml.GetMapElementNodes(ctx, rootNode, "description")
+ if !found {
+ responseValueNode = rootNode
+ }
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleOwaspDefineErrorResponses401,
+ fmt.Errorf("operation %s %s has 401 response but missing content schema", method, path),
+ responseValueNode,
+ ))
+ }
+ }
+ }
+ }
+ }
+
+ return errs
+}
diff --git a/openapi/linter/rules/owasp_define_error_responses_401_test.go b/openapi/linter/rules/owasp_define_error_responses_401_test.go
new file mode 100644
index 00000000..5e8ab6b1
--- /dev/null
+++ b/openapi/linter/rules/owasp_define_error_responses_401_test.go
@@ -0,0 +1,289 @@
+package rules_test
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/openapi/linter/rules"
+ "github.com/speakeasy-api/openapi/references"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestOwaspDefineErrorResponses401Rule_ValidCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "operation with 401 response and schema",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ '401':
+ description: Unauthorized
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ error:
+ type: string
+`,
+ },
+ {
+ name: "multiple operations all with 401",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ '401':
+ description: Unauthorized
+ content:
+ application/json:
+ schema:
+ type: object
+ post:
+ responses:
+ '201':
+ description: Created
+ '401':
+ description: Unauthorized
+ content:
+ application/json:
+ schema:
+ type: object
+`,
+ },
+ {
+ name: "401 with multiple content types",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ '401':
+ description: Unauthorized
+ content:
+ application/json:
+ schema:
+ type: object
+ application/xml:
+ schema:
+ type: object
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspDefineErrorResponses401Rule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+ assert.Empty(t, errs)
+ })
+ }
+}
+
+func TestOwaspDefineErrorResponses401Rule_Violations(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ expectedCount int
+ expectedText string
+ }{
+ {
+ name: "missing 401 response",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ '500':
+ description: Server Error
+`,
+ expectedCount: 1,
+ expectedText: "missing 401",
+ },
+ {
+ name: "401 exists but no content",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ '401':
+ description: Unauthorized
+`,
+ expectedCount: 1,
+ expectedText: "missing content schema",
+ },
+ {
+ name: "multiple operations missing 401",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ post:
+ responses:
+ '201':
+ description: Created
+`,
+ expectedCount: 2,
+ expectedText: "",
+ },
+ {
+ name: "one operation with 401 one without",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ '401':
+ description: Unauthorized
+ content:
+ application/json:
+ schema:
+ type: object
+ post:
+ responses:
+ '201':
+ description: Created
+`,
+ expectedCount: 1,
+ expectedText: "post",
+ },
+ {
+ name: "401 with empty content object",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ '401':
+ description: Unauthorized
+ content: {}
+`,
+ expectedCount: 1,
+ expectedText: "missing content schema",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspDefineErrorResponses401Rule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ require.Len(t, errs, tt.expectedCount)
+ for _, err := range errs {
+ assert.Contains(t, err.Error(), "401")
+ if tt.expectedText != "" {
+ assert.Contains(t, err.Error(), tt.expectedText)
+ }
+ }
+ })
+ }
+}
+
+func TestOwaspDefineErrorResponses401Rule_RuleMetadata(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.OwaspDefineErrorResponses401Rule{}
+
+ assert.Equal(t, "owasp-define-error-responses-401", rule.ID())
+ assert.Equal(t, rules.CategorySecurity, rule.Category())
+ assert.NotEmpty(t, rule.Description())
+ assert.NotEmpty(t, rule.Link())
+ assert.Equal(t, validation.SeverityWarning, rule.DefaultSeverity())
+ assert.Nil(t, rule.Versions())
+}
diff --git a/openapi/linter/rules/owasp_define_error_responses_429.go b/openapi/linter/rules/owasp_define_error_responses_429.go
new file mode 100644
index 00000000..0c49d8f4
--- /dev/null
+++ b/openapi/linter/rules/owasp_define_error_responses_429.go
@@ -0,0 +1,124 @@
+package rules
+
+import (
+ "context"
+ "fmt"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/speakeasy-api/openapi/yml"
+)
+
+const RuleOwaspDefineErrorResponses429 = "owasp-define-error-responses-429"
+
+type OwaspDefineErrorResponses429Rule struct{}
+
+func (r *OwaspDefineErrorResponses429Rule) ID() string { return RuleOwaspDefineErrorResponses429 }
+func (r *OwaspDefineErrorResponses429Rule) Category() string {
+ return CategorySecurity
+}
+func (r *OwaspDefineErrorResponses429Rule) Description() string {
+ return "Operations should define a 429 Too Many Requests response with a proper schema to indicate rate limiting. Rate limit responses help clients understand when they've exceeded usage thresholds and need to slow down requests."
+}
+func (r *OwaspDefineErrorResponses429Rule) Summary() string {
+ return "Operations should define a 429 Too Many Requests response with a schema."
+}
+func (r *OwaspDefineErrorResponses429Rule) HowToFix() string {
+ return "Add a 429 response with a response body schema to operations that may be rate limited."
+}
+func (r *OwaspDefineErrorResponses429Rule) Link() string {
+ return "https://github.com/speakeasy-api/openapi/blob/main/openapi/linter/README.md#owasp-define-error-responses-429"
+}
+func (r *OwaspDefineErrorResponses429Rule) DefaultSeverity() validation.Severity {
+ return validation.SeverityWarning
+}
+func (r *OwaspDefineErrorResponses429Rule) Versions() []string {
+ return nil // Applies to all OpenAPI versions
+}
+
+func (r *OwaspDefineErrorResponses429Rule) Run(ctx context.Context, docInfo *linter.DocumentInfo[*openapi.OpenAPI], config *linter.RuleConfig) []error {
+ if docInfo == nil || docInfo.Document == nil || docInfo.Index == nil {
+ return nil
+ }
+
+ var errs []error
+
+ // Check all operations
+ for _, opNode := range docInfo.Index.Operations {
+ op := opNode.Node
+ if op == nil {
+ continue
+ }
+
+ // Get operation details for error messages
+ method := ""
+ path := ""
+ for _, loc := range opNode.Location {
+ switch openapi.GetParentType(loc) {
+ case "Paths":
+ if loc.ParentKey != nil {
+ path = *loc.ParentKey
+ }
+ case "PathItem":
+ if loc.ParentKey != nil {
+ method = *loc.ParentKey
+ }
+ }
+ }
+
+ responses := op.GetResponses()
+ if responses == nil {
+ // No responses at all - report missing 429
+ if rootNode := op.GetRootNode(); rootNode != nil {
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleOwaspDefineErrorResponses429,
+ fmt.Errorf("operation %s %s is missing 429 Too Many Requests response", method, path),
+ rootNode,
+ ))
+ }
+ continue
+ }
+
+ // Check if 429 response exists
+ response429, has429 := responses.Get("429")
+ if !has429 {
+ // Missing 429 response
+ if rootNode := responses.GetRootNode(); rootNode != nil {
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleOwaspDefineErrorResponses429,
+ fmt.Errorf("operation %s %s is missing 429 Too Many Requests response", method, path),
+ rootNode,
+ ))
+ }
+ continue
+ }
+
+ // 429 exists, check if it has content with schema
+ if response429 != nil {
+ responseObj := response429.GetObject()
+ if responseObj != nil {
+ content := responseObj.GetContent()
+ if content == nil || content.Len() == 0 {
+ // 429 exists but has no content/schema
+ if rootNode := responseObj.GetRootNode(); rootNode != nil {
+ _, responseValueNode, found := yml.GetMapElementNodes(ctx, rootNode, "description")
+ if !found {
+ responseValueNode = rootNode
+ }
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleOwaspDefineErrorResponses429,
+ fmt.Errorf("operation %s %s has 429 response but missing content schema", method, path),
+ responseValueNode,
+ ))
+ }
+ }
+ }
+ }
+ }
+
+ return errs
+}
diff --git a/openapi/linter/rules/owasp_define_error_responses_429_test.go b/openapi/linter/rules/owasp_define_error_responses_429_test.go
new file mode 100644
index 00000000..6e538c9f
--- /dev/null
+++ b/openapi/linter/rules/owasp_define_error_responses_429_test.go
@@ -0,0 +1,213 @@
+package rules_test
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/openapi/linter/rules"
+ "github.com/speakeasy-api/openapi/references"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestOwaspDefineErrorResponses429Rule_ValidCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "operation with 429 response and schema",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ '429':
+ description: Too Many Requests
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ error:
+ type: string
+`,
+ },
+ {
+ name: "429 with retry-after header",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ '429':
+ description: Too Many Requests
+ headers:
+ Retry-After:
+ description: Number of seconds to wait
+ schema:
+ type: integer
+ content:
+ application/json:
+ schema:
+ type: object
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspDefineErrorResponses429Rule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+ assert.Empty(t, errs)
+ })
+ }
+}
+
+func TestOwaspDefineErrorResponses429Rule_Violations(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ expectedCount int
+ expectedText string
+ }{
+ {
+ name: "missing 429 response",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ '401':
+ description: Unauthorized
+`,
+ expectedCount: 1,
+ expectedText: "missing 429",
+ },
+ {
+ name: "429 exists but no content",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ '429':
+ description: Too Many Requests
+`,
+ expectedCount: 1,
+ expectedText: "missing content schema",
+ },
+ {
+ name: "multiple operations missing 429",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ post:
+ responses:
+ '201':
+ description: Created
+`,
+ expectedCount: 2,
+ expectedText: "",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspDefineErrorResponses429Rule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ require.Len(t, errs, tt.expectedCount)
+ for _, err := range errs {
+ assert.Contains(t, err.Error(), "429")
+ if tt.expectedText != "" {
+ assert.Contains(t, err.Error(), tt.expectedText)
+ }
+ }
+ })
+ }
+}
+
+func TestOwaspDefineErrorResponses429Rule_RuleMetadata(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.OwaspDefineErrorResponses429Rule{}
+
+ assert.Equal(t, "owasp-define-error-responses-429", rule.ID())
+ assert.Equal(t, rules.CategorySecurity, rule.Category())
+ assert.NotEmpty(t, rule.Description())
+ assert.NotEmpty(t, rule.Link())
+ assert.Equal(t, validation.SeverityWarning, rule.DefaultSeverity())
+ assert.Nil(t, rule.Versions())
+}
diff --git a/openapi/linter/rules/owasp_define_error_responses_500.go b/openapi/linter/rules/owasp_define_error_responses_500.go
new file mode 100644
index 00000000..d807c958
--- /dev/null
+++ b/openapi/linter/rules/owasp_define_error_responses_500.go
@@ -0,0 +1,124 @@
+package rules
+
+import (
+ "context"
+ "fmt"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/speakeasy-api/openapi/yml"
+)
+
+const RuleOwaspDefineErrorResponses500 = "owasp-define-error-responses-500"
+
+type OwaspDefineErrorResponses500Rule struct{}
+
+func (r *OwaspDefineErrorResponses500Rule) ID() string { return RuleOwaspDefineErrorResponses500 }
+func (r *OwaspDefineErrorResponses500Rule) Category() string {
+ return CategorySecurity
+}
+func (r *OwaspDefineErrorResponses500Rule) Description() string {
+ return "Operations should define a 500 Internal Server Error response with a proper schema to handle unexpected failures. Documenting server error responses helps clients distinguish between client-side and server-side problems."
+}
+func (r *OwaspDefineErrorResponses500Rule) Summary() string {
+ return "Operations should define a 500 Internal Server Error response with a schema."
+}
+func (r *OwaspDefineErrorResponses500Rule) HowToFix() string {
+ return "Add a 500 response with a response body schema to each operation."
+}
+func (r *OwaspDefineErrorResponses500Rule) Link() string {
+ return "https://github.com/speakeasy-api/openapi/blob/main/openapi/linter/README.md#owasp-define-error-responses-500"
+}
+func (r *OwaspDefineErrorResponses500Rule) DefaultSeverity() validation.Severity {
+ return validation.SeverityWarning
+}
+func (r *OwaspDefineErrorResponses500Rule) Versions() []string {
+ return nil // Applies to all OpenAPI versions
+}
+
+func (r *OwaspDefineErrorResponses500Rule) Run(ctx context.Context, docInfo *linter.DocumentInfo[*openapi.OpenAPI], config *linter.RuleConfig) []error {
+ if docInfo == nil || docInfo.Document == nil || docInfo.Index == nil {
+ return nil
+ }
+
+ var errs []error
+
+ // Check all operations
+ for _, opNode := range docInfo.Index.Operations {
+ op := opNode.Node
+ if op == nil {
+ continue
+ }
+
+ // Get operation details for error messages
+ method := ""
+ path := ""
+ for _, loc := range opNode.Location {
+ switch openapi.GetParentType(loc) {
+ case "Paths":
+ if loc.ParentKey != nil {
+ path = *loc.ParentKey
+ }
+ case "PathItem":
+ if loc.ParentKey != nil {
+ method = *loc.ParentKey
+ }
+ }
+ }
+
+ responses := op.GetResponses()
+ if responses == nil {
+ // No responses at all - report missing 500
+ if rootNode := op.GetRootNode(); rootNode != nil {
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleOwaspDefineErrorResponses500,
+ fmt.Errorf("operation %s %s is missing 500 Internal Server Error response", method, path),
+ rootNode,
+ ))
+ }
+ continue
+ }
+
+ // Check if 500 response exists
+ response500, has500 := responses.Get("500")
+ if !has500 {
+ // Missing 500 response
+ if rootNode := responses.GetRootNode(); rootNode != nil {
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleOwaspDefineErrorResponses500,
+ fmt.Errorf("operation %s %s is missing 500 Internal Server Error response", method, path),
+ rootNode,
+ ))
+ }
+ continue
+ }
+
+ // 500 exists, check if it has content with schema
+ if response500 != nil {
+ responseObj := response500.GetObject()
+ if responseObj != nil {
+ content := responseObj.GetContent()
+ if content == nil || content.Len() == 0 {
+ // 500 exists but has no content/schema
+ if rootNode := responseObj.GetRootNode(); rootNode != nil {
+ _, responseValueNode, found := yml.GetMapElementNodes(ctx, rootNode, "description")
+ if !found {
+ responseValueNode = rootNode
+ }
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleOwaspDefineErrorResponses500,
+ fmt.Errorf("operation %s %s has 500 response but missing content schema", method, path),
+ responseValueNode,
+ ))
+ }
+ }
+ }
+ }
+ }
+
+ return errs
+}
diff --git a/openapi/linter/rules/owasp_define_error_responses_500_test.go b/openapi/linter/rules/owasp_define_error_responses_500_test.go
new file mode 100644
index 00000000..49556098
--- /dev/null
+++ b/openapi/linter/rules/owasp_define_error_responses_500_test.go
@@ -0,0 +1,218 @@
+package rules_test
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/openapi/linter/rules"
+ "github.com/speakeasy-api/openapi/references"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestOwaspDefineErrorResponses500Rule_ValidCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "operation with 500 response and schema",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ '500':
+ description: Internal Server Error
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ error:
+ type: string
+`,
+ },
+ {
+ name: "multiple operations all with 500",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ '500':
+ description: Internal Server Error
+ content:
+ application/json:
+ schema:
+ type: object
+ post:
+ responses:
+ '201':
+ description: Created
+ '500':
+ description: Internal Server Error
+ content:
+ application/json:
+ schema:
+ type: object
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspDefineErrorResponses500Rule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+ assert.Empty(t, errs)
+ })
+ }
+}
+
+func TestOwaspDefineErrorResponses500Rule_Violations(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ expectedCount int
+ expectedText string
+ }{
+ {
+ name: "missing 500 response",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ '401':
+ description: Unauthorized
+`,
+ expectedCount: 1,
+ expectedText: "missing 500",
+ },
+ {
+ name: "500 exists but no content",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ '500':
+ description: Internal Server Error
+`,
+ expectedCount: 1,
+ expectedText: "missing content schema",
+ },
+ {
+ name: "multiple operations missing 500",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ post:
+ responses:
+ '201':
+ description: Created
+`,
+ expectedCount: 2,
+ expectedText: "",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspDefineErrorResponses500Rule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ require.Len(t, errs, tt.expectedCount)
+ for _, err := range errs {
+ assert.Contains(t, err.Error(), "500")
+ if tt.expectedText != "" {
+ assert.Contains(t, err.Error(), tt.expectedText)
+ }
+ }
+ })
+ }
+}
+
+func TestOwaspDefineErrorResponses500Rule_RuleMetadata(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.OwaspDefineErrorResponses500Rule{}
+
+ assert.Equal(t, "owasp-define-error-responses-500", rule.ID())
+ assert.Equal(t, rules.CategorySecurity, rule.Category())
+ assert.NotEmpty(t, rule.Description())
+ assert.NotEmpty(t, rule.Link())
+ assert.Equal(t, validation.SeverityWarning, rule.DefaultSeverity())
+ assert.Nil(t, rule.Versions())
+}
diff --git a/openapi/linter/rules/owasp_define_error_validation.go b/openapi/linter/rules/owasp_define_error_validation.go
new file mode 100644
index 00000000..95a71637
--- /dev/null
+++ b/openapi/linter/rules/owasp_define_error_validation.go
@@ -0,0 +1,102 @@
+package rules
+
+import (
+ "context"
+ "fmt"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/validation"
+)
+
+const RuleOwaspDefineErrorValidation = "owasp-define-error-validation"
+
+type OwaspDefineErrorValidationRule struct{}
+
+func (r *OwaspDefineErrorValidationRule) ID() string { return RuleOwaspDefineErrorValidation }
+func (r *OwaspDefineErrorValidationRule) Category() string {
+ return CategorySecurity
+}
+func (r *OwaspDefineErrorValidationRule) Description() string {
+ return "Operations should define validation error responses (400, 422, or 4XX) to indicate request data problems. Validation error responses help clients understand when and why their request data is invalid or malformed."
+}
+func (r *OwaspDefineErrorValidationRule) Summary() string {
+ return "Operations should define validation error responses (400, 422, or 4XX)."
+}
+func (r *OwaspDefineErrorValidationRule) HowToFix() string {
+ return "Add a 400, 422, or 4XX response with a schema to each operation to describe validation errors."
+}
+func (r *OwaspDefineErrorValidationRule) Link() string {
+ return "https://github.com/speakeasy-api/openapi/blob/main/openapi/linter/README.md#owasp-define-error-validation"
+}
+func (r *OwaspDefineErrorValidationRule) DefaultSeverity() validation.Severity {
+ return validation.SeverityWarning
+}
+func (r *OwaspDefineErrorValidationRule) Versions() []string {
+ return nil // Applies to all OpenAPI versions
+}
+
+func (r *OwaspDefineErrorValidationRule) Run(ctx context.Context, docInfo *linter.DocumentInfo[*openapi.OpenAPI], config *linter.RuleConfig) []error {
+ if docInfo == nil || docInfo.Document == nil || docInfo.Index == nil {
+ return nil
+ }
+
+ var errs []error
+
+ // Check all operations
+ for _, opNode := range docInfo.Index.Operations {
+ op := opNode.Node
+ if op == nil {
+ continue
+ }
+
+ // Get operation details for error messages
+ method := ""
+ path := ""
+ for _, loc := range opNode.Location {
+ switch openapi.GetParentType(loc) {
+ case "Paths":
+ if loc.ParentKey != nil {
+ path = *loc.ParentKey
+ }
+ case "PathItem":
+ if loc.ParentKey != nil {
+ method = *loc.ParentKey
+ }
+ }
+ }
+
+ responses := op.GetResponses()
+ if responses == nil {
+ // No responses at all - report missing validation error response
+ if rootNode := op.GetRootNode(); rootNode != nil {
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleOwaspDefineErrorValidation,
+ fmt.Errorf("operation %s %s is missing validation error response (400, 422, or 4XX)", method, path),
+ rootNode,
+ ))
+ }
+ continue
+ }
+
+ // Check if any of the validation error codes exist
+ has400, _ := responses.Get("400")
+ has422, _ := responses.Get("422")
+ has4XX, _ := responses.Get("4XX")
+
+ if has400 == nil && has422 == nil && has4XX == nil {
+ // Missing all validation error responses
+ if rootNode := responses.GetRootNode(); rootNode != nil {
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleOwaspDefineErrorValidation,
+ fmt.Errorf("operation %s %s is missing validation error response (should have 400, 422, or 4XX)", method, path),
+ rootNode,
+ ))
+ }
+ }
+ }
+
+ return errs
+}
diff --git a/openapi/linter/rules/owasp_define_error_validation_test.go b/openapi/linter/rules/owasp_define_error_validation_test.go
new file mode 100644
index 00000000..8ab42439
--- /dev/null
+++ b/openapi/linter/rules/owasp_define_error_validation_test.go
@@ -0,0 +1,268 @@
+package rules_test
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/openapi/linter/rules"
+ "github.com/speakeasy-api/openapi/references"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestOwaspDefineErrorValidationRule_ValidCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "operation with 400 response",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ '400':
+ description: Bad Request
+ content:
+ application/json:
+ schema:
+ type: object
+`,
+ },
+ {
+ name: "operation with 422 response",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ post:
+ responses:
+ '201':
+ description: Created
+ '422':
+ description: Unprocessable Entity
+ content:
+ application/json:
+ schema:
+ type: object
+`,
+ },
+ {
+ name: "operation with 4XX wildcard",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ '4XX':
+ description: Client Error
+ content:
+ application/json:
+ schema:
+ type: object
+`,
+ },
+ {
+ name: "operation with multiple validation error codes",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ post:
+ responses:
+ '201':
+ description: Created
+ '400':
+ description: Bad Request
+ '422':
+ description: Unprocessable Entity
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspDefineErrorValidationRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+ assert.Empty(t, errs)
+ })
+ }
+}
+
+func TestOwaspDefineErrorValidationRule_Violations(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ expectedCount int
+ expectedText string
+ }{
+ {
+ name: "missing validation error response",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ '401':
+ description: Unauthorized
+ '500':
+ description: Server Error
+`,
+ expectedCount: 1,
+ expectedText: "missing validation error",
+ },
+ {
+ name: "only success response",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+`,
+ expectedCount: 1,
+ expectedText: "missing validation error",
+ },
+ {
+ name: "multiple operations missing validation errors",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ post:
+ responses:
+ '201':
+ description: Created
+`,
+ expectedCount: 2,
+ expectedText: "",
+ },
+ {
+ name: "one operation with validation error one without",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ '400':
+ description: Bad Request
+ post:
+ responses:
+ '201':
+ description: Created
+`,
+ expectedCount: 1,
+ expectedText: "post",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspDefineErrorValidationRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ require.Len(t, errs, tt.expectedCount)
+ for _, err := range errs {
+ assert.Contains(t, err.Error(), "validation error")
+ if tt.expectedText != "" {
+ assert.Contains(t, err.Error(), tt.expectedText)
+ }
+ }
+ })
+ }
+}
+
+func TestOwaspDefineErrorValidationRule_RuleMetadata(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.OwaspDefineErrorValidationRule{}
+
+ assert.Equal(t, "owasp-define-error-validation", rule.ID())
+ assert.Equal(t, rules.CategorySecurity, rule.Category())
+ assert.NotEmpty(t, rule.Description())
+ assert.NotEmpty(t, rule.Link())
+ assert.Equal(t, validation.SeverityWarning, rule.DefaultSeverity())
+ assert.Nil(t, rule.Versions())
+}
diff --git a/openapi/linter/rules/owasp_integer_format.go b/openapi/linter/rules/owasp_integer_format.go
new file mode 100644
index 00000000..e907be4b
--- /dev/null
+++ b/openapi/linter/rules/owasp_integer_format.go
@@ -0,0 +1,85 @@
+package rules
+
+import (
+ "context"
+ "errors"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/validation"
+)
+
+const RuleOwaspIntegerFormat = "owasp-integer-format"
+
+type OwaspIntegerFormatRule struct{}
+
+func (r *OwaspIntegerFormatRule) ID() string {
+ return RuleOwaspIntegerFormat
+}
+func (r *OwaspIntegerFormatRule) Category() string {
+ return CategorySecurity
+}
+func (r *OwaspIntegerFormatRule) Description() string {
+ return "Integer schemas must specify a `format` of `int32` or `int64` to define the expected size and range. Explicit integer formats prevent overflow vulnerabilities and ensure clients and servers agree on numeric boundaries."
+}
+func (r *OwaspIntegerFormatRule) Summary() string {
+ return "Integer schemas must specify `int32` or `int64` format."
+}
+func (r *OwaspIntegerFormatRule) HowToFix() string {
+ return "Set integer schema `format` to `int32` or `int64` based on the expected range."
+}
+func (r *OwaspIntegerFormatRule) Link() string {
+ return "https://github.com/speakeasy-api/openapi/blob/main/openapi/linter/README.md#owasp-integer-format"
+}
+func (r *OwaspIntegerFormatRule) DefaultSeverity() validation.Severity {
+ return validation.SeverityError
+}
+func (r *OwaspIntegerFormatRule) Versions() []string {
+ return []string{"3.0", "3.1"}
+}
+
+func (r *OwaspIntegerFormatRule) Run(ctx context.Context, docInfo *linter.DocumentInfo[*openapi.OpenAPI], config *linter.RuleConfig) []error {
+ if docInfo == nil || docInfo.Document == nil || docInfo.Index == nil {
+ return nil
+ }
+
+ var errs []error
+
+ // Check all schemas in the document
+ for _, schemaNode := range docInfo.Index.GetAllSchemas() {
+ refSchema := schemaNode.Node
+ schema := refSchema.GetSchema()
+ if schema == nil {
+ continue
+ }
+
+ // Check if type contains "integer"
+ types := schema.GetType()
+ hasIntegerType := false
+ for _, typ := range types {
+ if typ == "integer" {
+ hasIntegerType = true
+ break
+ }
+ }
+
+ if !hasIntegerType {
+ continue
+ }
+
+ // Check if format is int32 or int64
+ format := schema.GetFormat()
+ if format != "int32" && format != "int64" {
+ if rootNode := refSchema.GetRootNode(); rootNode != nil {
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleOwaspIntegerFormat,
+ errors.New("schema of type `integer` must specify `format` as `int32` or `int64`"),
+ rootNode,
+ ))
+ }
+ }
+ }
+
+ return errs
+}
diff --git a/openapi/linter/rules/owasp_integer_format_test.go b/openapi/linter/rules/owasp_integer_format_test.go
new file mode 100644
index 00000000..24fd2be6
--- /dev/null
+++ b/openapi/linter/rules/owasp_integer_format_test.go
@@ -0,0 +1,217 @@
+package rules_test
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/openapi/linter/rules"
+ "github.com/speakeasy-api/openapi/references"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestOwaspIntegerFormatRule_ValidCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "integer with int32 format",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Counter:
+ type: integer
+ format: int32
+paths: {}
+`,
+ },
+ {
+ name: "integer with int64 format",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ BigCounter:
+ type: integer
+ format: int64
+paths: {}
+`,
+ },
+ {
+ name: "non-integer type without format is ok",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Name:
+ type: string
+paths: {}
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspIntegerFormatRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+ assert.Empty(t, errs)
+ })
+ }
+}
+
+func TestOwaspIntegerFormatRule_Violations(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ expectedCount int
+ }{
+ {
+ name: "integer without format",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Counter:
+ type: integer
+paths: {}
+`,
+ expectedCount: 1,
+ },
+ {
+ name: "integer with invalid format",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Counter:
+ type: integer
+ format: int16
+paths: {}
+`,
+ expectedCount: 1,
+ },
+ {
+ name: "multiple integers without proper format",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ User:
+ type: object
+ properties:
+ age:
+ type: integer
+ count:
+ type: integer
+ format: uint32
+paths: {}
+`,
+ expectedCount: 2,
+ },
+ {
+ name: "inline integer parameter without format",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ parameters:
+ - name: limit
+ in: query
+ schema:
+ type: integer
+ responses:
+ '200':
+ description: Success
+`,
+ expectedCount: 1,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspIntegerFormatRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ require.Len(t, errs, tt.expectedCount)
+ for _, err := range errs {
+ assert.Contains(t, err.Error(), "must specify `format` as `int32` or `int64`")
+ }
+ })
+ }
+}
+
+func TestOwaspIntegerFormatRule_RuleMetadata(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.OwaspIntegerFormatRule{}
+
+ assert.Equal(t, "owasp-integer-format", rule.ID())
+ assert.Equal(t, rules.CategorySecurity, rule.Category())
+ assert.NotEmpty(t, rule.Description())
+ assert.NotEmpty(t, rule.Link())
+ assert.Equal(t, validation.SeverityError, rule.DefaultSeverity())
+ assert.Equal(t, []string{"3.0", "3.1"}, rule.Versions())
+}
diff --git a/openapi/linter/rules/owasp_integer_limit.go b/openapi/linter/rules/owasp_integer_limit.go
new file mode 100644
index 00000000..331304db
--- /dev/null
+++ b/openapi/linter/rules/owasp_integer_limit.go
@@ -0,0 +1,98 @@
+package rules
+
+import (
+ "context"
+ "errors"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/validation"
+)
+
+const RuleOwaspIntegerLimit = "owasp-integer-limit"
+
+type OwaspIntegerLimitRule struct{}
+
+func (r *OwaspIntegerLimitRule) ID() string {
+ return RuleOwaspIntegerLimit
+}
+func (r *OwaspIntegerLimitRule) Category() string {
+ return CategorySecurity
+}
+func (r *OwaspIntegerLimitRule) Description() string {
+ return "Integer schemas must specify `minimum` and `maximum` values (or exclusive variants) to prevent unbounded inputs. Without numeric limits, APIs are vulnerable to overflow attacks and unexpected behavior from extreme values."
+}
+func (r *OwaspIntegerLimitRule) Summary() string {
+ return "Integer schemas must specify `minimum` and `maximum` values."
+}
+func (r *OwaspIntegerLimitRule) HowToFix() string {
+ return "Add `minimum` and `maximum` (or `exclusiveMinimum`/`exclusiveMaximum`) values to integer schemas."
+}
+func (r *OwaspIntegerLimitRule) Link() string {
+ return "https://github.com/speakeasy-api/openapi/blob/main/openapi/linter/README.md#owasp-integer-limit"
+}
+func (r *OwaspIntegerLimitRule) DefaultSeverity() validation.Severity {
+ return validation.SeverityError
+}
+func (r *OwaspIntegerLimitRule) Versions() []string {
+ return []string{"3.0", "3.1"}
+}
+
+func (r *OwaspIntegerLimitRule) Run(ctx context.Context, docInfo *linter.DocumentInfo[*openapi.OpenAPI], config *linter.RuleConfig) []error {
+ if docInfo == nil || docInfo.Document == nil || docInfo.Index == nil {
+ return nil
+ }
+
+ var errs []error
+
+ // Check all schemas in the document
+ for _, schemaNode := range docInfo.Index.GetAllSchemas() {
+ refSchema := schemaNode.Node
+ schema := refSchema.GetSchema()
+ if schema == nil {
+ continue
+ }
+
+ // Check if type contains "integer"
+ types := schema.GetType()
+ hasIntegerType := false
+ for _, typ := range types {
+ if typ == "integer" {
+ hasIntegerType = true
+ break
+ }
+ }
+
+ if !hasIntegerType {
+ continue
+ }
+
+ // Check if schema has appropriate minimum and maximum constraints
+ minimum := schema.GetMinimum()
+ maximum := schema.GetMaximum()
+ exclusiveMinimum := schema.GetExclusiveMinimum()
+ exclusiveMaximum := schema.GetExclusiveMaximum()
+
+ // Valid combinations:
+ // 1. minimum AND maximum
+ // 2. minimum AND exclusiveMaximum
+ // 3. exclusiveMinimum AND maximum
+ // 4. exclusiveMinimum AND exclusiveMaximum
+
+ hasMin := minimum != nil || exclusiveMinimum != nil
+ hasMax := maximum != nil || exclusiveMaximum != nil
+
+ if !hasMin || !hasMax {
+ if rootNode := refSchema.GetRootNode(); rootNode != nil {
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleOwaspIntegerLimit,
+ errors.New("schema of type `integer` must specify `minimum` and `maximum` (or `exclusiveMinimum` and `exclusiveMaximum`)"),
+ rootNode,
+ ))
+ }
+ }
+ }
+
+ return errs
+}
diff --git a/openapi/linter/rules/owasp_integer_limit_test.go b/openapi/linter/rules/owasp_integer_limit_test.go
new file mode 100644
index 00000000..cde65544
--- /dev/null
+++ b/openapi/linter/rules/owasp_integer_limit_test.go
@@ -0,0 +1,289 @@
+package rules_test
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/openapi/linter/rules"
+ "github.com/speakeasy-api/openapi/references"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestOwaspIntegerLimitRule_ValidCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "integer with minimum and maximum",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Age:
+ type: integer
+ format: int32
+ minimum: 0
+ maximum: 120
+paths: {}
+`,
+ },
+ {
+ name: "integer with minimum and exclusiveMaximum",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Counter:
+ type: integer
+ format: int32
+ minimum: 0
+ exclusiveMaximum: 100
+paths: {}
+`,
+ },
+ {
+ name: "integer with exclusiveMinimum and maximum",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Counter:
+ type: integer
+ format: int32
+ exclusiveMinimum: 0
+ maximum: 100
+paths: {}
+`,
+ },
+ {
+ name: "integer with exclusiveMinimum and exclusiveMaximum",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Counter:
+ type: integer
+ format: int32
+ exclusiveMinimum: 0
+ exclusiveMaximum: 100
+paths: {}
+`,
+ },
+ {
+ name: "non-integer type without limits is ok",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Name:
+ type: string
+paths: {}
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspIntegerLimitRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+ assert.Empty(t, errs)
+ })
+ }
+}
+
+func TestOwaspIntegerLimitRule_Violations(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ expectedCount int
+ }{
+ {
+ name: "integer without any limits",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Counter:
+ type: integer
+ format: int32
+paths: {}
+`,
+ expectedCount: 1,
+ },
+ {
+ name: "integer with only minimum",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Counter:
+ type: integer
+ format: int32
+ minimum: 0
+paths: {}
+`,
+ expectedCount: 1,
+ },
+ {
+ name: "integer with only maximum",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Counter:
+ type: integer
+ format: int32
+ maximum: 100
+paths: {}
+`,
+ expectedCount: 1,
+ },
+ {
+ name: "integer with only exclusiveMinimum",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Counter:
+ type: integer
+ format: int32
+ exclusiveMinimum: 0
+paths: {}
+`,
+ expectedCount: 1,
+ },
+ {
+ name: "integer with only exclusiveMaximum",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Counter:
+ type: integer
+ format: int32
+ exclusiveMaximum: 100
+paths: {}
+`,
+ expectedCount: 1,
+ },
+ {
+ name: "multiple integers without proper limits",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ User:
+ type: object
+ properties:
+ age:
+ type: integer
+ format: int32
+ count:
+ type: integer
+ format: int32
+ minimum: 0
+paths: {}
+`,
+ expectedCount: 2,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspIntegerLimitRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ require.Len(t, errs, tt.expectedCount)
+ for _, err := range errs {
+ assert.Contains(t, err.Error(), "must specify `minimum` and `maximum`")
+ }
+ })
+ }
+}
+
+func TestOwaspIntegerLimitRule_RuleMetadata(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.OwaspIntegerLimitRule{}
+
+ assert.Equal(t, "owasp-integer-limit", rule.ID())
+ assert.Equal(t, rules.CategorySecurity, rule.Category())
+ assert.NotEmpty(t, rule.Description())
+ assert.NotEmpty(t, rule.Link())
+ assert.Equal(t, validation.SeverityError, rule.DefaultSeverity())
+ assert.Equal(t, []string{"3.0", "3.1"}, rule.Versions())
+}
diff --git a/openapi/linter/rules/owasp_jwt_best_practices.go b/openapi/linter/rules/owasp_jwt_best_practices.go
new file mode 100644
index 00000000..929b6c5b
--- /dev/null
+++ b/openapi/linter/rules/owasp_jwt_best_practices.go
@@ -0,0 +1,107 @@
+package rules
+
+import (
+ "context"
+ "fmt"
+ "strings"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/speakeasy-api/openapi/yml"
+)
+
+const RuleOwaspJWTBestPractices = "owasp-jwt-best-practices"
+
+type OwaspJWTBestPracticesRule struct{}
+
+func (r *OwaspJWTBestPracticesRule) ID() string {
+ return RuleOwaspJWTBestPractices
+}
+func (r *OwaspJWTBestPracticesRule) Category() string {
+ return CategorySecurity
+}
+func (r *OwaspJWTBestPracticesRule) Description() string {
+ return "Security schemes using OAuth2 or JWT must explicitly declare support for RFC8725 (JWT Best Current Practices) in the description. RFC8725 compliance ensures JWTs are validated properly and protected against common attacks like algorithm confusion."
+}
+func (r *OwaspJWTBestPracticesRule) Summary() string {
+ return "OAuth2/JWT schemes must mention RFC8725 in their description."
+}
+func (r *OwaspJWTBestPracticesRule) HowToFix() string {
+ return "Update OAuth2/JWT security scheme descriptions to mention RFC8725 compliance."
+}
+func (r *OwaspJWTBestPracticesRule) Link() string {
+ return "https://github.com/speakeasy-api/openapi/blob/main/openapi/linter/README.md#owasp-jwt-best-practices"
+}
+func (r *OwaspJWTBestPracticesRule) DefaultSeverity() validation.Severity {
+ return validation.SeverityError
+}
+func (r *OwaspJWTBestPracticesRule) Versions() []string {
+ return []string{"3.0", "3.1"} // OAS3 only
+}
+
+func (r *OwaspJWTBestPracticesRule) Run(ctx context.Context, docInfo *linter.DocumentInfo[*openapi.OpenAPI], config *linter.RuleConfig) []error {
+ if docInfo == nil || docInfo.Document == nil {
+ return nil
+ }
+
+ var errs []error
+
+ doc := docInfo.Document
+ components := doc.GetComponents()
+ if components == nil {
+ return nil
+ }
+
+ securitySchemes := components.GetSecuritySchemes()
+ if securitySchemes == nil || securitySchemes.Len() == 0 {
+ return nil
+ }
+
+ // Check each security scheme
+ for name, scheme := range securitySchemes.All() {
+ schemeObj := scheme.GetObject()
+ if schemeObj == nil {
+ continue
+ }
+
+ schemeType := schemeObj.GetType()
+ bearerFormat := schemeObj.GetBearerFormat()
+
+ // Check if this is OAuth2 or JWT bearer
+ isOAuth2 := schemeType == "oauth2"
+ isJWT := strings.ToLower(bearerFormat) == "jwt"
+
+ if !isOAuth2 && !isJWT {
+ continue
+ }
+
+ // Check if description contains RFC8725
+ description := schemeObj.GetDescription()
+ if !strings.Contains(description, "RFC8725") {
+ // Try to get the description node for better error location
+ rootNode := scheme.GetRootNode()
+ if rootNode != nil {
+ _, descNode, found := yml.GetMapElementNodes(ctx, rootNode, "description")
+ if found && descNode != nil {
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleOwaspJWTBestPractices,
+ fmt.Errorf("security scheme `%s` must explicitly declare support for RFC8725 in the description", name),
+ descNode,
+ ))
+ } else {
+ // No description field - report on the scheme itself
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleOwaspJWTBestPractices,
+ fmt.Errorf("security scheme `%s` must explicitly declare support for RFC8725 in the description", name),
+ rootNode,
+ ))
+ }
+ }
+ }
+ }
+
+ return errs
+}
diff --git a/openapi/linter/rules/owasp_jwt_best_practices_test.go b/openapi/linter/rules/owasp_jwt_best_practices_test.go
new file mode 100644
index 00000000..3bc7b565
--- /dev/null
+++ b/openapi/linter/rules/owasp_jwt_best_practices_test.go
@@ -0,0 +1,300 @@
+package rules_test
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/openapi/linter/rules"
+ "github.com/speakeasy-api/openapi/references"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestOwaspJWTBestPracticesRule_ValidCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "oauth2 with RFC8725 in description",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ securitySchemes:
+ oauth:
+ type: oauth2
+ description: OAuth2 authentication supporting RFC8725
+ flows:
+ implicit:
+ authorizationUrl: https://example.com/oauth
+ scopes:
+ read: Read access
+paths: {}
+`,
+ },
+ {
+ name: "jwt bearer with RFC8725 in description",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ securitySchemes:
+ bearer:
+ type: http
+ scheme: bearer
+ bearerFormat: JWT
+ description: JWT bearer token supporting RFC8725
+paths: {}
+`,
+ },
+ {
+ name: "non-jwt bearer without RFC8725 is ok",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ securitySchemes:
+ bearer:
+ type: http
+ scheme: bearer
+ description: Bearer token authentication
+paths: {}
+`,
+ },
+ {
+ name: "api key without RFC8725 is ok",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ securitySchemes:
+ apiKey:
+ type: apiKey
+ in: header
+ name: X-API-Key
+ description: API key authentication
+paths: {}
+`,
+ },
+ {
+ name: "no security schemes is ok",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths: {}
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspJWTBestPracticesRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+ assert.Empty(t, errs)
+ })
+ }
+}
+
+func TestOwaspJWTBestPracticesRule_Violations(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ expectedCount int
+ expectedText string
+ }{
+ {
+ name: "oauth2 without RFC8725",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ securitySchemes:
+ oauth:
+ type: oauth2
+ description: OAuth2 authentication
+ flows:
+ implicit:
+ authorizationUrl: https://example.com/oauth
+ scopes:
+ read: Read access
+paths: {}
+`,
+ expectedCount: 1,
+ expectedText: "oauth",
+ },
+ {
+ name: "jwt bearer without RFC8725",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ securitySchemes:
+ bearer:
+ type: http
+ scheme: bearer
+ bearerFormat: JWT
+ description: JWT bearer token
+paths: {}
+`,
+ expectedCount: 1,
+ expectedText: "bearer",
+ },
+ {
+ name: "oauth2 with no description",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ securitySchemes:
+ oauth:
+ type: oauth2
+ flows:
+ implicit:
+ authorizationUrl: https://example.com/oauth
+ scopes:
+ read: Read access
+paths: {}
+`,
+ expectedCount: 1,
+ expectedText: "RFC8725",
+ },
+ {
+ name: "multiple jwt schemes without RFC8725",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ securitySchemes:
+ oauth:
+ type: oauth2
+ description: OAuth2 authentication
+ flows:
+ implicit:
+ authorizationUrl: https://example.com/oauth
+ scopes:
+ read: Read access
+ bearer:
+ type: http
+ scheme: bearer
+ bearerFormat: JWT
+ description: JWT bearer token
+paths: {}
+`,
+ expectedCount: 2,
+ expectedText: "",
+ },
+ {
+ name: "mixed schemes one with one without RFC8725",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ securitySchemes:
+ oauth:
+ type: oauth2
+ description: OAuth2 authentication supporting RFC8725
+ flows:
+ implicit:
+ authorizationUrl: https://example.com/oauth
+ scopes:
+ read: Read access
+ bearer:
+ type: http
+ scheme: bearer
+ bearerFormat: JWT
+ description: JWT bearer token
+paths: {}
+`,
+ expectedCount: 1,
+ expectedText: "bearer",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspJWTBestPracticesRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ require.Len(t, errs, tt.expectedCount)
+ for _, err := range errs {
+ assert.Contains(t, err.Error(), "RFC8725")
+ if tt.expectedText != "" {
+ assert.Contains(t, err.Error(), tt.expectedText)
+ }
+ }
+ })
+ }
+}
+
+func TestOwaspJWTBestPracticesRule_RuleMetadata(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.OwaspJWTBestPracticesRule{}
+
+ assert.Equal(t, "owasp-jwt-best-practices", rule.ID())
+ assert.Equal(t, rules.CategorySecurity, rule.Category())
+ assert.NotEmpty(t, rule.Description())
+ assert.NotEmpty(t, rule.Link())
+ assert.Equal(t, validation.SeverityError, rule.DefaultSeverity())
+ assert.Equal(t, []string{"3.0", "3.1"}, rule.Versions())
+}
diff --git a/openapi/linter/rules/owasp_no_additional_properties.go b/openapi/linter/rules/owasp_no_additional_properties.go
new file mode 100644
index 00000000..cfa972e8
--- /dev/null
+++ b/openapi/linter/rules/owasp_no_additional_properties.go
@@ -0,0 +1,107 @@
+package rules
+
+import (
+ "context"
+ "errors"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/validation"
+)
+
+const RuleOwaspNoAdditionalProperties = "owasp-no-additional-properties"
+
+type OwaspNoAdditionalPropertiesRule struct{}
+
+func (r *OwaspNoAdditionalPropertiesRule) ID() string {
+ return RuleOwaspNoAdditionalProperties
+}
+func (r *OwaspNoAdditionalPropertiesRule) Category() string {
+ return CategorySecurity
+}
+func (r *OwaspNoAdditionalPropertiesRule) Description() string {
+ return "Object schemas must not allow arbitrary additional properties (set additionalProperties to false or omit it). Allowing unexpected properties can lead to mass assignment vulnerabilities where attackers inject unintended fields."
+}
+func (r *OwaspNoAdditionalPropertiesRule) Summary() string {
+ return "Object schemas should not allow additional properties."
+}
+func (r *OwaspNoAdditionalPropertiesRule) HowToFix() string {
+ return "Set additionalProperties to false or remove it from object schemas."
+}
+func (r *OwaspNoAdditionalPropertiesRule) Link() string {
+ return "https://github.com/speakeasy-api/openapi/blob/main/openapi/linter/README.md#owasp-no-additional-properties"
+}
+func (r *OwaspNoAdditionalPropertiesRule) DefaultSeverity() validation.Severity {
+ return validation.SeverityError
+}
+func (r *OwaspNoAdditionalPropertiesRule) Versions() []string {
+ return []string{"3.0", "3.1"}
+}
+
+func (r *OwaspNoAdditionalPropertiesRule) Run(ctx context.Context, docInfo *linter.DocumentInfo[*openapi.OpenAPI], config *linter.RuleConfig) []error {
+ if docInfo == nil || docInfo.Document == nil || docInfo.Index == nil {
+ return nil
+ }
+
+ var errs []error
+
+ // Check all schemas in the document
+ for _, schemaNode := range docInfo.Index.GetAllSchemas() {
+ refSchema := schemaNode.Node
+ schema := refSchema.GetSchema()
+ if schema == nil {
+ continue
+ }
+
+ // Check if type contains "object"
+ types := schema.GetType()
+ hasObjectType := false
+ for _, typ := range types {
+ if typ == "object" {
+ hasObjectType = true
+ break
+ }
+ }
+
+ if !hasObjectType {
+ continue
+ }
+
+ // Check additionalProperties
+ additionalProps := schema.GetAdditionalProperties()
+ if additionalProps == nil {
+ // Not set - this is OK
+ continue
+ }
+
+ // additionalProperties can be either a boolean or a schema
+ // If it's a boolean, check if it's true (violation)
+ // If it's a schema, that's also a violation
+ isViolation := false
+
+ if additionalProps.IsBool() {
+ // It's a boolean value
+ boolVal := additionalProps.GetBool()
+ if boolVal != nil && *boolVal {
+ // additionalProperties: true is a violation
+ isViolation = true
+ }
+ } else {
+ // It's a schema object - this is a violation
+ isViolation = true
+ }
+
+ if isViolation {
+ if rootNode := refSchema.GetRootNode(); rootNode != nil {
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleOwaspNoAdditionalProperties,
+ errors.New("additionalProperties should not be set to true or define a schema - set to false or omit it"),
+ rootNode,
+ ))
+ }
+ }
+ }
+
+ return errs
+}
diff --git a/openapi/linter/rules/owasp_no_additional_properties_test.go b/openapi/linter/rules/owasp_no_additional_properties_test.go
new file mode 100644
index 00000000..651ec773
--- /dev/null
+++ b/openapi/linter/rules/owasp_no_additional_properties_test.go
@@ -0,0 +1,223 @@
+package rules_test
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/openapi/linter/rules"
+ "github.com/speakeasy-api/openapi/references"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestOwaspNoAdditionalPropertiesRule_ValidCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "object without additionalProperties set",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ User:
+ type: object
+ properties:
+ name:
+ type: string
+ maxLength: 100
+paths: {}
+`,
+ },
+ {
+ name: "object with additionalProperties false",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ User:
+ type: object
+ properties:
+ name:
+ type: string
+ maxLength: 100
+ additionalProperties: false
+paths: {}
+`,
+ },
+ {
+ name: "non-object type with additionalProperties is ok",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Name:
+ type: string
+ maxLength: 100
+paths: {}
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspNoAdditionalPropertiesRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+ assert.Empty(t, errs)
+ })
+ }
+}
+
+func TestOwaspNoAdditionalPropertiesRule_Violations(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ expectedCount int
+ }{
+ {
+ name: "object with additionalProperties true",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ User:
+ type: object
+ properties:
+ name:
+ type: string
+ maxLength: 100
+ additionalProperties: true
+paths: {}
+`,
+ expectedCount: 1,
+ },
+ {
+ name: "object with additionalProperties schema",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ User:
+ type: object
+ properties:
+ name:
+ type: string
+ maxLength: 100
+ additionalProperties:
+ type: string
+ maxLength: 50
+paths: {}
+`,
+ expectedCount: 1,
+ },
+ {
+ name: "multiple objects with additionalProperties violations",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ User:
+ type: object
+ properties:
+ name:
+ type: string
+ maxLength: 100
+ additionalProperties: true
+ Config:
+ type: object
+ properties:
+ setting:
+ type: string
+ maxLength: 50
+ additionalProperties:
+ type: string
+ maxLength: 100
+paths: {}
+`,
+ expectedCount: 2,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspNoAdditionalPropertiesRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ require.Len(t, errs, tt.expectedCount)
+ for _, err := range errs {
+ assert.Contains(t, err.Error(), "additionalProperties")
+ }
+ })
+ }
+}
+
+func TestOwaspNoAdditionalPropertiesRule_RuleMetadata(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.OwaspNoAdditionalPropertiesRule{}
+
+ assert.Equal(t, "owasp-no-additional-properties", rule.ID())
+ assert.Equal(t, rules.CategorySecurity, rule.Category())
+ assert.NotEmpty(t, rule.Description())
+ assert.NotEmpty(t, rule.Link())
+ assert.Equal(t, validation.SeverityError, rule.DefaultSeverity())
+ assert.Equal(t, []string{"3.0", "3.1"}, rule.Versions())
+}
diff --git a/openapi/linter/rules/owasp_no_api_keys_in_url.go b/openapi/linter/rules/owasp_no_api_keys_in_url.go
new file mode 100644
index 00000000..1c170ba6
--- /dev/null
+++ b/openapi/linter/rules/owasp_no_api_keys_in_url.go
@@ -0,0 +1,96 @@
+package rules
+
+import (
+ "context"
+ "fmt"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/speakeasy-api/openapi/yml"
+)
+
+//nolint:gosec
+const RuleOwaspNoAPIKeysInURL = "owasp-no-api-keys-in-url"
+
+type OwaspNoAPIKeysInURLRule struct{}
+
+func (r *OwaspNoAPIKeysInURLRule) ID() string { return RuleOwaspNoAPIKeysInURL }
+func (r *OwaspNoAPIKeysInURLRule) Category() string { return CategorySecurity }
+func (r *OwaspNoAPIKeysInURLRule) Description() string {
+ return "API keys must not be passed via URL parameters (query or path) as they are logged and cached. URL-based API keys appear in browser history, server logs, and proxy caches, creating security exposure."
+}
+func (r *OwaspNoAPIKeysInURLRule) Summary() string {
+ return "API keys must not be passed via URL parameters."
+}
+func (r *OwaspNoAPIKeysInURLRule) HowToFix() string {
+ return "Move API keys to header-based authentication instead of query or path parameters."
+}
+func (r *OwaspNoAPIKeysInURLRule) Link() string {
+ return "https://github.com/speakeasy-api/openapi/blob/main/openapi/linter/README.md#owasp-no-api-keys-in-url"
+}
+func (r *OwaspNoAPIKeysInURLRule) DefaultSeverity() validation.Severity {
+ return validation.SeverityError
+}
+func (r *OwaspNoAPIKeysInURLRule) Versions() []string {
+ return nil // Applies to all OpenAPI versions
+}
+
+func (r *OwaspNoAPIKeysInURLRule) Run(ctx context.Context, docInfo *linter.DocumentInfo[*openapi.OpenAPI], config *linter.RuleConfig) []error {
+ if docInfo == nil || docInfo.Document == nil {
+ return nil
+ }
+
+ doc := docInfo.Document
+ components := doc.GetComponents()
+ if components == nil {
+ return nil
+ }
+
+ securitySchemes := components.GetSecuritySchemes()
+ if securitySchemes == nil {
+ return nil
+ }
+
+ var errs []error
+
+ // Iterate through all security schemes
+ for name, scheme := range securitySchemes.All() {
+ if scheme == nil {
+ continue
+ }
+
+ // Get the security scheme object
+ secScheme := scheme.GetObject()
+ if secScheme == nil {
+ continue
+ }
+
+ // Check if this is an API key type security scheme
+ schemeType := secScheme.GetType()
+ if schemeType != "apiKey" {
+ continue
+ }
+
+ // Get the location where the API key is passed
+ location := secScheme.GetIn()
+
+ // Check if it's in query or path (both are insecure for API keys)
+ if location == "query" || location == "path" {
+ // Get the root node to find the "in" key
+ if rootNode := secScheme.GetRootNode(); rootNode != nil {
+ _, inValueNode, found := yml.GetMapElementNodes(ctx, rootNode, "in")
+ if found && inValueNode != nil {
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleOwaspNoAPIKeysInURL,
+ fmt.Errorf("security scheme `%s` passes API key via URL `%s` parameter - use header instead for security", name, location),
+ inValueNode,
+ ))
+ }
+ }
+ }
+ }
+
+ return errs
+}
diff --git a/openapi/linter/rules/owasp_no_api_keys_in_url_test.go b/openapi/linter/rules/owasp_no_api_keys_in_url_test.go
new file mode 100644
index 00000000..ffcc8b8d
--- /dev/null
+++ b/openapi/linter/rules/owasp_no_api_keys_in_url_test.go
@@ -0,0 +1,242 @@
+package rules_test
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/openapi/linter/rules"
+ "github.com/speakeasy-api/openapi/references"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestOwaspNoAPIKeysInURLRule_ValidCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "api key in header",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ securitySchemes:
+ apiKey:
+ type: apiKey
+ in: header
+ name: X-API-Key
+paths: {}
+`,
+ },
+ {
+ name: "api key in cookie",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ securitySchemes:
+ apiKey:
+ type: apiKey
+ in: cookie
+ name: api_key
+paths: {}
+`,
+ },
+ {
+ name: "bearer authentication",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ securitySchemes:
+ bearerAuth:
+ type: http
+ scheme: bearer
+ bearerFormat: JWT
+paths: {}
+`,
+ },
+ {
+ name: "no security schemes",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths: {}
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspNoAPIKeysInURLRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+ assert.Empty(t, errs)
+ })
+ }
+}
+
+func TestOwaspNoAPIKeysInURLRule_Violations(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ expectedCount int
+ expectedText string
+ }{
+ {
+ name: "api key in query parameter",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ securitySchemes:
+ apiKey:
+ type: apiKey
+ in: query
+ name: api_key
+paths: {}
+`,
+ expectedCount: 1,
+ expectedText: "query",
+ },
+ {
+ name: "api key in path parameter",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ securitySchemes:
+ apiKey:
+ type: apiKey
+ in: path
+ name: api_key
+paths: {}
+`,
+ expectedCount: 1,
+ expectedText: "path",
+ },
+ {
+ name: "multiple api keys in url",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ securitySchemes:
+ apiKeyQuery:
+ type: apiKey
+ in: query
+ name: api_key
+ apiKeyPath:
+ type: apiKey
+ in: path
+ name: key
+paths: {}
+`,
+ expectedCount: 2,
+ expectedText: "",
+ },
+ {
+ name: "mixed secure and insecure api keys",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ securitySchemes:
+ apiKeyHeader:
+ type: apiKey
+ in: header
+ name: X-API-Key
+ apiKeyQuery:
+ type: apiKey
+ in: query
+ name: api_key
+paths: {}
+`,
+ expectedCount: 1,
+ expectedText: "query",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspNoAPIKeysInURLRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ require.Len(t, errs, tt.expectedCount)
+ for _, err := range errs {
+ assert.Contains(t, err.Error(), "API key via URL")
+ if tt.expectedText != "" {
+ assert.Contains(t, err.Error(), tt.expectedText)
+ }
+ }
+ })
+ }
+}
+
+func TestOwaspNoAPIKeysInURLRule_RuleMetadata(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.OwaspNoAPIKeysInURLRule{}
+
+ assert.Equal(t, "owasp-no-api-keys-in-url", rule.ID())
+ assert.Equal(t, rules.CategorySecurity, rule.Category())
+ assert.NotEmpty(t, rule.Description())
+ assert.NotEmpty(t, rule.Link())
+ assert.Equal(t, validation.SeverityError, rule.DefaultSeverity())
+ assert.Nil(t, rule.Versions())
+}
diff --git a/openapi/linter/rules/owasp_no_credentials_in_url.go b/openapi/linter/rules/owasp_no_credentials_in_url.go
new file mode 100644
index 00000000..3c12f071
--- /dev/null
+++ b/openapi/linter/rules/owasp_no_credentials_in_url.go
@@ -0,0 +1,95 @@
+package rules
+
+import (
+ "context"
+ "fmt"
+ "regexp"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/speakeasy-api/openapi/yml"
+)
+
+//nolint:gosec
+const RuleOwaspNoCredentialsInURL = "owasp-no-credentials-in-url"
+
+// credentialPattern matches parameter names that look like credentials
+// Matches: client_secret, clientsecret, token, access_token, accesstoken, refresh_token, refreshtoken,
+// id_token, idtoken, password, secret, api-key, apikey (case insensitive)
+var credentialPattern = regexp.MustCompile(`(?i)^.*(client_?secret|token|access_?token|refresh_?token|id_?token|password|secret|api-?key).*$`)
+
+type OwaspNoCredentialsInURLRule struct{}
+
+func (r *OwaspNoCredentialsInURLRule) ID() string { return RuleOwaspNoCredentialsInURL }
+func (r *OwaspNoCredentialsInURLRule) Category() string { return CategorySecurity }
+func (r *OwaspNoCredentialsInURLRule) Description() string {
+ return "URL parameters must not contain credentials like API keys, passwords, or secrets. Credentials in URLs are logged by servers, proxies, and browsers, creating significant security risks."
+}
+func (r *OwaspNoCredentialsInURLRule) Summary() string {
+ return "URL parameters must not contain credentials."
+}
+func (r *OwaspNoCredentialsInURLRule) HowToFix() string {
+ return "Remove credentials from URL parameters; use headers or request bodies instead."
+}
+func (r *OwaspNoCredentialsInURLRule) Link() string {
+ return "https://github.com/speakeasy-api/openapi/blob/main/openapi/linter/README.md#owasp-no-credentials-in-url"
+}
+func (r *OwaspNoCredentialsInURLRule) DefaultSeverity() validation.Severity {
+ return validation.SeverityError
+}
+func (r *OwaspNoCredentialsInURLRule) Versions() []string {
+ return nil // Applies to all OpenAPI versions
+}
+
+func (r *OwaspNoCredentialsInURLRule) Run(ctx context.Context, docInfo *linter.DocumentInfo[*openapi.OpenAPI], config *linter.RuleConfig) []error {
+ if docInfo == nil || docInfo.Document == nil || docInfo.Index == nil {
+ return nil
+ }
+
+ var errs []error
+
+ // Helper function to check a parameter
+ checkParameter := func(paramNode *openapi.IndexNode[*openapi.ReferencedParameter]) {
+ param := paramNode.Node
+ if param == nil {
+ return
+ }
+
+ // Get the parameter object
+ paramObj := param.GetObject()
+ if paramObj == nil {
+ return
+ }
+
+ // Only check query and path parameters (header and cookie are OK)
+ location := paramObj.GetIn()
+ if location != "query" && location != "path" {
+ return
+ }
+
+ // Check if the parameter name matches the credential pattern
+ paramName := paramObj.GetName()
+ if credentialPattern.MatchString(paramName) {
+ // Get the root node to find the name key
+ if rootNode := paramObj.GetRootNode(); rootNode != nil {
+ _, nameValueNode, found := yml.GetMapElementNodes(ctx, rootNode, "name")
+ if found && nameValueNode != nil {
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleOwaspNoCredentialsInURL,
+ fmt.Errorf("URL parameter `%s` appears to contain credentials - avoid passing sensitive data in URLs", paramName),
+ nameValueNode,
+ ))
+ }
+ }
+ }
+ }
+
+ // Check all parameters (inline, component, external, and references)
+ for _, paramNode := range docInfo.Index.GetAllParameters() {
+ checkParameter(paramNode)
+ }
+
+ return errs
+}
diff --git a/openapi/linter/rules/owasp_no_credentials_in_url_test.go b/openapi/linter/rules/owasp_no_credentials_in_url_test.go
new file mode 100644
index 00000000..4251a149
--- /dev/null
+++ b/openapi/linter/rules/owasp_no_credentials_in_url_test.go
@@ -0,0 +1,372 @@
+package rules_test
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/openapi/linter/rules"
+ "github.com/speakeasy-api/openapi/references"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestOwaspNoCredentialsInURLRule_ValidCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "safe query parameter names",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ parameters:
+ - name: userId
+ in: query
+ schema:
+ type: string
+ - name: filter
+ in: query
+ schema:
+ type: string
+ responses:
+ '200':
+ description: Success
+`,
+ },
+ {
+ name: "credentials in header parameters are allowed",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ parameters:
+ - name: api-key
+ in: header
+ schema:
+ type: string
+ - name: password
+ in: header
+ schema:
+ type: string
+ responses:
+ '200':
+ description: Success
+`,
+ },
+ {
+ name: "credentials in cookie parameters are allowed",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ parameters:
+ - name: token
+ in: cookie
+ schema:
+ type: string
+ responses:
+ '200':
+ description: Success
+`,
+ },
+ {
+ name: "no parameters",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspNoCredentialsInURLRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+ assert.Empty(t, errs)
+ })
+ }
+}
+
+func TestOwaspNoCredentialsInURLRule_Violations(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ expectedCount int
+ expectedParam string
+ }{
+ {
+ name: "token in query parameter",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ parameters:
+ - name: token
+ in: query
+ schema:
+ type: string
+ responses:
+ '200':
+ description: Success
+`,
+ expectedCount: 1,
+ expectedParam: "token",
+ },
+ {
+ name: "api-key in query parameter",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ parameters:
+ - name: api-key
+ in: query
+ schema:
+ type: string
+ responses:
+ '200':
+ description: Success
+`,
+ expectedCount: 1,
+ expectedParam: "api-key",
+ },
+ {
+ name: "password in path parameter",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /auth/{password}:
+ get:
+ parameters:
+ - name: password
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: Success
+`,
+ expectedCount: 1,
+ expectedParam: "password",
+ },
+ {
+ name: "client_secret in query parameter",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /oauth:
+ get:
+ parameters:
+ - name: client_secret
+ in: query
+ schema:
+ type: string
+ responses:
+ '200':
+ description: Success
+`,
+ expectedCount: 1,
+ expectedParam: "client_secret",
+ },
+ {
+ name: "access_token in query parameter",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /api:
+ get:
+ parameters:
+ - name: access_token
+ in: query
+ schema:
+ type: string
+ responses:
+ '200':
+ description: Success
+`,
+ expectedCount: 1,
+ expectedParam: "access_token",
+ },
+ {
+ name: "multiple credential parameters",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /api:
+ get:
+ parameters:
+ - name: token
+ in: query
+ schema:
+ type: string
+ - name: api-key
+ in: query
+ schema:
+ type: string
+ - name: userId
+ in: query
+ schema:
+ type: string
+ responses:
+ '200':
+ description: Success
+`,
+ expectedCount: 2,
+ expectedParam: "",
+ },
+ {
+ name: "case insensitive match - TOKEN",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /api:
+ get:
+ parameters:
+ - name: TOKEN
+ in: query
+ schema:
+ type: string
+ responses:
+ '200':
+ description: Success
+`,
+ expectedCount: 1,
+ expectedParam: "TOKEN",
+ },
+ {
+ name: "apikey without dash",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /api:
+ get:
+ parameters:
+ - name: apikey
+ in: query
+ schema:
+ type: string
+ responses:
+ '200':
+ description: Success
+`,
+ expectedCount: 1,
+ expectedParam: "apikey",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspNoCredentialsInURLRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ require.Len(t, errs, tt.expectedCount)
+ for _, err := range errs {
+ assert.Contains(t, err.Error(), "credentials")
+ if tt.expectedParam != "" {
+ assert.Contains(t, err.Error(), tt.expectedParam)
+ }
+ }
+ })
+ }
+}
+
+func TestOwaspNoCredentialsInURLRule_RuleMetadata(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.OwaspNoCredentialsInURLRule{}
+
+ assert.Equal(t, "owasp-no-credentials-in-url", rule.ID())
+ assert.Equal(t, rules.CategorySecurity, rule.Category())
+ assert.NotEmpty(t, rule.Description())
+ assert.NotEmpty(t, rule.Link())
+ assert.Equal(t, validation.SeverityError, rule.DefaultSeverity())
+ assert.Nil(t, rule.Versions())
+}
diff --git a/openapi/linter/rules/owasp_no_http_basic.go b/openapi/linter/rules/owasp_no_http_basic.go
new file mode 100644
index 00000000..680c4ebb
--- /dev/null
+++ b/openapi/linter/rules/owasp_no_http_basic.go
@@ -0,0 +1,97 @@
+package rules
+
+import (
+ "context"
+ "fmt"
+ "strings"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/speakeasy-api/openapi/yml"
+)
+
+const RuleOwaspNoHttpBasic = "owasp-no-http-basic"
+
+type OwaspNoHttpBasicRule struct{}
+
+func (r *OwaspNoHttpBasicRule) ID() string { return RuleOwaspNoHttpBasic }
+func (r *OwaspNoHttpBasicRule) Category() string { return CategorySecurity }
+func (r *OwaspNoHttpBasicRule) Description() string {
+ return "Security schemes must not use `HTTP Basic` authentication without additional security layers. `HTTP Basic` sends credentials in easily-decoded base64 encoding, making it vulnerable to interception without `HTTPS`."
+}
+func (r *OwaspNoHttpBasicRule) Summary() string {
+ return "Security schemes must not use `HTTP Basic` authentication."
+}
+func (r *OwaspNoHttpBasicRule) HowToFix() string {
+ return "Replace `HTTP Basic` schemes with more secure authentication (e.g., `OAuth 2.0` or `bearer` tokens)."
+}
+func (r *OwaspNoHttpBasicRule) Link() string {
+ return "https://github.com/speakeasy-api/openapi/blob/main/openapi/linter/README.md#owasp-no-http-basic"
+}
+func (r *OwaspNoHttpBasicRule) DefaultSeverity() validation.Severity {
+ return validation.SeverityError
+}
+func (r *OwaspNoHttpBasicRule) Versions() []string {
+ return nil // Applies to all OpenAPI versions
+}
+
+func (r *OwaspNoHttpBasicRule) Run(ctx context.Context, docInfo *linter.DocumentInfo[*openapi.OpenAPI], config *linter.RuleConfig) []error {
+ if docInfo == nil || docInfo.Document == nil {
+ return nil
+ }
+
+ doc := docInfo.Document
+ components := doc.GetComponents()
+ if components == nil {
+ return nil
+ }
+
+ securitySchemes := components.GetSecuritySchemes()
+ if securitySchemes == nil {
+ return nil
+ }
+
+ var errs []error
+
+ // Iterate through all security schemes
+ for name, scheme := range securitySchemes.All() {
+ if scheme == nil {
+ continue
+ }
+
+ // Get the security scheme object
+ secScheme := scheme.GetObject()
+ if secScheme == nil {
+ continue
+ }
+
+ // Check if this is an HTTP type security scheme
+ schemeType := secScheme.GetType()
+ if schemeType != "http" {
+ continue
+ }
+
+ // Get the scheme value (basic, bearer, etc.)
+ httpScheme := secScheme.GetScheme()
+ httpSchemeLower := strings.ToLower(httpScheme)
+
+ // Check if it's basic or negotiate (both insecure)
+ if httpSchemeLower == "basic" || httpSchemeLower == "negotiate" {
+ // Get the root node to find the scheme key
+ if rootNode := secScheme.GetRootNode(); rootNode != nil {
+ _, schemeValueNode, found := yml.GetMapElementNodes(ctx, rootNode, "scheme")
+ if found && schemeValueNode != nil {
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleOwaspNoHttpBasic,
+ fmt.Errorf("security scheme `%s` uses `HTTP` `%s` authentication, which is insecure - use `OAuth 2.0` or another secure method", name, httpScheme),
+ schemeValueNode,
+ ))
+ }
+ }
+ }
+ }
+
+ return errs
+}
diff --git a/openapi/linter/rules/owasp_no_http_basic_test.go b/openapi/linter/rules/owasp_no_http_basic_test.go
new file mode 100644
index 00000000..fbfa8d7a
--- /dev/null
+++ b/openapi/linter/rules/owasp_no_http_basic_test.go
@@ -0,0 +1,236 @@
+package rules_test
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/openapi/linter/rules"
+ "github.com/speakeasy-api/openapi/references"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestOwaspNoHttpBasicRule_ValidCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "bearer authentication",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ securitySchemes:
+ bearerAuth:
+ type: http
+ scheme: bearer
+ bearerFormat: JWT
+paths: {}
+`,
+ },
+ {
+ name: "oauth2 authentication",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ securitySchemes:
+ oauth:
+ type: oauth2
+ flows:
+ implicit:
+ authorizationUrl: https://example.com/oauth/authorize
+ scopes:
+ read: Read access
+paths: {}
+`,
+ },
+ {
+ name: "api key authentication",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ securitySchemes:
+ apiKey:
+ type: apiKey
+ in: header
+ name: X-API-Key
+paths: {}
+`,
+ },
+ {
+ name: "no security schemes",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths: {}
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspNoHttpBasicRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+ assert.Empty(t, errs)
+ })
+ }
+}
+
+func TestOwaspNoHttpBasicRule_Violations(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ expectedCount int
+ expectedText string
+ }{
+ {
+ name: "basic authentication",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ securitySchemes:
+ basicAuth:
+ type: http
+ scheme: basic
+paths: {}
+`,
+ expectedCount: 1,
+ expectedText: "basic",
+ },
+ {
+ name: "negotiate authentication",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ securitySchemes:
+ negotiateAuth:
+ type: http
+ scheme: negotiate
+paths: {}
+`,
+ expectedCount: 1,
+ expectedText: "negotiate",
+ },
+ {
+ name: "multiple insecure schemes",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ securitySchemes:
+ basicAuth:
+ type: http
+ scheme: basic
+ negotiateAuth:
+ type: http
+ scheme: negotiate
+paths: {}
+`,
+ expectedCount: 2,
+ expectedText: "",
+ },
+ {
+ name: "basic with uppercase",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ securitySchemes:
+ basicAuth:
+ type: http
+ scheme: Basic
+paths: {}
+`,
+ expectedCount: 1,
+ expectedText: "Basic",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspNoHttpBasicRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ require.Len(t, errs, tt.expectedCount)
+ for _, err := range errs {
+ assert.Contains(t, err.Error(), "insecure")
+ if tt.expectedText != "" {
+ assert.Contains(t, err.Error(), tt.expectedText)
+ }
+ }
+ })
+ }
+}
+
+func TestOwaspNoHttpBasicRule_RuleMetadata(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.OwaspNoHttpBasicRule{}
+
+ assert.Equal(t, "owasp-no-http-basic", rule.ID())
+ assert.Equal(t, rules.CategorySecurity, rule.Category())
+ assert.NotEmpty(t, rule.Description())
+ assert.NotEmpty(t, rule.Link())
+ assert.Equal(t, validation.SeverityError, rule.DefaultSeverity())
+ assert.Nil(t, rule.Versions())
+}
diff --git a/openapi/linter/rules/owasp_no_numeric_ids.go b/openapi/linter/rules/owasp_no_numeric_ids.go
new file mode 100644
index 00000000..6f562d47
--- /dev/null
+++ b/openapi/linter/rules/owasp_no_numeric_ids.go
@@ -0,0 +1,108 @@
+package rules
+
+import (
+ "context"
+ "fmt"
+ "strings"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/validation"
+)
+
+const RuleOwaspNoNumericIDs = "owasp-no-numeric-ids"
+
+type OwaspNoNumericIDsRule struct{}
+
+func (r *OwaspNoNumericIDsRule) ID() string {
+ return RuleOwaspNoNumericIDs
+}
+func (r *OwaspNoNumericIDsRule) Category() string {
+ return CategorySecurity
+}
+func (r *OwaspNoNumericIDsRule) Description() string {
+ return "Resource identifiers must use random values like UUIDs instead of sequential numeric IDs. Sequential IDs enable enumeration attacks where attackers can guess valid IDs and access unauthorized resources."
+}
+func (r *OwaspNoNumericIDsRule) Summary() string {
+ return "Resource identifiers should not use sequential numeric IDs."
+}
+func (r *OwaspNoNumericIDsRule) HowToFix() string {
+ return "Use non-sequential identifiers (e.g., UUIDs) for ID parameters."
+}
+func (r *OwaspNoNumericIDsRule) Link() string {
+ return "https://github.com/speakeasy-api/openapi/blob/main/openapi/linter/README.md#owasp-no-numeric-ids"
+}
+func (r *OwaspNoNumericIDsRule) DefaultSeverity() validation.Severity {
+ return validation.SeverityError
+}
+func (r *OwaspNoNumericIDsRule) Versions() []string {
+ return []string{"3.0", "3.1"} // OAS3 only
+}
+
+// isIDParameter checks if a parameter name is an ID field
+func isIDParameter(name string) bool {
+ lowerName := strings.ToLower(name)
+ return lowerName == "id" ||
+ strings.HasSuffix(lowerName, "_id") ||
+ strings.HasSuffix(lowerName, "-id") ||
+ strings.HasSuffix(lowerName, "id")
+}
+
+func (r *OwaspNoNumericIDsRule) Run(ctx context.Context, docInfo *linter.DocumentInfo[*openapi.OpenAPI], config *linter.RuleConfig) []error {
+ if docInfo == nil || docInfo.Document == nil || docInfo.Index == nil {
+ return nil
+ }
+
+ var errs []error
+
+ // Check all parameters (inline, component, external, and references)
+ for _, paramNode := range docInfo.Index.GetAllParameters() {
+ param := paramNode.Node
+ if param == nil {
+ continue
+ }
+
+ paramObj := param.GetObject()
+ if paramObj == nil {
+ continue
+ }
+
+ name := paramObj.GetName()
+ if !isIDParameter(name) {
+ continue
+ }
+
+ // Check if schema type is integer
+ jsonSchema := paramObj.GetSchema()
+ if jsonSchema == nil {
+ continue
+ }
+
+ schema := jsonSchema.GetSchema()
+ if schema == nil {
+ continue
+ }
+
+ types := schema.GetType()
+ if len(types) == 0 {
+ continue
+ }
+
+ // Check if type contains "integer"
+ for _, typ := range types {
+ if typ == "integer" {
+ if rootNode := jsonSchema.GetRootNode(); rootNode != nil {
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleOwaspNoNumericIDs,
+ fmt.Errorf("parameter `%s` uses integer type for ID - use random IDs like UUIDs instead of numeric IDs", name),
+ rootNode,
+ ))
+ }
+ break
+ }
+ }
+ }
+
+ return errs
+}
diff --git a/openapi/linter/rules/owasp_no_numeric_ids_test.go b/openapi/linter/rules/owasp_no_numeric_ids_test.go
new file mode 100644
index 00000000..efb8a7a7
--- /dev/null
+++ b/openapi/linter/rules/owasp_no_numeric_ids_test.go
@@ -0,0 +1,430 @@
+package rules_test
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/openapi/linter/rules"
+ "github.com/speakeasy-api/openapi/references"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestOwaspNoNumericIDsRule_ValidCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "id parameter with string type",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{id}:
+ get:
+ parameters:
+ - name: id
+ in: path
+ schema:
+ type: string
+ format: uuid
+ responses:
+ '200':
+ description: Success
+`,
+ },
+ {
+ name: "user_id parameter with string type",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{user_id}:
+ get:
+ parameters:
+ - name: user_id
+ in: path
+ schema:
+ type: string
+ responses:
+ '200':
+ description: Success
+`,
+ },
+ {
+ name: "non-id parameter with integer type is ok",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ parameters:
+ - name: limit
+ in: query
+ schema:
+ type: integer
+ - name: offset
+ in: query
+ schema:
+ type: integer
+ responses:
+ '200':
+ description: Success
+`,
+ },
+ {
+ name: "referenced id parameter with string type",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ parameters:
+ UserId:
+ name: user_id
+ in: path
+ schema:
+ type: string
+ format: uuid
+paths:
+ /users/{user_id}:
+ get:
+ parameters:
+ - $ref: '#/components/parameters/UserId'
+ responses:
+ '200':
+ description: Success
+`,
+ },
+ {
+ name: "id with object type",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{id}:
+ get:
+ parameters:
+ - name: id
+ in: path
+ schema:
+ type: object
+ responses:
+ '200':
+ description: Success
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspNoNumericIDsRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+ assert.Empty(t, errs)
+ })
+ }
+}
+
+func TestOwaspNoNumericIDsRule_Violations(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ expectedCount int
+ expectedText string
+ }{
+ {
+ name: "id parameter with integer type",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{id}:
+ get:
+ parameters:
+ - name: id
+ in: path
+ schema:
+ type: integer
+ responses:
+ '200':
+ description: Success
+`,
+ expectedCount: 1,
+ expectedText: "id",
+ },
+ {
+ name: "user_id parameter with integer type",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{user_id}:
+ get:
+ parameters:
+ - name: user_id
+ in: path
+ schema:
+ type: integer
+ responses:
+ '200':
+ description: Success
+`,
+ expectedCount: 1,
+ expectedText: "user_id",
+ },
+ {
+ name: "post-id parameter with integer type",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /posts/{post-id}:
+ get:
+ parameters:
+ - name: post-id
+ in: path
+ schema:
+ type: integer
+ responses:
+ '200':
+ description: Success
+`,
+ expectedCount: 1,
+ expectedText: "post-id",
+ },
+ {
+ name: "multiple id parameters with integer type",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{user_id}/posts/{post_id}:
+ get:
+ parameters:
+ - name: user_id
+ in: path
+ schema:
+ type: integer
+ - name: post_id
+ in: path
+ schema:
+ type: integer
+ responses:
+ '200':
+ description: Success
+`,
+ expectedCount: 2,
+ expectedText: "",
+ },
+ {
+ name: "component parameter id with integer type",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ parameters:
+ UserId:
+ name: id
+ in: path
+ schema:
+ type: integer
+paths:
+ /users/{id}:
+ get:
+ parameters:
+ - $ref: '#/components/parameters/UserId'
+ responses:
+ '200':
+ description: Success
+`,
+ expectedCount: 1,
+ expectedText: "id",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspNoNumericIDsRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ require.Len(t, errs, tt.expectedCount)
+ for _, err := range errs {
+ assert.Contains(t, err.Error(), "integer type for ID")
+ assert.Contains(t, err.Error(), "UUID")
+ if tt.expectedText != "" {
+ assert.Contains(t, err.Error(), tt.expectedText)
+ }
+ }
+ })
+ }
+}
+
+func TestOwaspNoNumericIDsRule_EdgeCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "productId ending with lowercase id",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /products/{productid}:
+ get:
+ parameters:
+ - name: productid
+ in: path
+ schema:
+ type: integer
+ responses:
+ '200':
+ description: Success
+`,
+ },
+ {
+ name: "parameter with no schema",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{id}:
+ get:
+ parameters:
+ - name: id
+ in: path
+ responses:
+ '200':
+ description: Success
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspNoNumericIDsRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ // Should not panic
+ errs := rule.Run(ctx, docInfo, config)
+ // productid ends with "id" so it should trigger the rule
+ if strings.Contains(tt.name, "productId") {
+ assert.Len(t, errs, 1)
+ assert.Contains(t, errs[0].Error(), "productid")
+ } else {
+ // parameter with no schema should not error
+ assert.Empty(t, errs)
+ }
+ })
+ }
+}
+
+func TestOwaspNoNumericIDsRule_NilInputs(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.OwaspNoNumericIDsRule{}
+ config := &linter.RuleConfig{}
+ ctx := t.Context()
+
+ // Test with nil docInfo
+ errs := rule.Run(ctx, nil, config)
+ assert.Empty(t, errs)
+
+ // Test with nil document
+ var nilDoc *openapi.OpenAPI
+ errs = rule.Run(ctx, linter.NewDocumentInfoWithIndex(nilDoc, "test.yaml", nil), config)
+ assert.Empty(t, errs)
+}
+
+func TestOwaspNoNumericIDsRule_RuleMetadata(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.OwaspNoNumericIDsRule{}
+
+ assert.Equal(t, "owasp-no-numeric-ids", rule.ID())
+ assert.Equal(t, rules.CategorySecurity, rule.Category())
+ assert.NotEmpty(t, rule.Description())
+ assert.NotEmpty(t, rule.Link())
+ assert.Equal(t, validation.SeverityError, rule.DefaultSeverity())
+ assert.Equal(t, []string{"3.0", "3.1"}, rule.Versions())
+}
diff --git a/openapi/linter/rules/owasp_protection_global_safe.go b/openapi/linter/rules/owasp_protection_global_safe.go
new file mode 100644
index 00000000..64faeac3
--- /dev/null
+++ b/openapi/linter/rules/owasp_protection_global_safe.go
@@ -0,0 +1,115 @@
+package rules
+
+import (
+ "context"
+ "fmt"
+ "strings"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/speakeasy-api/openapi/yml"
+)
+
+const RuleOwaspProtectionGlobalSafe = "owasp-protection-global-safe"
+
+// Safe HTTP methods that don't modify state
+var safeMethods = map[string]bool{
+ "get": true,
+ "head": true,
+}
+
+type OwaspProtectionGlobalSafeRule struct{}
+
+func (r *OwaspProtectionGlobalSafeRule) ID() string {
+ return RuleOwaspProtectionGlobalSafe
+}
+func (r *OwaspProtectionGlobalSafeRule) Category() string {
+ return CategorySecurity
+}
+func (r *OwaspProtectionGlobalSafeRule) Description() string {
+ return "Safe operations (GET, HEAD) should be protected by security schemes or explicitly marked as public. Unprotected read operations may expose sensitive data to unauthorized users."
+}
+func (r *OwaspProtectionGlobalSafeRule) Summary() string {
+ return "Safe operations should be protected or explicitly marked public."
+}
+func (r *OwaspProtectionGlobalSafeRule) HowToFix() string {
+ return "Add global security requirements or set operation-level security (empty array for public endpoints)."
+}
+func (r *OwaspProtectionGlobalSafeRule) Link() string {
+ return "https://github.com/speakeasy-api/openapi/blob/main/openapi/linter/README.md#owasp-protection-global-safe"
+}
+func (r *OwaspProtectionGlobalSafeRule) DefaultSeverity() validation.Severity {
+ return validation.SeverityHint
+}
+func (r *OwaspProtectionGlobalSafeRule) Versions() []string {
+ return []string{"3.0", "3.1"} // OAS3 only
+}
+
+func (r *OwaspProtectionGlobalSafeRule) Run(ctx context.Context, docInfo *linter.DocumentInfo[*openapi.OpenAPI], config *linter.RuleConfig) []error {
+ if docInfo == nil || docInfo.Document == nil || docInfo.Index == nil {
+ return nil
+ }
+
+ var errs []error
+
+ doc := docInfo.Document
+
+ // Check if there's a global security requirement
+ globalSecurity := doc.GetSecurity()
+ hasGlobalSecurity := len(globalSecurity) > 0
+
+ // Check all operations
+ for _, opNode := range docInfo.Index.Operations {
+ op := opNode.Node
+ if op == nil {
+ continue
+ }
+
+ // Get operation details
+ method := ""
+ path := ""
+ for _, loc := range opNode.Location {
+ switch openapi.GetParentType(loc) {
+ case "Paths":
+ if loc.ParentKey != nil {
+ path = *loc.ParentKey
+ }
+ case "PathItem":
+ if loc.ParentKey != nil {
+ method = *loc.ParentKey
+ }
+ }
+ }
+
+ // Only check safe methods
+ if !safeMethods[strings.ToLower(method)] {
+ continue
+ }
+
+ // Check if operation has explicit security field (even if empty array)
+ // security: [] means explicitly public and is allowed
+ rootNode := op.GetRootNode()
+ hasExplicitSecurity := false
+ if rootNode != nil {
+ _, _, found := yml.GetMapElementNodes(ctx, rootNode, "security")
+ hasExplicitSecurity = found
+ }
+
+ // Operation is protected if:
+ // 1. Has global security, OR
+ // 2. Has explicit operation-level security field (even if empty)
+ if !hasGlobalSecurity && !hasExplicitSecurity {
+ if rootNode != nil {
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleOwaspProtectionGlobalSafe,
+ fmt.Errorf("operation %s %s is not protected by any security scheme", method, path),
+ rootNode,
+ ))
+ }
+ }
+ }
+
+ return errs
+}
diff --git a/openapi/linter/rules/owasp_protection_global_safe_test.go b/openapi/linter/rules/owasp_protection_global_safe_test.go
new file mode 100644
index 00000000..2f3186f5
--- /dev/null
+++ b/openapi/linter/rules/owasp_protection_global_safe_test.go
@@ -0,0 +1,302 @@
+package rules_test
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/openapi/linter/rules"
+ "github.com/speakeasy-api/openapi/references"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestOwaspProtectionGlobalSafeRule_ValidCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "global security protects all operations",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+security:
+ - apiKey: []
+components:
+ securitySchemes:
+ apiKey:
+ type: apiKey
+ in: header
+ name: X-API-Key
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ head:
+ responses:
+ '200':
+ description: Success
+`,
+ },
+ {
+ name: "operation-level security",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ securitySchemes:
+ apiKey:
+ type: apiKey
+ in: header
+ name: X-API-Key
+paths:
+ /users:
+ get:
+ security:
+ - apiKey: []
+ responses:
+ '200':
+ description: Success
+`,
+ },
+ {
+ name: "empty security array allowed for safe methods",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /public:
+ get:
+ security: []
+ responses:
+ '200':
+ description: Success
+`,
+ },
+ {
+ name: "unsafe methods not checked by this rule",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ post:
+ responses:
+ '201':
+ description: Created
+`,
+ },
+ {
+ name: "mixed global and operation security",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+security:
+ - apiKey: []
+components:
+ securitySchemes:
+ apiKey:
+ type: apiKey
+ in: header
+ name: X-API-Key
+ oauth:
+ type: oauth2
+ flows:
+ implicit:
+ authorizationUrl: https://example.com/oauth
+ scopes:
+ read: Read access
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ head:
+ security:
+ - oauth: [read]
+ responses:
+ '200':
+ description: Success
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspProtectionGlobalSafeRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+ assert.Empty(t, errs)
+ })
+ }
+}
+
+func TestOwaspProtectionGlobalSafeRule_Violations(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ expectedCount int
+ expectedText string
+ }{
+ {
+ name: "get without security",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+`,
+ expectedCount: 1,
+ expectedText: "get",
+ },
+ {
+ name: "head without security",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ head:
+ responses:
+ '200':
+ description: Success
+`,
+ expectedCount: 1,
+ expectedText: "head",
+ },
+ {
+ name: "multiple safe operations without security",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ /posts:
+ get:
+ responses:
+ '200':
+ description: Success
+ head:
+ responses:
+ '200':
+ description: Success
+`,
+ expectedCount: 3,
+ expectedText: "",
+ },
+ {
+ name: "post is unsafe but get is not protected",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ post:
+ responses:
+ '201':
+ description: Created
+`,
+ expectedCount: 1,
+ expectedText: "get",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspProtectionGlobalSafeRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ require.Len(t, errs, tt.expectedCount)
+ for _, err := range errs {
+ assert.Contains(t, err.Error(), "not protected")
+ if tt.expectedText != "" {
+ assert.Contains(t, err.Error(), tt.expectedText)
+ }
+ }
+ })
+ }
+}
+
+func TestOwaspProtectionGlobalSafeRule_RuleMetadata(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.OwaspProtectionGlobalSafeRule{}
+
+ assert.Equal(t, "owasp-protection-global-safe", rule.ID())
+ assert.Equal(t, rules.CategorySecurity, rule.Category())
+ assert.NotEmpty(t, rule.Description())
+ assert.NotEmpty(t, rule.Link())
+ assert.Equal(t, validation.SeverityHint, rule.DefaultSeverity())
+ assert.Equal(t, []string{"3.0", "3.1"}, rule.Versions())
+}
diff --git a/openapi/linter/rules/owasp_protection_global_unsafe.go b/openapi/linter/rules/owasp_protection_global_unsafe.go
new file mode 100644
index 00000000..52b906fc
--- /dev/null
+++ b/openapi/linter/rules/owasp_protection_global_unsafe.go
@@ -0,0 +1,115 @@
+package rules
+
+import (
+ "context"
+ "fmt"
+ "strings"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/speakeasy-api/openapi/yml"
+)
+
+const RuleOwaspProtectionGlobalUnsafe = "owasp-protection-global-unsafe"
+
+// Unsafe HTTP methods that modify state and should be protected
+var unsafeMethods = map[string]bool{
+ "post": true,
+ "put": true,
+ "patch": true,
+ "delete": true,
+}
+
+type OwaspProtectionGlobalUnsafeRule struct{}
+
+func (r *OwaspProtectionGlobalUnsafeRule) ID() string { return RuleOwaspProtectionGlobalUnsafe }
+func (r *OwaspProtectionGlobalUnsafeRule) Category() string {
+ return CategorySecurity
+}
+func (r *OwaspProtectionGlobalUnsafeRule) Description() string {
+ return "Unsafe operations (POST, PUT, PATCH, DELETE) must be protected by security schemes to prevent unauthorized modifications. Write operations without authentication create serious security vulnerabilities allowing data tampering."
+}
+func (r *OwaspProtectionGlobalUnsafeRule) Summary() string {
+ return "Unsafe operations must be protected by security schemes."
+}
+func (r *OwaspProtectionGlobalUnsafeRule) HowToFix() string {
+ return "Define security requirements globally or per operation for POST/PUT/PATCH/DELETE endpoints."
+}
+func (r *OwaspProtectionGlobalUnsafeRule) Link() string {
+ return "https://github.com/speakeasy-api/openapi/blob/main/openapi/linter/README.md#owasp-protection-global-unsafe"
+}
+func (r *OwaspProtectionGlobalUnsafeRule) DefaultSeverity() validation.Severity {
+ return validation.SeverityError
+}
+func (r *OwaspProtectionGlobalUnsafeRule) Versions() []string {
+ return nil // Applies to all OpenAPI versions
+}
+
+func (r *OwaspProtectionGlobalUnsafeRule) Run(ctx context.Context, docInfo *linter.DocumentInfo[*openapi.OpenAPI], config *linter.RuleConfig) []error {
+ if docInfo == nil || docInfo.Document == nil || docInfo.Index == nil {
+ return nil
+ }
+
+ var errs []error
+
+ doc := docInfo.Document
+
+ // Check if there's a global security requirement
+ globalSecurity := doc.GetSecurity()
+ hasGlobalSecurity := len(globalSecurity) > 0
+
+ // Check all operations
+ for _, opNode := range docInfo.Index.Operations {
+ op := opNode.Node
+ if op == nil {
+ continue
+ }
+
+ // Get operation details
+ method := ""
+ path := ""
+ for _, loc := range opNode.Location {
+ switch openapi.GetParentType(loc) {
+ case "Paths":
+ if loc.ParentKey != nil {
+ path = *loc.ParentKey
+ }
+ case "PathItem":
+ if loc.ParentKey != nil {
+ method = *loc.ParentKey
+ }
+ }
+ }
+
+ // Only check unsafe methods
+ if !unsafeMethods[strings.ToLower(method)] {
+ continue
+ }
+
+ // Check if operation has explicit security field (even if empty array)
+ // security: [] means explicitly public and is allowed
+ rootNode := op.GetRootNode()
+ hasExplicitSecurity := false
+ if rootNode != nil {
+ _, _, found := yml.GetMapElementNodes(ctx, rootNode, "security")
+ hasExplicitSecurity = found
+ }
+
+ // Operation is protected if:
+ // 1. Has global security, OR
+ // 2. Has explicit operation-level security field (even if empty)
+ if !hasGlobalSecurity && !hasExplicitSecurity {
+ if rootNode != nil {
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleOwaspProtectionGlobalUnsafe,
+ fmt.Errorf("operation %s %s is not protected by any security scheme", method, path),
+ rootNode,
+ ))
+ }
+ }
+ }
+
+ return errs
+}
diff --git a/openapi/linter/rules/owasp_protection_global_unsafe_strict.go b/openapi/linter/rules/owasp_protection_global_unsafe_strict.go
new file mode 100644
index 00000000..3570e96a
--- /dev/null
+++ b/openapi/linter/rules/owasp_protection_global_unsafe_strict.go
@@ -0,0 +1,101 @@
+package rules
+
+import (
+ "context"
+ "fmt"
+ "strings"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/validation"
+)
+
+const RuleOwaspProtectionGlobalUnsafeStrict = "owasp-protection-global-unsafe-strict"
+
+type OwaspProtectionGlobalUnsafeStrictRule struct{}
+
+func (r *OwaspProtectionGlobalUnsafeStrictRule) ID() string {
+ return RuleOwaspProtectionGlobalUnsafeStrict
+}
+func (r *OwaspProtectionGlobalUnsafeStrictRule) Category() string {
+ return CategorySecurity
+}
+func (r *OwaspProtectionGlobalUnsafeStrictRule) Description() string {
+ return "Unsafe operations (POST, PUT, PATCH, DELETE) must be protected by non-empty security schemes without explicit opt-outs. Strict authentication requirements ensure write operations cannot bypass security even with empty security arrays."
+}
+func (r *OwaspProtectionGlobalUnsafeStrictRule) Summary() string {
+ return "Unsafe operations must have non-empty security schemes (no opt-outs)."
+}
+func (r *OwaspProtectionGlobalUnsafeStrictRule) HowToFix() string {
+ return "Define non-empty security requirements globally or per unsafe operation (no empty security arrays)."
+}
+func (r *OwaspProtectionGlobalUnsafeStrictRule) Link() string {
+ return "https://github.com/speakeasy-api/openapi/blob/main/openapi/linter/README.md#owasp-protection-global-unsafe-strict"
+}
+func (r *OwaspProtectionGlobalUnsafeStrictRule) DefaultSeverity() validation.Severity {
+ return validation.SeverityHint
+}
+func (r *OwaspProtectionGlobalUnsafeStrictRule) Versions() []string {
+ return []string{"3.0", "3.1"} // OAS3 only
+}
+
+func (r *OwaspProtectionGlobalUnsafeStrictRule) Run(ctx context.Context, docInfo *linter.DocumentInfo[*openapi.OpenAPI], config *linter.RuleConfig) []error {
+ if docInfo == nil || docInfo.Document == nil || docInfo.Index == nil {
+ return nil
+ }
+
+ var errs []error
+
+ doc := docInfo.Document
+
+ // Check if there's a global security requirement with actual schemes
+ globalSecurity := doc.GetSecurity()
+ hasGlobalSecurity := len(globalSecurity) > 0
+
+ // Check all operations
+ for _, opNode := range docInfo.Index.Operations {
+ op := opNode.Node
+ if op == nil {
+ continue
+ }
+
+ // Get operation details
+ method := ""
+ path := ""
+ for _, loc := range opNode.Location {
+ switch openapi.GetParentType(loc) {
+ case "Paths":
+ if loc.ParentKey != nil {
+ path = *loc.ParentKey
+ }
+ case "PathItem":
+ if loc.ParentKey != nil {
+ method = *loc.ParentKey
+ }
+ }
+ }
+
+ // Only check unsafe methods
+ if !unsafeMethods[strings.ToLower(method)] {
+ continue
+ }
+
+ // Check if operation has security with actual schemes
+ opSecurity := op.GetSecurity()
+ hasOpSecurity := len(opSecurity) > 0
+
+ // Strict mode: operation must have actual security schemes (no empty arrays allowed)
+ if !hasGlobalSecurity && !hasOpSecurity {
+ if rootNode := op.GetRootNode(); rootNode != nil {
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleOwaspProtectionGlobalUnsafeStrict,
+ fmt.Errorf("operation %s %s must be protected by a security scheme (empty security array not allowed)", method, path),
+ rootNode,
+ ))
+ }
+ }
+ }
+
+ return errs
+}
diff --git a/openapi/linter/rules/owasp_protection_global_unsafe_strict_test.go b/openapi/linter/rules/owasp_protection_global_unsafe_strict_test.go
new file mode 100644
index 00000000..86615535
--- /dev/null
+++ b/openapi/linter/rules/owasp_protection_global_unsafe_strict_test.go
@@ -0,0 +1,307 @@
+package rules_test
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/openapi/linter/rules"
+ "github.com/speakeasy-api/openapi/references"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestOwaspProtectionGlobalUnsafeStrictRule_ValidCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "global security protects all operations",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+security:
+ - apiKey: []
+components:
+ securitySchemes:
+ apiKey:
+ type: apiKey
+ in: header
+ name: X-API-Key
+paths:
+ /users:
+ post:
+ responses:
+ '201':
+ description: Created
+ delete:
+ responses:
+ '204':
+ description: Deleted
+`,
+ },
+ {
+ name: "operation-level security",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ securitySchemes:
+ apiKey:
+ type: apiKey
+ in: header
+ name: X-API-Key
+paths:
+ /users:
+ post:
+ security:
+ - apiKey: []
+ responses:
+ '201':
+ description: Created
+`,
+ },
+ {
+ name: "safe methods dont require security",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+`,
+ },
+ {
+ name: "mixed global and operation security",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+security:
+ - apiKey: []
+components:
+ securitySchemes:
+ apiKey:
+ type: apiKey
+ in: header
+ name: X-API-Key
+ oauth:
+ type: oauth2
+ flows:
+ implicit:
+ authorizationUrl: https://example.com/oauth
+ scopes:
+ write: Write access
+paths:
+ /users:
+ post:
+ responses:
+ '201':
+ description: Created
+ put:
+ security:
+ - oauth: [write]
+ responses:
+ '200':
+ description: Updated
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspProtectionGlobalUnsafeStrictRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+ assert.Empty(t, errs)
+ })
+ }
+}
+
+func TestOwaspProtectionGlobalUnsafeStrictRule_Violations(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ expectedCount int
+ expectedText string
+ }{
+ {
+ name: "post without security",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ post:
+ responses:
+ '201':
+ description: Created
+`,
+ expectedCount: 1,
+ expectedText: "post",
+ },
+ {
+ name: "empty security array not allowed in strict mode",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /public:
+ post:
+ security: []
+ responses:
+ '201':
+ description: Created
+`,
+ expectedCount: 1,
+ expectedText: "post",
+ },
+ {
+ name: "delete without security",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{id}:
+ delete:
+ responses:
+ '204':
+ description: Deleted
+`,
+ expectedCount: 1,
+ expectedText: "delete",
+ },
+ {
+ name: "multiple unsafe operations without security",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ post:
+ responses:
+ '201':
+ description: Created
+ put:
+ responses:
+ '200':
+ description: Updated
+ patch:
+ responses:
+ '200':
+ description: Patched
+ delete:
+ responses:
+ '204':
+ description: Deleted
+`,
+ expectedCount: 4,
+ expectedText: "",
+ },
+ {
+ name: "get is safe but post is not protected",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ post:
+ responses:
+ '201':
+ description: Created
+`,
+ expectedCount: 1,
+ expectedText: "post",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspProtectionGlobalUnsafeStrictRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ require.Len(t, errs, tt.expectedCount)
+ for _, err := range errs {
+ assert.Contains(t, err.Error(), "must be protected")
+ if tt.expectedText != "" {
+ assert.Contains(t, err.Error(), tt.expectedText)
+ }
+ }
+ })
+ }
+}
+
+func TestOwaspProtectionGlobalUnsafeStrictRule_RuleMetadata(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.OwaspProtectionGlobalUnsafeStrictRule{}
+
+ assert.Equal(t, "owasp-protection-global-unsafe-strict", rule.ID())
+ assert.Equal(t, rules.CategorySecurity, rule.Category())
+ assert.NotEmpty(t, rule.Description())
+ assert.NotEmpty(t, rule.Link())
+ assert.Equal(t, validation.SeverityHint, rule.DefaultSeverity())
+ assert.Equal(t, []string{"3.0", "3.1"}, rule.Versions())
+}
diff --git a/openapi/linter/rules/owasp_protection_global_unsafe_test.go b/openapi/linter/rules/owasp_protection_global_unsafe_test.go
new file mode 100644
index 00000000..5e19f5d4
--- /dev/null
+++ b/openapi/linter/rules/owasp_protection_global_unsafe_test.go
@@ -0,0 +1,305 @@
+package rules_test
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/openapi/linter/rules"
+ "github.com/speakeasy-api/openapi/references"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestOwaspProtectionGlobalUnsafeRule_ValidCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "global security protects all operations",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+security:
+ - apiKey: []
+components:
+ securitySchemes:
+ apiKey:
+ type: apiKey
+ in: header
+ name: X-API-Key
+paths:
+ /users:
+ post:
+ responses:
+ '201':
+ description: Created
+ delete:
+ responses:
+ '204':
+ description: Deleted
+`,
+ },
+ {
+ name: "operation-level security",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ securitySchemes:
+ apiKey:
+ type: apiKey
+ in: header
+ name: X-API-Key
+paths:
+ /users:
+ post:
+ security:
+ - apiKey: []
+ responses:
+ '201':
+ description: Created
+`,
+ },
+ {
+ name: "safe methods dont require security",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+`,
+ },
+ {
+ name: "empty security array allowed",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /public:
+ post:
+ security: []
+ responses:
+ '201':
+ description: Created
+`,
+ },
+ {
+ name: "mixed global and operation security",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+security:
+ - apiKey: []
+components:
+ securitySchemes:
+ apiKey:
+ type: apiKey
+ in: header
+ name: X-API-Key
+ oauth:
+ type: oauth2
+ flows:
+ implicit:
+ authorizationUrl: https://example.com/oauth
+ scopes:
+ write: Write access
+paths:
+ /users:
+ post:
+ responses:
+ '201':
+ description: Created
+ put:
+ security:
+ - oauth: [write]
+ responses:
+ '200':
+ description: Updated
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspProtectionGlobalUnsafeRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+ assert.Empty(t, errs)
+ })
+ }
+}
+
+func TestOwaspProtectionGlobalUnsafeRule_Violations(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ expectedCount int
+ expectedText string
+ }{
+ {
+ name: "post without security",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ post:
+ responses:
+ '201':
+ description: Created
+`,
+ expectedCount: 1,
+ expectedText: "post",
+ },
+ {
+ name: "delete without security",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{id}:
+ delete:
+ responses:
+ '204':
+ description: Deleted
+`,
+ expectedCount: 1,
+ expectedText: "delete",
+ },
+ {
+ name: "multiple unsafe operations without security",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ post:
+ responses:
+ '201':
+ description: Created
+ put:
+ responses:
+ '200':
+ description: Updated
+ patch:
+ responses:
+ '200':
+ description: Patched
+ delete:
+ responses:
+ '204':
+ description: Deleted
+`,
+ expectedCount: 4,
+ expectedText: "",
+ },
+ {
+ name: "get is safe but post is not protected",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ post:
+ responses:
+ '201':
+ description: Created
+`,
+ expectedCount: 1,
+ expectedText: "post",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspProtectionGlobalUnsafeRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ require.Len(t, errs, tt.expectedCount)
+ for _, err := range errs {
+ assert.Contains(t, err.Error(), "not protected")
+ if tt.expectedText != "" {
+ assert.Contains(t, err.Error(), tt.expectedText)
+ }
+ }
+ })
+ }
+}
+
+func TestOwaspProtectionGlobalUnsafeRule_RuleMetadata(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.OwaspProtectionGlobalUnsafeRule{}
+
+ assert.Equal(t, "owasp-protection-global-unsafe", rule.ID())
+ assert.Equal(t, rules.CategorySecurity, rule.Category())
+ assert.NotEmpty(t, rule.Description())
+ assert.NotEmpty(t, rule.Link())
+ assert.Equal(t, validation.SeverityError, rule.DefaultSeverity())
+ assert.Nil(t, rule.Versions())
+}
diff --git a/openapi/linter/rules/owasp_rate_limit.go b/openapi/linter/rules/owasp_rate_limit.go
new file mode 100644
index 00000000..6d1dfa61
--- /dev/null
+++ b/openapi/linter/rules/owasp_rate_limit.go
@@ -0,0 +1,137 @@
+package rules
+
+import (
+ "context"
+ "fmt"
+ "strings"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/validation"
+)
+
+const RuleOwaspRateLimit = "owasp-rate-limit"
+
+// Rate limiting headers to check for
+var rateLimitHeaders = []string{
+ "X-RateLimit-Limit",
+ "X-Rate-Limit-Limit",
+ "RateLimit-Limit",
+ "RateLimit-Reset",
+ "RateLimit",
+}
+
+type OwaspRateLimitRule struct{}
+
+func (r *OwaspRateLimitRule) ID() string {
+ return RuleOwaspRateLimit
+}
+func (r *OwaspRateLimitRule) Category() string {
+ return CategorySecurity
+}
+func (r *OwaspRateLimitRule) Description() string {
+ return "2XX and 4XX responses must define rate limiting headers (X-RateLimit-Limit, X-RateLimit-Remaining) to prevent API overload. Rate limit headers help clients manage their usage and avoid hitting limits."
+}
+func (r *OwaspRateLimitRule) Summary() string {
+ return "2XX and 4XX responses should include rate limit headers."
+}
+func (r *OwaspRateLimitRule) HowToFix() string {
+ return "Add rate limit headers (e.g., X-RateLimit-Limit, X-RateLimit-Remaining) to 2XX and 4XX responses."
+}
+func (r *OwaspRateLimitRule) Link() string {
+ return "https://github.com/speakeasy-api/openapi/blob/main/openapi/linter/README.md#owasp-rate-limit"
+}
+func (r *OwaspRateLimitRule) DefaultSeverity() validation.Severity {
+ return validation.SeverityError
+}
+func (r *OwaspRateLimitRule) Versions() []string {
+ return []string{"3.0", "3.1"} // OAS3 only
+}
+
+func (r *OwaspRateLimitRule) Run(ctx context.Context, docInfo *linter.DocumentInfo[*openapi.OpenAPI], config *linter.RuleConfig) []error {
+ if docInfo == nil || docInfo.Document == nil || docInfo.Index == nil {
+ return nil
+ }
+
+ var errs []error
+
+ // Check all operations
+ for _, opNode := range docInfo.Index.Operations {
+ op := opNode.Node
+ if op == nil {
+ continue
+ }
+
+ // Get operation details for error messages
+ method := ""
+ path := ""
+ for _, loc := range opNode.Location {
+ switch openapi.GetParentType(loc) {
+ case "Paths":
+ if loc.ParentKey != nil {
+ path = *loc.ParentKey
+ }
+ case "PathItem":
+ if loc.ParentKey != nil {
+ method = *loc.ParentKey
+ }
+ }
+ }
+
+ responses := op.GetResponses()
+ if responses == nil {
+ continue
+ }
+
+ // Check all response codes
+ for statusCode, response := range responses.All() {
+ // Only check 2XX and 4XX responses
+ if !strings.HasPrefix(statusCode, "2") && !strings.HasPrefix(statusCode, "4") {
+ continue
+ }
+
+ responseObj := response.GetObject()
+ if responseObj == nil {
+ continue
+ }
+
+ headers := responseObj.GetHeaders()
+ if headers == nil || headers.Len() == 0 {
+ // No headers defined - report missing rate limit headers
+ if rootNode := response.GetRootNode(); rootNode != nil {
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleOwaspRateLimit,
+ fmt.Errorf("response %s for operation %s %s is missing rate limiting headers", statusCode, method, path),
+ rootNode,
+ ))
+ }
+ continue
+ }
+
+ // Check if any rate limit header is present
+ hasRateLimitHeader := false
+ for _, headerName := range rateLimitHeaders {
+ if _, exists := headers.Get(headerName); exists {
+ hasRateLimitHeader = true
+ break
+ }
+ }
+
+ if !hasRateLimitHeader {
+ // No rate limit header found
+ if rootNode := responseObj.GetRootNode(); rootNode != nil {
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleOwaspRateLimit,
+ fmt.Errorf("response %s for operation %s %s is missing rate limiting headers (expected one of: %s)",
+ statusCode, method, path, strings.Join(rateLimitHeaders, ", ")),
+ rootNode,
+ ))
+ }
+ }
+ }
+ }
+
+ return errs
+}
diff --git a/openapi/linter/rules/owasp_rate_limit_retry_after.go b/openapi/linter/rules/owasp_rate_limit_retry_after.go
new file mode 100644
index 00000000..c63b2627
--- /dev/null
+++ b/openapi/linter/rules/owasp_rate_limit_retry_after.go
@@ -0,0 +1,122 @@
+package rules
+
+import (
+ "context"
+ "fmt"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/validation"
+)
+
+const RuleOwaspRateLimitRetryAfter = "owasp-rate-limit-retry-after"
+
+type OwaspRateLimitRetryAfterRule struct{}
+
+func (r *OwaspRateLimitRetryAfterRule) ID() string {
+ return RuleOwaspRateLimitRetryAfter
+}
+func (r *OwaspRateLimitRetryAfterRule) Category() string {
+ return CategorySecurity
+}
+func (r *OwaspRateLimitRetryAfterRule) Description() string {
+ return "429 Too Many Requests responses must include a Retry-After header indicating when clients can retry. Retry-After headers prevent thundering herd problems by telling clients exactly when to resume requests."
+}
+func (r *OwaspRateLimitRetryAfterRule) Summary() string {
+ return "429 responses must include a Retry-After header."
+}
+func (r *OwaspRateLimitRetryAfterRule) HowToFix() string {
+ return "Add a Retry-After header to 429 responses to indicate when clients can retry."
+}
+func (r *OwaspRateLimitRetryAfterRule) Link() string {
+ return "https://github.com/speakeasy-api/openapi/blob/main/openapi/linter/README.md#owasp-rate-limit-retry-after"
+}
+func (r *OwaspRateLimitRetryAfterRule) DefaultSeverity() validation.Severity {
+ return validation.SeverityError
+}
+func (r *OwaspRateLimitRetryAfterRule) Versions() []string {
+ return []string{"3.0", "3.1"} // OAS3 only
+}
+
+func (r *OwaspRateLimitRetryAfterRule) Run(ctx context.Context, docInfo *linter.DocumentInfo[*openapi.OpenAPI], config *linter.RuleConfig) []error {
+ if docInfo == nil || docInfo.Document == nil || docInfo.Index == nil {
+ return nil
+ }
+
+ var errs []error
+
+ // Check all operations
+ for _, opNode := range docInfo.Index.Operations {
+ op := opNode.Node
+ if op == nil {
+ continue
+ }
+
+ // Get operation details for error messages
+ method := ""
+ path := ""
+ for _, loc := range opNode.Location {
+ switch openapi.GetParentType(loc) {
+ case "Paths":
+ if loc.ParentKey != nil {
+ path = *loc.ParentKey
+ }
+ case "PathItem":
+ if loc.ParentKey != nil {
+ method = *loc.ParentKey
+ }
+ }
+ }
+
+ responses := op.GetResponses()
+ if responses == nil {
+ continue
+ }
+
+ // Check for 429 response
+ response429, exists := responses.Get("429")
+ if !exists || response429 == nil {
+ continue
+ }
+
+ responseObj := response429.GetObject()
+ if responseObj == nil {
+ continue
+ }
+
+ // Check if Retry-After header exists
+ headers := responseObj.GetHeaders()
+ if headers == nil {
+ // No headers at all
+ if rootNode := response429.GetRootNode(); rootNode != nil {
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleOwaspRateLimitRetryAfter,
+ fmt.Errorf("429 response for operation %s %s is missing Retry-After header", method, path),
+ rootNode,
+ ))
+ }
+ continue
+ }
+
+ // Check for Retry-After header (case-insensitive check)
+ retryAfter, hasRetryAfter := headers.Get("Retry-After")
+ if !hasRetryAfter || retryAfter == nil {
+ // Try alternate casing
+ retryAfter, hasRetryAfter = headers.Get("retry-after")
+ }
+
+ if !hasRetryAfter || retryAfter == nil {
+ if rootNode := responseObj.GetRootNode(); rootNode != nil {
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleOwaspRateLimitRetryAfter,
+ fmt.Errorf("429 response for operation %s %s is missing Retry-After header", method, path),
+ rootNode,
+ ))
+ }
+ }
+ }
+
+ return errs
+}
diff --git a/openapi/linter/rules/owasp_rate_limit_retry_after_test.go b/openapi/linter/rules/owasp_rate_limit_retry_after_test.go
new file mode 100644
index 00000000..50526e55
--- /dev/null
+++ b/openapi/linter/rules/owasp_rate_limit_retry_after_test.go
@@ -0,0 +1,301 @@
+package rules_test
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/openapi/linter/rules"
+ "github.com/speakeasy-api/openapi/references"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestOwaspRateLimitRetryAfterRule_ValidCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "429 response with Retry-After header",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '429':
+ description: Too Many Requests
+ headers:
+ Retry-After:
+ description: Number of seconds to wait
+ schema:
+ type: integer
+`,
+ },
+ {
+ name: "429 with lowercase retry-after header",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '429':
+ description: Too Many Requests
+ headers:
+ retry-after:
+ schema:
+ type: integer
+`,
+ },
+ {
+ name: "no 429 response is ok",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ '400':
+ description: Bad Request
+`,
+ },
+ {
+ name: "429 with Retry-After and other headers",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '429':
+ description: Too Many Requests
+ headers:
+ Retry-After:
+ schema:
+ type: integer
+ X-RateLimit-Limit:
+ schema:
+ type: integer
+ X-RateLimit-Remaining:
+ schema:
+ type: integer
+`,
+ },
+ {
+ name: "multiple operations with 429 and Retry-After",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '429':
+ description: Too Many Requests
+ headers:
+ Retry-After:
+ schema:
+ type: integer
+ post:
+ responses:
+ '429':
+ description: Too Many Requests
+ headers:
+ Retry-After:
+ schema:
+ type: integer
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspRateLimitRetryAfterRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+ assert.Empty(t, errs)
+ })
+ }
+}
+
+func TestOwaspRateLimitRetryAfterRule_Violations(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ expectedCount int
+ expectedText string
+ }{
+ {
+ name: "429 response missing Retry-After header",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '429':
+ description: Too Many Requests
+`,
+ expectedCount: 1,
+ expectedText: "Retry-After",
+ },
+ {
+ name: "429 has headers but no Retry-After",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '429':
+ description: Too Many Requests
+ headers:
+ X-RateLimit-Limit:
+ schema:
+ type: integer
+`,
+ expectedCount: 1,
+ expectedText: "Retry-After",
+ },
+ {
+ name: "multiple operations with 429 missing Retry-After",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '429':
+ description: Too Many Requests
+ post:
+ responses:
+ '429':
+ description: Too Many Requests
+ /posts:
+ get:
+ responses:
+ '429':
+ description: Too Many Requests
+`,
+ expectedCount: 3,
+ expectedText: "",
+ },
+ {
+ name: "mixed operations some with some without Retry-After",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '429':
+ description: Too Many Requests
+ headers:
+ Retry-After:
+ schema:
+ type: integer
+ post:
+ responses:
+ '429':
+ description: Too Many Requests
+`,
+ expectedCount: 1,
+ expectedText: "post",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspRateLimitRetryAfterRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ require.Len(t, errs, tt.expectedCount)
+ for _, err := range errs {
+ assert.Contains(t, err.Error(), "429")
+ if tt.expectedText != "" {
+ assert.Contains(t, err.Error(), tt.expectedText)
+ }
+ }
+ })
+ }
+}
+
+func TestOwaspRateLimitRetryAfterRule_RuleMetadata(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.OwaspRateLimitRetryAfterRule{}
+
+ assert.Equal(t, "owasp-rate-limit-retry-after", rule.ID())
+ assert.Equal(t, rules.CategorySecurity, rule.Category())
+ assert.NotEmpty(t, rule.Description())
+ assert.NotEmpty(t, rule.Link())
+ assert.Equal(t, validation.SeverityError, rule.DefaultSeverity())
+ assert.Equal(t, []string{"3.0", "3.1"}, rule.Versions())
+}
diff --git a/openapi/linter/rules/owasp_rate_limit_test.go b/openapi/linter/rules/owasp_rate_limit_test.go
new file mode 100644
index 00000000..b18eaa67
--- /dev/null
+++ b/openapi/linter/rules/owasp_rate_limit_test.go
@@ -0,0 +1,319 @@
+package rules_test
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/openapi/linter/rules"
+ "github.com/speakeasy-api/openapi/references"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestOwaspRateLimitRule_ValidCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "2xx response with X-RateLimit-Limit header",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ headers:
+ X-RateLimit-Limit:
+ description: Request limit per hour
+ schema:
+ type: integer
+`,
+ },
+ {
+ name: "4xx response with RateLimit header",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '429':
+ description: Too Many Requests
+ headers:
+ RateLimit:
+ description: Rate limit info
+ schema:
+ type: string
+`,
+ },
+ {
+ name: "response with RateLimit-Limit header",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ headers:
+ RateLimit-Limit:
+ schema:
+ type: integer
+`,
+ },
+ {
+ name: "3xx response without rate limit headers is ok",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '301':
+ description: Moved Permanently
+`,
+ },
+ {
+ name: "5xx response without rate limit headers is ok",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '500':
+ description: Server Error
+`,
+ },
+ {
+ name: "multiple responses with rate limit headers",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ headers:
+ X-Rate-Limit-Limit:
+ schema:
+ type: integer
+ '400':
+ description: Bad Request
+ headers:
+ RateLimit-Reset:
+ schema:
+ type: integer
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspRateLimitRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+ assert.Empty(t, errs)
+ })
+ }
+}
+
+func TestOwaspRateLimitRule_Violations(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ expectedCount int
+ expectedText string
+ }{
+ {
+ name: "2xx response missing rate limit headers",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+`,
+ expectedCount: 1,
+ expectedText: "200",
+ },
+ {
+ name: "4xx response missing rate limit headers",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '400':
+ description: Bad Request
+`,
+ expectedCount: 1,
+ expectedText: "400",
+ },
+ {
+ name: "2xx response has headers but no rate limit header",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ headers:
+ X-Request-ID:
+ schema:
+ type: string
+`,
+ expectedCount: 1,
+ expectedText: "missing rate limiting headers",
+ },
+ {
+ name: "multiple responses missing rate limit headers",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ '201':
+ description: Created
+ '400':
+ description: Bad Request
+ '404':
+ description: Not Found
+`,
+ expectedCount: 4,
+ expectedText: "",
+ },
+ {
+ name: "mixed responses some with some without rate limit headers",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ headers:
+ RateLimit:
+ schema:
+ type: string
+ '400':
+ description: Bad Request
+`,
+ expectedCount: 1,
+ expectedText: "400",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspRateLimitRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ require.Len(t, errs, tt.expectedCount)
+ for _, err := range errs {
+ assert.Contains(t, err.Error(), "rate limiting")
+ if tt.expectedText != "" {
+ assert.Contains(t, err.Error(), tt.expectedText)
+ }
+ }
+ })
+ }
+}
+
+func TestOwaspRateLimitRule_RuleMetadata(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.OwaspRateLimitRule{}
+
+ assert.Equal(t, "owasp-rate-limit", rule.ID())
+ assert.Equal(t, rules.CategorySecurity, rule.Category())
+ assert.NotEmpty(t, rule.Description())
+ assert.NotEmpty(t, rule.Link())
+ assert.Equal(t, validation.SeverityError, rule.DefaultSeverity())
+ assert.Equal(t, []string{"3.0", "3.1"}, rule.Versions())
+}
diff --git a/openapi/linter/rules/owasp_security_hosts_https_oas3.go b/openapi/linter/rules/owasp_security_hosts_https_oas3.go
new file mode 100644
index 00000000..b86d9ece
--- /dev/null
+++ b/openapi/linter/rules/owasp_security_hosts_https_oas3.go
@@ -0,0 +1,85 @@
+package rules
+
+import (
+ "context"
+ "fmt"
+ "strings"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/speakeasy-api/openapi/yml"
+)
+
+const RuleOwaspSecurityHostsHttpsOAS3 = "owasp-security-hosts-https-oas3"
+
+type OwaspSecurityHostsHttpsOAS3Rule struct{}
+
+func (r *OwaspSecurityHostsHttpsOAS3Rule) ID() string {
+ return RuleOwaspSecurityHostsHttpsOAS3
+}
+func (r *OwaspSecurityHostsHttpsOAS3Rule) Category() string {
+ return CategorySecurity
+}
+func (r *OwaspSecurityHostsHttpsOAS3Rule) Description() string {
+ return "Server URLs must begin with https:// as the only permitted protocol. Using HTTPS is essential for protecting API traffic from interception, tampering, and eavesdropping attacks."
+}
+func (r *OwaspSecurityHostsHttpsOAS3Rule) Summary() string {
+ return "Server URLs must use HTTPS."
+}
+func (r *OwaspSecurityHostsHttpsOAS3Rule) HowToFix() string {
+ return "Update server URLs to use https:// instead of http://."
+}
+func (r *OwaspSecurityHostsHttpsOAS3Rule) Link() string {
+ return "https://github.com/speakeasy-api/openapi/blob/main/openapi/linter/README.md#owasp-security-hosts-https-oas3"
+}
+func (r *OwaspSecurityHostsHttpsOAS3Rule) DefaultSeverity() validation.Severity {
+ return validation.SeverityError
+}
+func (r *OwaspSecurityHostsHttpsOAS3Rule) Versions() []string {
+ return []string{"3.0", "3.1"} // Only applies to OpenAPI 3.x
+}
+
+func (r *OwaspSecurityHostsHttpsOAS3Rule) Run(ctx context.Context, docInfo *linter.DocumentInfo[*openapi.OpenAPI], config *linter.RuleConfig) []error {
+ if docInfo == nil || docInfo.Document == nil {
+ return nil
+ }
+
+ var errs []error
+
+ doc := docInfo.Document
+ servers := doc.GetServers()
+ if len(servers) == 0 {
+ return nil
+ }
+
+ // Check each server URL
+ for _, server := range servers {
+ if server == nil {
+ continue
+ }
+
+ url := server.GetURL()
+ if url == "" {
+ continue
+ }
+
+ // Check if URL starts with https
+ if !strings.HasPrefix(url, "https") {
+ // Get the root node to find the url key
+ if rootNode := server.GetRootNode(); rootNode != nil {
+ _, urlValueNode, found := yml.GetMapElementNodes(ctx, rootNode, "url")
+ if found && urlValueNode != nil {
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleOwaspSecurityHostsHttpsOAS3,
+ fmt.Errorf("server URL `%s` must use HTTPS protocol for security", url),
+ urlValueNode,
+ ))
+ }
+ }
+ }
+ }
+
+ return errs
+}
diff --git a/openapi/linter/rules/owasp_security_hosts_https_oas3_test.go b/openapi/linter/rules/owasp_security_hosts_https_oas3_test.go
new file mode 100644
index 00000000..66a73708
--- /dev/null
+++ b/openapi/linter/rules/owasp_security_hosts_https_oas3_test.go
@@ -0,0 +1,309 @@
+package rules_test
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/openapi/linter/rules"
+ "github.com/speakeasy-api/openapi/references"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestOwaspSecurityHostsHttpsOAS3Rule_ValidCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "https server url",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+servers:
+ - url: https://api.example.com
+paths: {}
+`,
+ },
+ {
+ name: "https with path",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+servers:
+ - url: https://api.example.com/v1
+paths: {}
+`,
+ },
+ {
+ name: "multiple https servers",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+servers:
+ - url: https://api.example.com
+ description: Production
+ - url: https://staging.example.com
+ description: Staging
+paths: {}
+`,
+ },
+ {
+ name: "no servers defined",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths: {}
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspSecurityHostsHttpsOAS3Rule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+ assert.Empty(t, errs)
+ })
+ }
+}
+
+func TestOwaspSecurityHostsHttpsOAS3Rule_Violations(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ expectedCount int
+ expectedText string
+ }{
+ {
+ name: "http server url",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+servers:
+ - url: http://api.example.com
+paths: {}
+`,
+ expectedCount: 1,
+ expectedText: "http://api.example.com",
+ },
+ {
+ name: "ftp server url",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+servers:
+ - url: ftp://api.example.com
+paths: {}
+`,
+ expectedCount: 1,
+ expectedText: "ftp://api.example.com",
+ },
+ {
+ name: "mixed https and http servers",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+servers:
+ - url: https://api.example.com
+ description: Production
+ - url: http://staging.example.com
+ description: Staging (insecure)
+paths: {}
+`,
+ expectedCount: 1,
+ expectedText: "http://staging.example.com",
+ },
+ {
+ name: "multiple non-https servers",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+servers:
+ - url: http://api.example.com
+ - url: ws://websocket.example.com
+paths: {}
+`,
+ expectedCount: 2,
+ expectedText: "",
+ },
+ {
+ name: "relative url not starting with https",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+servers:
+ - url: /api/v1
+paths: {}
+`,
+ expectedCount: 1,
+ expectedText: "/api/v1",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspSecurityHostsHttpsOAS3Rule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ require.Len(t, errs, tt.expectedCount)
+ for _, err := range errs {
+ assert.Contains(t, err.Error(), "HTTPS")
+ if tt.expectedText != "" {
+ assert.Contains(t, err.Error(), tt.expectedText)
+ }
+ }
+ })
+ }
+}
+
+func TestOwaspSecurityHostsHttpsOAS3Rule_EdgeCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "server with empty url",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+servers:
+ - url: ""
+ description: Empty URL
+paths: {}
+`,
+ },
+ {
+ name: "server with variables in https url",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+servers:
+ - url: https://{environment}.example.com
+ variables:
+ environment:
+ default: api
+paths: {}
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspSecurityHostsHttpsOAS3Rule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ // Should not panic
+ errs := rule.Run(ctx, docInfo, config)
+
+ // Empty URL should be skipped, variables in https URL should be valid
+ assert.Empty(t, errs)
+ })
+ }
+}
+
+func TestOwaspSecurityHostsHttpsOAS3Rule_NilInputs(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.OwaspSecurityHostsHttpsOAS3Rule{}
+ config := &linter.RuleConfig{}
+ ctx := t.Context()
+
+ // Test with nil docInfo
+ errs := rule.Run(ctx, nil, config)
+ assert.Empty(t, errs)
+
+ // Test with nil document
+ var nilDoc *openapi.OpenAPI
+ errs = rule.Run(ctx, linter.NewDocumentInfoWithIndex(nilDoc, "test.yaml", nil), config)
+ assert.Empty(t, errs)
+}
+
+func TestOwaspSecurityHostsHttpsOAS3Rule_RuleMetadata(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.OwaspSecurityHostsHttpsOAS3Rule{}
+
+ assert.Equal(t, "owasp-security-hosts-https-oas3", rule.ID())
+ assert.Equal(t, rules.CategorySecurity, rule.Category())
+ assert.NotEmpty(t, rule.Description())
+ assert.NotEmpty(t, rule.Link())
+ assert.Equal(t, validation.SeverityError, rule.DefaultSeverity())
+ assert.Equal(t, []string{"3.0", "3.1"}, rule.Versions())
+}
diff --git a/openapi/linter/rules/owasp_string_limit.go b/openapi/linter/rules/owasp_string_limit.go
new file mode 100644
index 00000000..198037ee
--- /dev/null
+++ b/openapi/linter/rules/owasp_string_limit.go
@@ -0,0 +1,89 @@
+package rules
+
+import (
+ "context"
+ "errors"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/validation"
+)
+
+const RuleOwaspStringLimit = "owasp-string-limit"
+
+type OwaspStringLimitRule struct{}
+
+func (r *OwaspStringLimitRule) ID() string {
+ return RuleOwaspStringLimit
+}
+func (r *OwaspStringLimitRule) Category() string {
+ return CategorySecurity
+}
+func (r *OwaspStringLimitRule) Description() string {
+ return "String schemas must specify maxLength, const, or enum to prevent unbounded data. Without string length limits, APIs are vulnerable to resource exhaustion from extremely long inputs."
+}
+func (r *OwaspStringLimitRule) Summary() string {
+ return "String schemas must specify maxLength, const, or enum."
+}
+func (r *OwaspStringLimitRule) HowToFix() string {
+ return "Add maxLength, const, or enum constraints to string schemas."
+}
+func (r *OwaspStringLimitRule) Link() string {
+ return "https://github.com/speakeasy-api/openapi/blob/main/openapi/linter/README.md#owasp-string-limit"
+}
+func (r *OwaspStringLimitRule) DefaultSeverity() validation.Severity {
+ return validation.SeverityError
+}
+func (r *OwaspStringLimitRule) Versions() []string {
+ return []string{"3.0", "3.1"}
+}
+
+func (r *OwaspStringLimitRule) Run(ctx context.Context, docInfo *linter.DocumentInfo[*openapi.OpenAPI], config *linter.RuleConfig) []error {
+ if docInfo == nil || docInfo.Document == nil || docInfo.Index == nil {
+ return nil
+ }
+
+ var errs []error
+
+ // Check all schemas in the document
+ for _, schemaNode := range docInfo.Index.GetAllSchemas() {
+ refSchema := schemaNode.Node
+ schema := refSchema.GetSchema()
+ if schema == nil {
+ continue
+ }
+
+ // Check if type contains "string"
+ types := schema.GetType()
+ hasStringType := false
+ for _, typ := range types {
+ if typ == "string" {
+ hasStringType = true
+ break
+ }
+ }
+
+ if !hasStringType {
+ continue
+ }
+
+ // Check if schema has maxLength, const, or enum defined
+ maxLength := schema.GetMaxLength()
+ constValue := schema.GetConst()
+ enumValues := schema.GetEnum()
+
+ // If none of these are defined, report error
+ if maxLength == nil && constValue == nil && len(enumValues) == 0 {
+ if rootNode := refSchema.GetRootNode(); rootNode != nil {
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleOwaspStringLimit,
+ errors.New("schema of type 'string' must specify maxLength, const, or enum to prevent unbounded data"),
+ rootNode,
+ ))
+ }
+ }
+ }
+
+ return errs
+}
diff --git a/openapi/linter/rules/owasp_string_limit_test.go b/openapi/linter/rules/owasp_string_limit_test.go
new file mode 100644
index 00000000..1deaabaa
--- /dev/null
+++ b/openapi/linter/rules/owasp_string_limit_test.go
@@ -0,0 +1,267 @@
+package rules_test
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/openapi/linter/rules"
+ "github.com/speakeasy-api/openapi/references"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestOwaspStringLimitRule_ValidCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "string with maxLength",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ User:
+ type: object
+ properties:
+ name:
+ type: string
+ maxLength: 100
+paths: {}
+`,
+ },
+ {
+ name: "string with const",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Status:
+ type: string
+ const: active
+paths: {}
+`,
+ },
+ {
+ name: "string with enum",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Status:
+ type: string
+ enum:
+ - active
+ - inactive
+ - pending
+paths: {}
+`,
+ },
+ {
+ name: "non-string type without maxLength is ok",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Counter:
+ type: integer
+paths: {}
+`,
+ },
+ {
+ name: "object type is ok",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ User:
+ type: object
+ properties:
+ id:
+ type: string
+ maxLength: 36
+paths: {}
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspStringLimitRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+ assert.Empty(t, errs)
+ })
+ }
+}
+
+func TestOwaspStringLimitRule_Violations(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ expectedCount int
+ }{
+ {
+ name: "string without maxLength, const, or enum",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ User:
+ type: object
+ properties:
+ name:
+ type: string
+paths: {}
+`,
+ expectedCount: 1,
+ },
+ {
+ name: "multiple strings without constraints",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ User:
+ type: object
+ properties:
+ name:
+ type: string
+ email:
+ type: string
+ description:
+ type: string
+paths: {}
+`,
+ expectedCount: 3,
+ },
+ {
+ name: "inline string parameter without maxLength",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ parameters:
+ - name: search
+ in: query
+ schema:
+ type: string
+ responses:
+ '200':
+ description: Success
+`,
+ expectedCount: 1,
+ },
+ {
+ name: "response with string without constraint",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: Success
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ message:
+ type: string
+`,
+ expectedCount: 1,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspStringLimitRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ require.Len(t, errs, tt.expectedCount)
+ for _, err := range errs {
+ assert.Contains(t, err.Error(), "must specify maxLength, const, or enum")
+ }
+ })
+ }
+}
+
+func TestOwaspStringLimitRule_RuleMetadata(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.OwaspStringLimitRule{}
+
+ assert.Equal(t, "owasp-string-limit", rule.ID())
+ assert.Equal(t, rules.CategorySecurity, rule.Category())
+ assert.NotEmpty(t, rule.Description())
+ assert.NotEmpty(t, rule.Link())
+ assert.Equal(t, validation.SeverityError, rule.DefaultSeverity())
+ assert.Equal(t, []string{"3.0", "3.1"}, rule.Versions())
+}
diff --git a/openapi/linter/rules/owasp_string_restricted.go b/openapi/linter/rules/owasp_string_restricted.go
new file mode 100644
index 00000000..1b9418de
--- /dev/null
+++ b/openapi/linter/rules/owasp_string_restricted.go
@@ -0,0 +1,90 @@
+package rules
+
+import (
+ "context"
+ "errors"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/validation"
+)
+
+const RuleOwaspStringRestricted = "owasp-string-restricted"
+
+type OwaspStringRestrictedRule struct{}
+
+func (r *OwaspStringRestrictedRule) ID() string {
+ return RuleOwaspStringRestricted
+}
+func (r *OwaspStringRestrictedRule) Category() string {
+ return CategorySecurity
+}
+func (r *OwaspStringRestrictedRule) Description() string {
+ return "String schemas must specify `format`, `const`, `enum`, or `pattern` to restrict content. String restrictions prevent injection attacks and ensure data conforms to expected formats."
+}
+func (r *OwaspStringRestrictedRule) Summary() string {
+ return "String schemas must specify `format`, `const`, `enum`, or `pattern`."
+}
+func (r *OwaspStringRestrictedRule) HowToFix() string {
+ return "Add `format`, `const`, `enum`, or `pattern` constraints to string schemas."
+}
+func (r *OwaspStringRestrictedRule) Link() string {
+ return "https://github.com/speakeasy-api/openapi/blob/main/openapi/linter/README.md#owasp-string-restricted"
+}
+func (r *OwaspStringRestrictedRule) DefaultSeverity() validation.Severity {
+ return validation.SeverityError
+}
+func (r *OwaspStringRestrictedRule) Versions() []string {
+ return []string{"3.0", "3.1"}
+}
+
+func (r *OwaspStringRestrictedRule) Run(ctx context.Context, docInfo *linter.DocumentInfo[*openapi.OpenAPI], config *linter.RuleConfig) []error {
+ if docInfo == nil || docInfo.Document == nil || docInfo.Index == nil {
+ return nil
+ }
+
+ var errs []error
+
+ // Check all schemas in the document
+ for _, schemaNode := range docInfo.Index.GetAllSchemas() {
+ refSchema := schemaNode.Node
+ schema := refSchema.GetSchema()
+ if schema == nil {
+ continue
+ }
+
+ // Check if type contains "string"
+ types := schema.GetType()
+ hasStringType := false
+ for _, typ := range types {
+ if typ == "string" {
+ hasStringType = true
+ break
+ }
+ }
+
+ if !hasStringType {
+ continue
+ }
+
+ // Check if schema has format, const, enum, or pattern defined
+ format := schema.GetFormat()
+ constValue := schema.GetConst()
+ enumValues := schema.GetEnum()
+ pattern := schema.GetPattern()
+
+ // If none of these are defined, report error
+ if format == "" && constValue == nil && len(enumValues) == 0 && pattern == "" {
+ if rootNode := refSchema.GetRootNode(); rootNode != nil {
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleOwaspStringRestricted,
+ errors.New("schema of type `string` must specify `format`, `const`, `enum`, or `pattern` to restrict content"),
+ rootNode,
+ ))
+ }
+ }
+ }
+
+ return errs
+}
diff --git a/openapi/linter/rules/owasp_string_restricted_test.go b/openapi/linter/rules/owasp_string_restricted_test.go
new file mode 100644
index 00000000..bc1ec390
--- /dev/null
+++ b/openapi/linter/rules/owasp_string_restricted_test.go
@@ -0,0 +1,237 @@
+package rules_test
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/openapi/linter/rules"
+ "github.com/speakeasy-api/openapi/references"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestOwaspStringRestrictedRule_ValidCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "string with format",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Email:
+ type: string
+ format: email
+paths: {}
+`,
+ },
+ {
+ name: "string with const",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Status:
+ type: string
+ const: active
+paths: {}
+`,
+ },
+ {
+ name: "string with enum",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Status:
+ type: string
+ enum:
+ - active
+ - inactive
+paths: {}
+`,
+ },
+ {
+ name: "string with pattern",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ PhoneNumber:
+ type: string
+ pattern: '^\d{3}-\d{3}-\d{4}$'
+paths: {}
+`,
+ },
+ {
+ name: "non-string type without restrictions is ok",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Counter:
+ type: integer
+paths: {}
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspStringRestrictedRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+ assert.Empty(t, errs)
+ })
+ }
+}
+
+func TestOwaspStringRestrictedRule_Violations(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ expectedCount int
+ }{
+ {
+ name: "string without any restrictions",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ User:
+ type: object
+ properties:
+ name:
+ type: string
+paths: {}
+`,
+ expectedCount: 1,
+ },
+ {
+ name: "multiple strings without restrictions",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ User:
+ type: object
+ properties:
+ name:
+ type: string
+ email:
+ type: string
+ description:
+ type: string
+paths: {}
+`,
+ expectedCount: 3,
+ },
+ {
+ name: "inline string parameter without restrictions",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ parameters:
+ - name: search
+ in: query
+ schema:
+ type: string
+ responses:
+ '200':
+ description: Success
+`,
+ expectedCount: 1,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.OwaspStringRestrictedRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ require.Len(t, errs, tt.expectedCount)
+ for _, err := range errs {
+ assert.Contains(t, err.Error(), "must specify `format`, `const`, `enum`, or `pattern`")
+ }
+ })
+ }
+}
+
+func TestOwaspStringRestrictedRule_RuleMetadata(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.OwaspStringRestrictedRule{}
+
+ assert.Equal(t, "owasp-string-restricted", rule.ID())
+ assert.Equal(t, rules.CategorySecurity, rule.Category())
+ assert.NotEmpty(t, rule.Description())
+ assert.NotEmpty(t, rule.Link())
+ assert.Equal(t, validation.SeverityError, rule.DefaultSeverity())
+ assert.Equal(t, []string{"3.0", "3.1"}, rule.Versions())
+}
diff --git a/openapi/linter/rules/parameter_description.go b/openapi/linter/rules/parameter_description.go
new file mode 100644
index 00000000..386535ad
--- /dev/null
+++ b/openapi/linter/rules/parameter_description.go
@@ -0,0 +1,109 @@
+package rules
+
+import (
+ "context"
+ "fmt"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/validation"
+)
+
+const RuleStyleOAS3ParameterDescription = "style-oas3-parameter-description"
+
+type OAS3ParameterDescriptionRule struct{}
+
+func (r *OAS3ParameterDescriptionRule) ID() string {
+ return RuleStyleOAS3ParameterDescription
+}
+
+func (r *OAS3ParameterDescriptionRule) Description() string {
+ return "Parameters should include descriptions that explain their purpose and expected values. Clear parameter documentation helps developers understand how to construct valid requests and what each parameter controls."
+}
+
+func (r *OAS3ParameterDescriptionRule) Summary() string {
+ return "Parameters should include descriptions."
+}
+
+func (r *OAS3ParameterDescriptionRule) HowToFix() string {
+ return "Add descriptions to parameters that explain their purpose and expected values."
+}
+
+func (r *OAS3ParameterDescriptionRule) Category() string {
+ return CategoryStyle
+}
+
+func (r *OAS3ParameterDescriptionRule) DefaultSeverity() validation.Severity {
+ return validation.SeverityWarning
+}
+
+func (r *OAS3ParameterDescriptionRule) Link() string {
+ return "https://github.com/speakeasy-api/openapi/blob/main/openapi/linter/README.md#style-oas3-parameter-description"
+}
+
+func (r *OAS3ParameterDescriptionRule) Versions() []string {
+ return []string{"3.0.0", "3.0.1", "3.0.2", "3.0.3", "3.1.0", "3.1.1", "3.2.0"}
+}
+
+func (r *OAS3ParameterDescriptionRule) Run(ctx context.Context, docInfo *linter.DocumentInfo[*openapi.OpenAPI], config *linter.RuleConfig) []error {
+ if docInfo == nil || docInfo.Document == nil || docInfo.Index == nil {
+ return nil
+ }
+
+ doc := docInfo.Document
+ var errs []error
+
+ // Check only inline parameters (component parameters are checked by component_description rule)
+ for _, paramNode := range docInfo.Index.InlineParameters {
+ refParam := paramNode.Node
+ if refParam == nil {
+ continue
+ }
+
+ param := refParam.GetObject()
+ if param == nil {
+ continue
+ }
+
+ description := param.GetDescription()
+ if description == "" {
+ paramName := param.GetName()
+
+ // Extract method and path manually from location
+ var method, path string
+ for _, loc := range paramNode.Location {
+ switch openapi.GetParentType(loc) {
+ case "Paths":
+ if loc.ParentKey != nil {
+ path = *loc.ParentKey
+ }
+ case "PathItem":
+ if loc.ParentKey != nil {
+ method = *loc.ParentKey
+ }
+ }
+ }
+
+ errNode := GetFieldValueNode(param, "description", doc)
+ if errNode == nil {
+ errNode = param.GetRootNode()
+ }
+
+ var msg string
+ if method != "" && path != "" {
+ msg = fmt.Sprintf("parameter `%s` in `%s %s` is missing a description", paramName, method, path)
+ } else {
+ msg = fmt.Sprintf("parameter `%s` is missing a description", paramName)
+ }
+
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleStyleOAS3ParameterDescription,
+ fmt.Errorf("%s", msg),
+ errNode,
+ ))
+ }
+ }
+
+ return errs
+}
diff --git a/openapi/linter/rules/parameter_description_test.go b/openapi/linter/rules/parameter_description_test.go
new file mode 100644
index 00000000..f118d6d7
--- /dev/null
+++ b/openapi/linter/rules/parameter_description_test.go
@@ -0,0 +1,181 @@
+package rules_test
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/openapi/linter/rules"
+ "github.com/speakeasy-api/openapi/references"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestOAS3ParameterDescriptionRule_ValidCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "path parameter with description",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{id}:
+ get:
+ parameters:
+ - name: id
+ in: path
+ required: true
+ description: The user ID
+ schema:
+ type: string
+`,
+ },
+ {
+ name: "query parameter with description",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ parameters:
+ - name: limit
+ in: query
+ description: Maximum number of results
+ schema:
+ type: integer
+`,
+ },
+ {
+ name: "no parameters",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get: {}
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err, "unmarshal should succeed")
+
+ rule := &rules.OAS3ParameterDescriptionRule{}
+ config := &linter.RuleConfig{}
+
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+ assert.Empty(t, errs, "should have no lint errors")
+ })
+ }
+}
+
+func TestOAS3ParameterDescriptionRule_Violations(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ expectedError string
+ }{
+ {
+ name: "path parameter missing description",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{id}:
+ get:
+ parameters:
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
+`,
+ expectedError: "parameter `id` in `get /users/{id}` is missing a description",
+ },
+ {
+ name: "query parameter missing description",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ parameters:
+ - name: limit
+ in: query
+ schema:
+ type: integer
+`,
+ expectedError: "parameter `limit` in `get /users` is missing a description",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err, "unmarshal should succeed")
+
+ rule := &rules.OAS3ParameterDescriptionRule{}
+ config := &linter.RuleConfig{}
+
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+ require.NotEmpty(t, errs, "should have lint errors")
+ assert.Contains(t, errs[0].Error(), tt.expectedError, "error message should contain expected text")
+ })
+ }
+}
+
+func TestOAS3ParameterDescriptionRule_RuleMetadata(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.OAS3ParameterDescriptionRule{}
+
+ assert.Equal(t, "style-oas3-parameter-description", rule.ID())
+ assert.Equal(t, rules.CategoryStyle, rule.Category())
+ assert.NotEmpty(t, rule.Description())
+ assert.NotEmpty(t, rule.Link())
+ assert.Equal(t, validation.SeverityWarning, rule.DefaultSeverity())
+ assert.NotNil(t, rule.Versions())
+}
diff --git a/openapi/linter/rules/path_declarations.go b/openapi/linter/rules/path_declarations.go
new file mode 100644
index 00000000..25b60693
--- /dev/null
+++ b/openapi/linter/rules/path_declarations.go
@@ -0,0 +1,58 @@
+package rules
+
+import (
+ "context"
+ "fmt"
+ "strings"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/validation"
+)
+
+const RuleSemanticPathDeclarations = "semantic-path-declarations"
+
+type PathDeclarationsRule struct{}
+
+func (r *PathDeclarationsRule) ID() string { return RuleSemanticPathDeclarations }
+func (r *PathDeclarationsRule) Category() string { return CategorySemantic }
+func (r *PathDeclarationsRule) Description() string {
+ return "Path parameter declarations must not be empty - declarations like /api/{} are invalid. Empty path parameters create ambiguous routes and will cause runtime errors in most API frameworks."
+}
+func (r *PathDeclarationsRule) Summary() string {
+ return "Path parameter declarations must not be empty."
+}
+func (r *PathDeclarationsRule) HowToFix() string {
+ return "Replace empty path parameters with named ones (e.g., /items/{itemId})."
+}
+func (r *PathDeclarationsRule) Link() string {
+ return "https://github.com/speakeasy-api/openapi/blob/main/openapi/linter/README.md#semantic-path-declarations"
+}
+func (r *PathDeclarationsRule) DefaultSeverity() validation.Severity {
+ return validation.SeverityError
+}
+func (r *PathDeclarationsRule) Versions() []string {
+ return nil // Applies to all OpenAPI versions
+}
+
+func (r *PathDeclarationsRule) Run(ctx context.Context, docInfo *linter.DocumentInfo[*openapi.OpenAPI], config *linter.RuleConfig) []error {
+ var errs []error
+
+ doc := docInfo.Document
+
+ // Check each path for empty parameter declarations
+ for pathKey := range doc.GetPaths().All() {
+ if strings.Contains(pathKey, "{}") {
+ node := doc.GetPaths().GetCore().GetMapKeyNodeOrRoot(pathKey, doc.GetPaths().GetRootNode())
+
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleSemanticPathDeclarations,
+ fmt.Errorf("path %q contains empty parameter declaration `{}`", pathKey),
+ node,
+ ))
+ }
+ }
+
+ return errs
+}
diff --git a/openapi/linter/rules/path_declarations_test.go b/openapi/linter/rules/path_declarations_test.go
new file mode 100644
index 00000000..b8a663ed
--- /dev/null
+++ b/openapi/linter/rules/path_declarations_test.go
@@ -0,0 +1,229 @@
+package rules_test
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/openapi/linter/rules"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestPathDeclarationsRule_ValidCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "valid single parameter",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{userId}:
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ },
+ {
+ name: "valid multiple parameters",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{userId}/posts/{postId}:
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ },
+ {
+ name: "no parameters",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ },
+ {
+ name: "parameter with underscores",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{user_id}:
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ },
+ {
+ name: "parameter with hyphens",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{user-id}:
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err, "unmarshal should succeed")
+
+ rule := &rules.PathDeclarationsRule{}
+ config := &linter.RuleConfig{}
+
+ docInfo := &linter.DocumentInfo[*openapi.OpenAPI]{
+ Document: doc,
+ }
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ assert.Empty(t, errs, "should have no lint errors")
+ })
+ }
+}
+
+func TestPathDeclarationsRule_EmptyDeclarations(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ expectedError string
+ }{
+ {
+ name: "single empty declaration",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /api/{}:
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ expectedError: "[7:3] error semantic-path-declarations path \"/api/{}\" contains empty parameter declaration `{}`",
+ },
+ {
+ name: "empty declaration in middle of path",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /api/{}/users:
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ expectedError: "[7:3] error semantic-path-declarations path \"/api/{}/users\" contains empty parameter declaration `{}`",
+ },
+ {
+ name: "multiple empty declarations",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /api/{}/{}/users:
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ expectedError: "[7:3] error semantic-path-declarations path \"/api/{}/{}/users\" contains empty parameter declaration `{}`",
+ },
+ {
+ name: "empty declaration with valid parameter",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /api/{userId}/{}:
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ expectedError: "[7:3] error semantic-path-declarations path \"/api/{userId}/{}\" contains empty parameter declaration `{}`",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err, "unmarshal should succeed")
+
+ rule := &rules.PathDeclarationsRule{}
+ config := &linter.RuleConfig{}
+
+ docInfo := &linter.DocumentInfo[*openapi.OpenAPI]{
+ Document: doc,
+ }
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ require.Len(t, errs, 1, "should have one lint error")
+ assert.Equal(t, tt.expectedError, errs[0].Error(), "error message should match exactly")
+ })
+ }
+}
+
+func TestPathDeclarationsRule_RuleMetadata(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.PathDeclarationsRule{}
+
+ assert.Equal(t, "semantic-path-declarations", rule.ID())
+ assert.Equal(t, rules.CategorySemantic, rule.Category())
+ assert.NotEmpty(t, rule.Description())
+ assert.NotEmpty(t, rule.Link())
+ assert.Equal(t, validation.SeverityError, rule.DefaultSeverity())
+ assert.Nil(t, rule.Versions())
+}
diff --git a/openapi/linter/rules/path_params.go b/openapi/linter/rules/path_params.go
new file mode 100644
index 00000000..459679e5
--- /dev/null
+++ b/openapi/linter/rules/path_params.go
@@ -0,0 +1,186 @@
+package rules
+
+import (
+ "context"
+ "fmt"
+ "regexp"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/validation"
+)
+
+const RuleSemanticPathParams = "semantic-path-params"
+
+type PathParamsRule struct{}
+
+func (r *PathParamsRule) ID() string { return RuleSemanticPathParams }
+func (r *PathParamsRule) Category() string { return CategorySemantic }
+func (r *PathParamsRule) Description() string {
+ return "Path template variables like {userId} must have corresponding parameter definitions with in='path', and declared path parameters must be used in the URL template. This ensures request routing works correctly and all path variables are properly documented. Parameters can be defined at PathItem level (inherited by all operations) or Operation level (can override PathItem parameters)."
+}
+func (r *PathParamsRule) Summary() string {
+ return "Path template variables must have matching path parameters and vice versa."
+}
+func (r *PathParamsRule) HowToFix() string {
+ return "Ensure every {param} in the path has an in: path parameter and remove any unused path parameters."
+}
+func (r *PathParamsRule) Link() string {
+ return "https://github.com/speakeasy-api/openapi/blob/main/openapi/linter/README.md#semantic-path-params"
+}
+func (r *PathParamsRule) DefaultSeverity() validation.Severity {
+ return validation.SeverityError
+}
+func (r *PathParamsRule) Versions() []string {
+ return nil // Applies to all OpenAPI versions
+}
+
+var pathParamRegex = regexp.MustCompile(`\{([^}]+)\}`)
+
+func (r *PathParamsRule) Run(ctx context.Context, docInfo *linter.DocumentInfo[*openapi.OpenAPI], config *linter.RuleConfig) []error {
+ if docInfo == nil || docInfo.Document == nil || docInfo.Index == nil {
+ return nil
+ }
+
+ var errs []error
+
+ doc := docInfo.Document
+
+ // Build resolve options from config
+ resolveOpts := openapi.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: docInfo.Location,
+ }
+ if config.ResolveOptions != nil {
+ resolveOpts.VirtualFS = config.ResolveOptions.VirtualFS
+ resolveOpts.HTTPClient = config.ResolveOptions.HTTPClient
+ resolveOpts.DisableExternalRefs = config.ResolveOptions.DisableExternalRefs
+ }
+
+ // Use the pre-computed InlinePathItems index (path items from /paths)
+ // These are the only ones with path templates in their location parent key
+ for _, pathItemNode := range docInfo.Index.InlinePathItems {
+ refPathItem := pathItemNode.Node
+
+ // Extract path from location (parent key of the path item)
+ path := pathItemNode.Location.ParentKey()
+ if path == "" {
+ continue
+ }
+
+ pathItem := refPathItem.GetObject()
+ if pathItem == nil {
+ continue
+ }
+
+ templateParams := extractParamsFromPath(path)
+
+ // Get PathItem parameters (in: path)
+ pathItemParams, pathItemErrs := getPathParameters(ctx, pathItem.Parameters, resolveOpts, config)
+ errs = append(errs, pathItemErrs...)
+
+ // Iterate operations
+ for _, op := range pathItem.All() {
+ // Merge parameters
+ opParams, opErrs := getPathParameters(ctx, op.Parameters, resolveOpts, config)
+ errs = append(errs, opErrs...)
+ effectiveParams := mergeParameters(pathItemParams, opParams)
+
+ // Validate
+ // 1. All template params must be in effectiveParams
+ for _, tmplParam := range templateParams {
+ if _, ok := effectiveParams[tmplParam]; !ok {
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleSemanticPathParams,
+ fmt.Errorf("path parameter `{%s}` is not defined in operation parameters", tmplParam),
+ op.GetRootNode(),
+ ))
+ }
+ }
+
+ // 2. All effectiveParams must be in template params
+ for paramName := range effectiveParams {
+ found := false
+ for _, tmplParam := range templateParams {
+ if tmplParam == paramName {
+ found = true
+ break
+ }
+ }
+ if !found {
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleSemanticPathParams,
+ fmt.Errorf("parameter `%s` is declared as path parameter but not used in path template `%s`", paramName, path),
+ op.GetRootNode(),
+ ))
+ }
+ }
+ }
+ }
+
+ return errs
+}
+
+func extractParamsFromPath(path string) []string {
+ matches := pathParamRegex.FindAllStringSubmatch(path, -1)
+ var params []string
+ for _, match := range matches {
+ if len(match) > 1 {
+ params = append(params, match[1])
+ }
+ }
+ return params
+}
+
+func getPathParameters(ctx context.Context, params []*openapi.ReferencedParameter, resolveOpts openapi.ResolveOptions, _ *linter.RuleConfig) (map[string]bool, []error) {
+ result := make(map[string]bool)
+ var resolutionErrs []error
+
+ for _, refParam := range params {
+ if refParam == nil {
+ continue
+ }
+
+ // Resolve reference if needed
+ if refParam.IsReference() && !refParam.IsResolved() {
+ validErrs, err := refParam.Resolve(ctx, resolveOpts)
+ if err != nil {
+ // Resolution failed - report as validation error
+ resolutionErrs = append(resolutionErrs, validation.NewValidationError(
+ validation.SeverityError,
+ RuleSemanticPathParams,
+ fmt.Errorf("failed to resolve parameter reference `%s`: %w", refParam.GetReference(), err),
+ refParam.GetRootNode(),
+ ))
+ continue
+ }
+ // Append any validation errors from resolution
+ resolutionErrs = append(resolutionErrs, validErrs...)
+ }
+
+ // GetObject() returns the resolved object for references, or inline object
+ param := refParam.GetObject()
+ if param == nil {
+ continue
+ }
+
+ if param.In == "path" {
+ result[param.Name] = true
+ }
+ }
+ return result, resolutionErrs
+}
+
+func mergeParameters(base, override map[string]bool) map[string]bool {
+ result := make(map[string]bool)
+ for k, v := range base {
+ result[k] = v
+ }
+ for k, v := range override {
+ result[k] = v
+ }
+ return result
+}
diff --git a/openapi/linter/rules/path_params_test.go b/openapi/linter/rules/path_params_test.go
new file mode 100644
index 00000000..ac22483a
--- /dev/null
+++ b/openapi/linter/rules/path_params_test.go
@@ -0,0 +1,1006 @@
+package rules_test
+
+import (
+ "context"
+ "fmt"
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "testing"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/openapi/linter/rules"
+ "github.com/speakeasy-api/openapi/references"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+// Helper function to create DocumentInfo with Index
+func createDocInfoWithIndex(t *testing.T, ctx context.Context, doc *openapi.OpenAPI, location string) *linter.DocumentInfo[*openapi.OpenAPI] {
+ t.Helper()
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: location,
+ })
+ return linter.NewDocumentInfoWithIndex(doc, location, idx)
+}
+
+func TestPathParamsRule_ValidCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "single path param in operation",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{userId}:
+ get:
+ parameters:
+ - name: userId
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: ok
+`,
+ },
+ {
+ name: "path param defined at path item level",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{userId}:
+ parameters:
+ - name: userId
+ in: path
+ required: true
+ schema:
+ type: string
+ get:
+ responses:
+ '200':
+ description: ok
+ post:
+ responses:
+ '201':
+ description: created
+`,
+ },
+ {
+ name: "multiple path params",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{userId}/posts/{postId}:
+ get:
+ parameters:
+ - name: userId
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: postId
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: ok
+`,
+ },
+ {
+ name: "deeply nested path params",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /orgs/{orgId}/teams/{teamId}/members/{memberId}:
+ get:
+ parameters:
+ - name: orgId
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: teamId
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: memberId
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: ok
+`,
+ },
+ {
+ name: "path param override at operation level",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{userId}:
+ parameters:
+ - name: userId
+ in: path
+ required: true
+ schema:
+ type: string
+ get:
+ parameters:
+ - name: userId
+ in: path
+ required: true
+ schema:
+ type: integer
+ responses:
+ '200':
+ description: ok
+`,
+ },
+ {
+ name: "mixed path item and operation params",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{userId}/posts/{postId}:
+ parameters:
+ - name: userId
+ in: path
+ required: true
+ schema:
+ type: string
+ get:
+ parameters:
+ - name: postId
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: ok
+`,
+ },
+ {
+ name: "multiple operations sharing path item params",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{userId}:
+ parameters:
+ - name: userId
+ in: path
+ required: true
+ schema:
+ type: string
+ get:
+ responses:
+ '200':
+ description: ok
+ put:
+ responses:
+ '200':
+ description: ok
+ delete:
+ responses:
+ '204':
+ description: deleted
+`,
+ },
+ {
+ name: "path without template params",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ },
+ {
+ name: "query param ignored for path validation",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ parameters:
+ - name: filter
+ in: query
+ schema:
+ type: string
+ responses:
+ '200':
+ description: ok
+`,
+ },
+ {
+ name: "header param ignored for path validation",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ parameters:
+ - name: X-Request-Id
+ in: header
+ schema:
+ type: string
+ responses:
+ '200':
+ description: ok
+`,
+ },
+ {
+ name: "referenced parameter from components",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{userId}:
+ get:
+ parameters:
+ - $ref: '#/components/parameters/UserId'
+ responses:
+ '200':
+ description: ok
+components:
+ parameters:
+ UserId:
+ name: userId
+ in: path
+ required: true
+ schema:
+ type: string
+`,
+ },
+ {
+ name: "referenced path item from components",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{userId}:
+ $ref: '#/components/pathItems/UserPath'
+components:
+ pathItems:
+ UserPath:
+ parameters:
+ - name: userId
+ in: path
+ required: true
+ schema:
+ type: string
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ },
+ {
+ name: "path item ref with params defined in operations",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{userId}:
+ $ref: '#/components/pathItems/UserPath'
+components:
+ pathItems:
+ UserPath:
+ get:
+ parameters:
+ - name: userId
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: ok
+`,
+ },
+ {
+ name: "mixed inline and referenced parameters",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{userId}/posts/{postId}:
+ get:
+ parameters:
+ - $ref: '#/components/parameters/UserId'
+ - name: postId
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: ok
+components:
+ parameters:
+ UserId:
+ name: userId
+ in: path
+ required: true
+ schema:
+ type: string
+`,
+ },
+ {
+ name: "path item level ref param inherited by multiple ops",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{userId}:
+ parameters:
+ - $ref: '#/components/parameters/UserId'
+ get:
+ responses:
+ '200':
+ description: ok
+ delete:
+ responses:
+ '204':
+ description: deleted
+components:
+ parameters:
+ UserId:
+ name: userId
+ in: path
+ required: true
+ schema:
+ type: string
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err, "unmarshal should succeed")
+
+ rule := &rules.PathParamsRule{}
+ config := &linter.RuleConfig{}
+
+ docInfo := createDocInfoWithIndex(t, ctx, doc, "test.yaml")
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ assert.Empty(t, errs, "should have no lint errors")
+ })
+ }
+}
+
+func TestPathParamsRule_MissingPathParam(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ expectedErrors []string
+ }{
+ {
+ name: "missing single path param",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{userId}:
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ expectedErrors: []string{
+ "[9:7] error semantic-path-params path parameter `{userId}` is not defined in operation parameters",
+ },
+ },
+ {
+ name: "missing one of multiple path params",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{userId}/posts/{postId}:
+ get:
+ parameters:
+ - name: userId
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: ok
+`,
+ expectedErrors: []string{
+ "[9:7] error semantic-path-params path parameter `{postId}` is not defined in operation parameters",
+ },
+ },
+ {
+ name: "missing all path params",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{userId}/posts/{postId}:
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ expectedErrors: []string{
+ "[9:7] error semantic-path-params path parameter `{userId}` is not defined in operation parameters",
+ "[9:7] error semantic-path-params path parameter `{postId}` is not defined in operation parameters",
+ },
+ },
+ {
+ name: "missing path param in one operation but not another",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{userId}:
+ get:
+ parameters:
+ - name: userId
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: ok
+ post:
+ responses:
+ '201':
+ description: created
+`,
+ expectedErrors: []string{
+ "[19:7] error semantic-path-params path parameter `{userId}` is not defined in operation parameters",
+ },
+ },
+ {
+ name: "case sensitive param names",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{userId}:
+ get:
+ parameters:
+ - name: userid
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: ok
+`,
+ expectedErrors: []string{
+ "[9:7] error semantic-path-params path parameter `{userId}` is not defined in operation parameters",
+ "[9:7] error semantic-path-params parameter `userid` is declared as path parameter but not used in path template `/users/{userId}`",
+ },
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err, "unmarshal should succeed")
+
+ rule := &rules.PathParamsRule{}
+ config := &linter.RuleConfig{}
+
+ docInfo := createDocInfoWithIndex(t, ctx, doc, "test.yaml")
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ var errMsgs []string
+ for _, err := range errs {
+ errMsgs = append(errMsgs, err.Error())
+ }
+
+ assert.ElementsMatch(t, tt.expectedErrors, errMsgs)
+ })
+ }
+}
+
+func TestPathParamsRule_UnusedPathParam(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ expectedErrors []string
+ }{
+ {
+ name: "unused single path param",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ parameters:
+ - name: userId
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: ok
+`,
+ expectedErrors: []string{
+ "[9:7] error semantic-path-params parameter `userId` is declared as path parameter but not used in path template `/users`",
+ },
+ },
+ {
+ name: "unused path param at path item level",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ parameters:
+ - name: userId
+ in: path
+ required: true
+ schema:
+ type: string
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ expectedErrors: []string{
+ "[15:7] error semantic-path-params parameter `userId` is declared as path parameter but not used in path template `/users`",
+ },
+ },
+ {
+ name: "one used one unused path param",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{userId}:
+ get:
+ parameters:
+ - name: userId
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: postId
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: ok
+`,
+ expectedErrors: []string{
+ "[9:7] error semantic-path-params parameter `postId` is declared as path parameter but not used in path template `/users/{userId}`",
+ },
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err, "unmarshal should succeed")
+
+ rule := &rules.PathParamsRule{}
+ config := &linter.RuleConfig{}
+
+ docInfo := createDocInfoWithIndex(t, ctx, doc, "test.yaml")
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ var errMsgs []string
+ for _, err := range errs {
+ errMsgs = append(errMsgs, err.Error())
+ }
+
+ assert.ElementsMatch(t, tt.expectedErrors, errMsgs)
+ })
+ }
+}
+
+func TestPathParamsRule_RuleMetadata(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.PathParamsRule{}
+
+ assert.Equal(t, "semantic-path-params", rule.ID(), "rule ID should match")
+ assert.Equal(t, rules.CategorySemantic, rule.Category(), "rule category should match")
+ assert.NotEmpty(t, rule.Description(), "rule should have description")
+ assert.Equal(t, validation.SeverityError, rule.DefaultSeverity(), "default severity should be error")
+ assert.Nil(t, rule.Versions(), "versions should be nil (all versions)")
+}
+
+func TestPathParamsRule_SeverityOverride(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ yamlInput := `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{userId}:
+ get:
+ responses:
+ '200':
+ description: ok
+`
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(yamlInput))
+ require.NoError(t, err, "unmarshal should succeed")
+
+ rule := &rules.PathParamsRule{}
+ warningSeverity := validation.SeverityWarning
+ config := &linter.RuleConfig{
+ Severity: &warningSeverity,
+ }
+
+ docInfo := createDocInfoWithIndex(t, ctx, doc, "test.yaml")
+
+ errs := rule.Run(ctx, docInfo, config)
+ require.Len(t, errs, 1, "should have one error")
+
+ // Check full error string includes warning severity
+ assert.Equal(t, "[9:7] warning semantic-path-params path parameter `{userId}` is not defined in operation parameters", errs[0].Error())
+}
+
+func TestPathParamsRule_ExternalReferenceResolution(t *testing.T) {
+ t.Parallel()
+
+ t.Run("external reference to parameter resolved successfully", func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ // Create a mock HTTP server for this test
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ switch r.URL.Path {
+ case "/params/user-id.yaml":
+ w.Header().Set("Content-Type", "application/yaml")
+ w.WriteHeader(http.StatusOK)
+ _, _ = w.Write([]byte(`
+name: userId
+in: path
+required: true
+schema:
+ type: string
+`))
+ default:
+ w.WriteHeader(http.StatusNotFound)
+ }
+ }))
+ defer server.Close()
+
+ yamlInput := fmt.Sprintf(`openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{userId}:
+ get:
+ parameters:
+ - $ref: "%s/params/user-id.yaml"
+ responses:
+ "200":
+ description: ok
+`, server.URL)
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(yamlInput))
+ require.NoError(t, err, "unmarshal should succeed")
+
+ rule := &rules.PathParamsRule{}
+ config := &linter.RuleConfig{}
+
+ docInfo := createDocInfoWithIndex(t, ctx, doc, server.URL+"/openapi.yaml")
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ // Should have no errors because the external reference resolves to a valid path param
+ assert.Empty(t, errs, "should have no lint errors when external ref is resolved")
+ })
+
+ t.Run("multiple external references resolved", func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ // Create a mock HTTP server for this test
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ switch r.URL.Path {
+ case "/params/user-id.yaml":
+ w.Header().Set("Content-Type", "application/yaml")
+ w.WriteHeader(http.StatusOK)
+ _, _ = w.Write([]byte(`
+name: userId
+in: path
+required: true
+schema:
+ type: string
+`))
+ case "/params/post-id.yaml":
+ w.Header().Set("Content-Type", "application/yaml")
+ w.WriteHeader(http.StatusOK)
+ _, _ = w.Write([]byte(`
+name: postId
+in: path
+required: true
+schema:
+ type: string
+`))
+ default:
+ w.WriteHeader(http.StatusNotFound)
+ }
+ }))
+ defer server.Close()
+
+ yamlInput := fmt.Sprintf(`openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{userId}/posts/{postId}:
+ get:
+ parameters:
+ - $ref: "%s/params/user-id.yaml"
+ - $ref: "%s/params/post-id.yaml"
+ responses:
+ "200":
+ description: ok
+`, server.URL, server.URL)
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(yamlInput))
+ require.NoError(t, err, "unmarshal should succeed")
+
+ rule := &rules.PathParamsRule{}
+ config := &linter.RuleConfig{}
+
+ docInfo := createDocInfoWithIndex(t, ctx, doc, server.URL+"/openapi.yaml")
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ // Should have no errors - both path params are defined via external refs
+ assert.Empty(t, errs, "should have no lint errors when all external refs resolve")
+ })
+
+ t.Run("missing path param detected even with external references", func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ // Create a mock HTTP server for this test
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ switch r.URL.Path {
+ case "/params/user-id.yaml":
+ w.Header().Set("Content-Type", "application/yaml")
+ w.WriteHeader(http.StatusOK)
+ _, _ = w.Write([]byte(`
+name: userId
+in: path
+required: true
+schema:
+ type: string
+`))
+ default:
+ w.WriteHeader(http.StatusNotFound)
+ }
+ }))
+ defer server.Close()
+
+ yamlInput := fmt.Sprintf(`openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{userId}/posts/{postId}:
+ get:
+ parameters:
+ - $ref: "%s/params/user-id.yaml"
+ responses:
+ "200":
+ description: ok
+`, server.URL)
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(yamlInput))
+ require.NoError(t, err, "unmarshal should succeed")
+
+ rule := &rules.PathParamsRule{}
+ config := &linter.RuleConfig{}
+
+ docInfo := createDocInfoWithIndex(t, ctx, doc, server.URL+"/openapi.yaml")
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ // Should have one error - postId is not defined
+ require.Len(t, errs, 1, "should have one lint error for missing postId")
+ assert.Contains(t, errs[0].Error(), "postId", "error should mention postId")
+ })
+
+ t.Run("resolution error reported when external reference fails", func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ // Create a mock HTTP server that returns 404
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ w.WriteHeader(http.StatusNotFound)
+ }))
+ defer server.Close()
+
+ yamlInput := fmt.Sprintf(`openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{userId}:
+ get:
+ parameters:
+ - $ref: "%s/params/missing.yaml"
+ responses:
+ "200":
+ description: ok
+`, server.URL)
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(yamlInput))
+ require.NoError(t, err, "unmarshal should succeed")
+
+ rule := &rules.PathParamsRule{}
+ config := &linter.RuleConfig{}
+
+ docInfo := createDocInfoWithIndex(t, ctx, doc, server.URL+"/openapi.yaml")
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ // Should have errors for both resolution failure and missing param
+ require.NotEmpty(t, errs, "should have errors when resolution fails")
+
+ // Check that we have a resolution error
+ var foundResolutionError bool
+ for _, err := range errs {
+ if strings.Contains(err.Error(), "failed to resolve parameter reference") {
+ foundResolutionError = true
+ break
+ }
+ }
+ assert.True(t, foundResolutionError, "should report resolution error")
+ })
+
+ t.Run("resolution error for invalid yaml content", func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ // Create a mock HTTP server that returns invalid YAML
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ switch r.URL.Path {
+ case "/params/invalid.yaml":
+ w.Header().Set("Content-Type", "application/yaml")
+ w.WriteHeader(http.StatusOK)
+ _, _ = w.Write([]byte(`this is not valid: yaml: content: [unclosed`))
+ default:
+ w.WriteHeader(http.StatusNotFound)
+ }
+ }))
+ defer server.Close()
+
+ yamlInput := fmt.Sprintf(`openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{userId}:
+ get:
+ parameters:
+ - $ref: "%s/params/invalid.yaml"
+ responses:
+ "200":
+ description: ok
+`, server.URL)
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(yamlInput))
+ require.NoError(t, err, "unmarshal should succeed")
+
+ rule := &rules.PathParamsRule{}
+ config := &linter.RuleConfig{}
+
+ docInfo := createDocInfoWithIndex(t, ctx, doc, server.URL+"/openapi.yaml")
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ // Should have a resolution error for invalid YAML
+ require.NotEmpty(t, errs, "should have errors when YAML is invalid")
+
+ var foundResolutionError bool
+ for _, err := range errs {
+ if strings.Contains(err.Error(), "failed to resolve parameter reference") {
+ foundResolutionError = true
+ break
+ }
+ }
+ assert.True(t, foundResolutionError, "should report resolution error for invalid YAML")
+ })
+}
diff --git a/openapi/linter/rules/path_query.go b/openapi/linter/rules/path_query.go
new file mode 100644
index 00000000..a324d0be
--- /dev/null
+++ b/openapi/linter/rules/path_query.go
@@ -0,0 +1,58 @@
+package rules
+
+import (
+ "context"
+ "fmt"
+ "strings"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/validation"
+)
+
+const RuleSemanticPathQuery = "semantic-path-query"
+
+type PathQueryRule struct{}
+
+func (r *PathQueryRule) ID() string { return RuleSemanticPathQuery }
+func (r *PathQueryRule) Category() string { return CategorySemantic }
+func (r *PathQueryRule) Description() string {
+ return "Paths must not include query strings - query parameters should be defined in the parameters array instead. Including query strings in paths creates ambiguity, breaks code generation, and violates OpenAPI specification structure."
+}
+func (r *PathQueryRule) Summary() string {
+ return "Paths must not include query strings."
+}
+func (r *PathQueryRule) HowToFix() string {
+ return "Remove query strings from path keys and define them as query parameters instead."
+}
+func (r *PathQueryRule) Link() string {
+ return "https://github.com/speakeasy-api/openapi/blob/main/openapi/linter/README.md#semantic-path-query"
+}
+func (r *PathQueryRule) DefaultSeverity() validation.Severity {
+ return validation.SeverityError
+}
+func (r *PathQueryRule) Versions() []string {
+ return nil // Applies to all OpenAPI versions
+}
+
+func (r *PathQueryRule) Run(ctx context.Context, docInfo *linter.DocumentInfo[*openapi.OpenAPI], config *linter.RuleConfig) []error {
+ var errs []error
+
+ doc := docInfo.Document
+
+ // Check each path for query strings
+ for pathKey := range doc.GetPaths().All() {
+ if strings.Contains(pathKey, "?") {
+ node := doc.GetPaths().GetCore().GetMapKeyNodeOrRoot(pathKey, doc.GetPaths().GetRootNode())
+
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleSemanticPathQuery,
+ fmt.Errorf("path %q contains query string - use parameters array instead", pathKey),
+ node,
+ ))
+ }
+ }
+
+ return errs
+}
diff --git a/openapi/linter/rules/path_query_test.go b/openapi/linter/rules/path_query_test.go
new file mode 100644
index 00000000..252b24eb
--- /dev/null
+++ b/openapi/linter/rules/path_query_test.go
@@ -0,0 +1,161 @@
+package rules_test
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/openapi/linter/rules"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestPathQueryRule_ValidCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "no query string",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ },
+ {
+ name: "path with parameters but no query",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{userId}:
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.PathQueryRule{}
+ config := &linter.RuleConfig{}
+ docInfo := &linter.DocumentInfo[*openapi.OpenAPI]{Document: doc}
+
+ errs := rule.Run(ctx, docInfo, config)
+ assert.Empty(t, errs)
+ })
+ }
+}
+
+func TestPathQueryRule_QueryInPath(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ expectedError string
+ }{
+ {
+ name: "query string at end",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users?filter=active:
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ expectedError: `[7:3] error semantic-path-query path "/users?filter=active" contains query string - use parameters array instead`,
+ },
+ {
+ name: "query string with parameter",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{id}?include=details:
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ expectedError: `[7:3] error semantic-path-query path "/users/{id}?include=details" contains query string - use parameters array instead`,
+ },
+ {
+ name: "single question mark at end",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users?:
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ expectedError: `[7:3] error semantic-path-query path "/users?" contains query string - use parameters array instead`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.PathQueryRule{}
+ config := &linter.RuleConfig{}
+ docInfo := &linter.DocumentInfo[*openapi.OpenAPI]{Document: doc}
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ require.Len(t, errs, 1)
+ assert.Equal(t, tt.expectedError, errs[0].Error())
+ })
+ }
+}
+
+func TestPathQueryRule_RuleMetadata(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.PathQueryRule{}
+
+ assert.Equal(t, "semantic-path-query", rule.ID())
+ assert.Equal(t, rules.CategorySemantic, rule.Category())
+ assert.NotEmpty(t, rule.Description())
+ assert.NotEmpty(t, rule.Link())
+ assert.Equal(t, validation.SeverityError, rule.DefaultSeverity())
+ assert.Nil(t, rule.Versions())
+}
diff --git a/openapi/linter/rules/path_trailing_slash.go b/openapi/linter/rules/path_trailing_slash.go
new file mode 100644
index 00000000..87a5aabe
--- /dev/null
+++ b/openapi/linter/rules/path_trailing_slash.go
@@ -0,0 +1,64 @@
+package rules
+
+import (
+ "context"
+ "fmt"
+ "strings"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/validation"
+)
+
+const RuleStylePathTrailingSlash = "style-path-trailing-slash"
+
+type PathTrailingSlashRule struct{}
+
+func (r *PathTrailingSlashRule) ID() string { return RuleStylePathTrailingSlash }
+func (r *PathTrailingSlashRule) Category() string { return CategoryStyle }
+func (r *PathTrailingSlashRule) Description() string {
+ return "Path definitions should not end with a trailing slash to maintain consistency and avoid routing ambiguity. Trailing slashes in paths can cause mismatches with server routing rules and create duplicate endpoint definitions."
+}
+func (r *PathTrailingSlashRule) Summary() string {
+ return "Paths should not end with a trailing slash."
+}
+func (r *PathTrailingSlashRule) HowToFix() string {
+ return "Remove trailing slashes from path keys (except the root '/')."
+}
+func (r *PathTrailingSlashRule) Link() string {
+ return "https://github.com/speakeasy-api/openapi/blob/main/openapi/linter/README.md#style-path-trailing-slash"
+}
+func (r *PathTrailingSlashRule) DefaultSeverity() validation.Severity {
+ return validation.SeverityWarning
+}
+func (r *PathTrailingSlashRule) Versions() []string {
+ return nil // Applies to all OpenAPI versions
+}
+
+func (r *PathTrailingSlashRule) Run(ctx context.Context, docInfo *linter.DocumentInfo[*openapi.OpenAPI], config *linter.RuleConfig) []error {
+ if docInfo == nil || docInfo.Document == nil {
+ return nil
+ }
+
+ var errs []error
+ doc := docInfo.Document
+
+ paths := doc.GetPaths()
+ if paths == nil {
+ return nil
+ }
+
+ for pathKey := range paths.All() {
+ if strings.HasSuffix(pathKey, "/") && pathKey != "/" {
+ node := paths.GetCore().GetMapKeyNodeOrRoot(pathKey, paths.GetRootNode())
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleStylePathTrailingSlash,
+ fmt.Errorf("path `%s` must not end with a trailing slash", pathKey),
+ node,
+ ))
+ }
+ }
+
+ return errs
+}
diff --git a/openapi/linter/rules/path_trailing_slash_test.go b/openapi/linter/rules/path_trailing_slash_test.go
new file mode 100644
index 00000000..dd93c0a1
--- /dev/null
+++ b/openapi/linter/rules/path_trailing_slash_test.go
@@ -0,0 +1,160 @@
+package rules_test
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/openapi/linter/rules"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestPathTrailingSlashRule_ValidCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "path without trailing slash",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users:
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ },
+ {
+ name: "root path",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /:
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ },
+ {
+ name: "path with parameters",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{id}:
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.PathTrailingSlashRule{}
+ config := &linter.RuleConfig{}
+ docInfo := linter.NewDocumentInfo(doc, "test.yaml")
+
+ errs := rule.Run(ctx, docInfo, config)
+ assert.Empty(t, errs)
+ })
+ }
+}
+
+func TestPathTrailingSlashRule_Violations(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ expectedError string
+ }{
+ {
+ name: "path with trailing slash",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/:
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ expectedError: "[7:3] warning style-path-trailing-slash path `/users/` must not end with a trailing slash",
+ },
+ {
+ name: "nested path with trailing slash",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /api/users/:
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ expectedError: "[7:3] warning style-path-trailing-slash path `/api/users/` must not end with a trailing slash",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.PathTrailingSlashRule{}
+ config := &linter.RuleConfig{}
+ docInfo := linter.NewDocumentInfo(doc, "test.yaml")
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ require.Len(t, errs, 1)
+ assert.Equal(t, tt.expectedError, errs[0].Error())
+ })
+ }
+}
+
+func TestPathTrailingSlashRule_RuleMetadata(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.PathTrailingSlashRule{}
+
+ assert.Equal(t, "style-path-trailing-slash", rule.ID())
+ assert.Equal(t, rules.CategoryStyle, rule.Category())
+ assert.NotEmpty(t, rule.Description())
+ assert.NotEmpty(t, rule.Link())
+ assert.Equal(t, validation.SeverityWarning, rule.DefaultSeverity())
+ assert.Nil(t, rule.Versions())
+}
diff --git a/openapi/linter/rules/paths_kebab_case.go b/openapi/linter/rules/paths_kebab_case.go
new file mode 100644
index 00000000..e724a1c9
--- /dev/null
+++ b/openapi/linter/rules/paths_kebab_case.go
@@ -0,0 +1,107 @@
+package rules
+
+import (
+ "context"
+ "fmt"
+ "regexp"
+ "strings"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/validation"
+)
+
+const RuleStylePathsKebabCase = "style-paths-kebab-case"
+
+type PathsKebabCaseRule struct{}
+
+func (r *PathsKebabCaseRule) ID() string {
+ return RuleStylePathsKebabCase
+}
+
+func (r *PathsKebabCaseRule) Description() string {
+ return "Path segments should use kebab-case (lowercase with hyphens) for consistency and readability. Kebab-case paths are easier to read, follow REST conventions, and avoid case-sensitivity issues across different systems."
+}
+
+func (r *PathsKebabCaseRule) Summary() string {
+ return "Path segments should use kebab-case."
+}
+
+func (r *PathsKebabCaseRule) HowToFix() string {
+ return "Rename non-kebab-case path segments to lowercase with hyphens."
+}
+
+func (r *PathsKebabCaseRule) Category() string {
+ return CategoryStyle
+}
+
+func (r *PathsKebabCaseRule) DefaultSeverity() validation.Severity {
+ return validation.SeverityWarning
+}
+
+func (r *PathsKebabCaseRule) Link() string {
+ return "https://github.com/speakeasy-api/openapi/blob/main/openapi/linter/README.md#style-paths-kebab-case"
+}
+
+func (r *PathsKebabCaseRule) Versions() []string {
+ return nil // applies to all versions
+}
+
+var pathKebabCaseRegex = regexp.MustCompile(`^[{}a-z\d-.]+$`)
+var variableRegex = regexp.MustCompile(`^\{(\w.*)}\.?.*$`)
+
+// checkPathKebabCase returns non-kebab-case segments in the path
+func checkPathKebabCase(path string) []string {
+ parts := strings.Split(path, "/")
+ if len(parts) == 0 {
+ return nil
+ }
+ segments := parts[1:] // skip first empty segment
+ var invalidSegments []string
+
+ for _, seg := range segments {
+ if seg == "" {
+ continue
+ }
+ // Skip variable segments like {id} or {userId}
+ if variableRegex.MatchString(seg) {
+ continue
+ }
+ // Check if segment matches kebab-case pattern
+ if !pathKebabCaseRegex.MatchString(seg) {
+ invalidSegments = append(invalidSegments, seg)
+ }
+ }
+
+ return invalidSegments
+}
+
+func (r *PathsKebabCaseRule) Run(ctx context.Context, docInfo *linter.DocumentInfo[*openapi.OpenAPI], config *linter.RuleConfig) []error {
+ if docInfo == nil || docInfo.Document == nil {
+ return nil
+ }
+
+ var errs []error
+ doc := docInfo.Document
+
+ paths := doc.GetPaths()
+ if paths == nil {
+ return nil
+ }
+
+ for pathKey := range paths.All() {
+ invalidSegments := checkPathKebabCase(pathKey)
+
+ if len(invalidSegments) > 0 {
+ node := paths.GetCore().GetMapKeyNodeOrRoot(pathKey, paths.GetRootNode())
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleStylePathsKebabCase,
+ fmt.Errorf("path segments `%s` are not kebab-case", strings.Join(invalidSegments, "`, `")),
+ node,
+ ))
+ }
+ }
+
+ return errs
+}
diff --git a/openapi/linter/rules/paths_kebab_case_test.go b/openapi/linter/rules/paths_kebab_case_test.go
new file mode 100644
index 00000000..7c651251
--- /dev/null
+++ b/openapi/linter/rules/paths_kebab_case_test.go
@@ -0,0 +1,222 @@
+package rules_test
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/openapi/linter/rules"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestPathsKebabCaseRule_ValidCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "kebab-case path",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /api-users:
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ },
+ {
+ name: "kebab-case with numbers",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /api-v1-users:
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ },
+ {
+ name: "path with variables",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /users/{userId}:
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ },
+ {
+ name: "mixed kebab-case and variables",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /api-users/{userId}/user-profile:
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ },
+ {
+ name: "path with dots and dashes",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /api.v1/user-data:
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.PathsKebabCaseRule{}
+ config := &linter.RuleConfig{}
+ docInfo := linter.NewDocumentInfo(doc, "test.yaml")
+
+ errs := rule.Run(ctx, docInfo, config)
+ assert.Empty(t, errs)
+ })
+ }
+}
+
+func TestPathsKebabCaseRule_Violations(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ expectedError string
+ }{
+ {
+ name: "camelCase path",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /apiUsers:
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ expectedError: "[7:3] warning style-paths-kebab-case path segments `apiUsers` are not kebab-case",
+ },
+ {
+ name: "snake_case path",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /api_users:
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ expectedError: "[7:3] warning style-paths-kebab-case path segments `api_users` are not kebab-case",
+ },
+ {
+ name: "uppercase path",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /API/USERS:
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ expectedError: "[7:3] warning style-paths-kebab-case path segments `API`, `USERS` are not kebab-case",
+ },
+ {
+ name: "mixed valid and invalid segments",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /api-users/userId:
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ expectedError: "[7:3] warning style-paths-kebab-case path segments `userId` are not kebab-case",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.PathsKebabCaseRule{}
+ config := &linter.RuleConfig{}
+ docInfo := linter.NewDocumentInfo(doc, "test.yaml")
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ require.Len(t, errs, 1)
+ assert.Equal(t, tt.expectedError, errs[0].Error())
+ })
+ }
+}
+
+func TestPathsKebabCaseRule_RuleMetadata(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.PathsKebabCaseRule{}
+
+ assert.Equal(t, "style-paths-kebab-case", rule.ID())
+ assert.Equal(t, rules.CategoryStyle, rule.Category())
+ assert.NotEmpty(t, rule.Description())
+ assert.NotEmpty(t, rule.Link())
+ assert.Equal(t, validation.SeverityWarning, rule.DefaultSeverity())
+ assert.Nil(t, rule.Versions())
+}
diff --git a/openapi/linter/rules/rule_metadata_test.go b/openapi/linter/rules/rule_metadata_test.go
new file mode 100644
index 00000000..cc0333e8
--- /dev/null
+++ b/openapi/linter/rules/rule_metadata_test.go
@@ -0,0 +1,103 @@
+package rules_test
+
+import (
+ "testing"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/openapi/linter/rules"
+ "github.com/stretchr/testify/assert"
+)
+
+// howToFixer is the interface satisfied by rules that provide fix guidance.
+type howToFixer interface {
+ HowToFix() string
+}
+
+// allRules returns every built-in rule instance.
+func allRules() []linter.RuleRunner[*openapi.OpenAPI] {
+ return []linter.RuleRunner[*openapi.OpenAPI]{
+ &rules.PathParamsRule{},
+ &rules.PathDeclarationsRule{},
+ &rules.PathQueryRule{},
+ &rules.TypedEnumRule{},
+ &rules.DuplicatedEnumRule{},
+ &rules.NoEvalInMarkdownRule{},
+ &rules.OAS3APIServersRule{},
+ &rules.NoRefSiblingsRule{},
+ &rules.NoScriptTagsInMarkdownRule{},
+ &rules.OAS3HostNotExampleRule{},
+ &rules.OperationIdRule{},
+ &rules.OperationSuccessResponseRule{},
+ &rules.OperationErrorResponseRule{},
+ &rules.OperationTagDefinedRule{},
+ &rules.OperationSingularTagRule{},
+ &rules.OperationDescriptionRule{},
+ &rules.OperationTagsRule{},
+ &rules.InfoDescriptionRule{},
+ &rules.InfoContactRule{},
+ &rules.InfoLicenseRule{},
+ &rules.LicenseURLRule{},
+ &rules.PathTrailingSlashRule{},
+ &rules.PathsKebabCaseRule{},
+ &rules.NoVerbsInPathRule{},
+ &rules.TagDescriptionRule{},
+ &rules.TagsAlphabeticalRule{},
+ &rules.ContactPropertiesRule{},
+ &rules.OpenAPITagsRule{},
+ &rules.ComponentDescriptionRule{},
+ &rules.UnusedComponentRule{},
+ &rules.OperationIDValidInURLRule{},
+ &rules.LinkOperationRule{},
+ &rules.OAS3HostTrailingSlashRule{},
+ &rules.OAS3ParameterDescriptionRule{},
+ &rules.NoAmbiguousPathsRule{},
+ &rules.DescriptionDuplicationRule{},
+ &rules.OwaspNoHttpBasicRule{},
+ &rules.OwaspNoAPIKeysInURLRule{},
+ &rules.OwaspNoCredentialsInURLRule{},
+ &rules.OwaspAuthInsecureSchemesRule{},
+ &rules.OwaspDefineErrorResponses401Rule{},
+ &rules.OwaspDefineErrorResponses500Rule{},
+ &rules.OwaspDefineErrorResponses429Rule{},
+ &rules.OwaspSecurityHostsHttpsOAS3Rule{},
+ &rules.OwaspDefineErrorValidationRule{},
+ &rules.OwaspProtectionGlobalUnsafeRule{},
+ &rules.OwaspProtectionGlobalUnsafeStrictRule{},
+ &rules.OwaspProtectionGlobalSafeRule{},
+ &rules.OwaspRateLimitRule{},
+ &rules.OwaspRateLimitRetryAfterRule{},
+ &rules.OwaspNoNumericIDsRule{},
+ &rules.OwaspJWTBestPracticesRule{},
+ &rules.OwaspArrayLimitRule{},
+ &rules.OwaspStringLimitRule{},
+ &rules.OwaspStringRestrictedRule{},
+ &rules.OwaspIntegerFormatRule{},
+ &rules.OwaspIntegerLimitRule{},
+ &rules.OwaspNoAdditionalPropertiesRule{},
+ &rules.OwaspAdditionalPropertiesConstrainedRule{},
+ &rules.OAS3NoNullableRule{},
+ &rules.OAS3ExampleMissingRule{},
+ &rules.OASSchemaCheckRule{},
+ }
+}
+
+func TestAllRules_MetadataPopulated(t *testing.T) {
+ t.Parallel()
+
+ for _, rule := range allRules() {
+ t.Run(rule.ID(), func(t *testing.T) {
+ t.Parallel()
+
+ assert.NotEmpty(t, rule.ID(), "rule ID should not be empty")
+ assert.NotEmpty(t, rule.Category(), "rule category should not be empty")
+ assert.NotEmpty(t, rule.Description(), "rule description should not be empty")
+ assert.NotEmpty(t, rule.Summary(), "rule summary should not be empty")
+ assert.NotEmpty(t, rule.DefaultSeverity(), "rule default severity should not be empty")
+
+ if fixer, ok := rule.(howToFixer); ok {
+ assert.NotEmpty(t, fixer.HowToFix(), "rule HowToFix should not be empty")
+ }
+ })
+ }
+}
diff --git a/openapi/linter/rules/tag_description.go b/openapi/linter/rules/tag_description.go
new file mode 100644
index 00000000..d8e28114
--- /dev/null
+++ b/openapi/linter/rules/tag_description.go
@@ -0,0 +1,80 @@
+package rules
+
+import (
+ "context"
+ "fmt"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/validation"
+)
+
+const RuleStyleTagDescription = "style-tag-description"
+
+type TagDescriptionRule struct{}
+
+func (r *TagDescriptionRule) ID() string {
+ return RuleStyleTagDescription
+}
+
+func (r *TagDescriptionRule) Description() string {
+ return "Tags should include descriptions that explain the purpose and scope of the operations they group. Tag descriptions provide context in documentation and help developers understand the organization of API functionality."
+}
+
+func (r *TagDescriptionRule) Summary() string {
+ return "Tags should include descriptions."
+}
+
+func (r *TagDescriptionRule) HowToFix() string {
+ return "Add descriptions to each tag to explain the grouped operations."
+}
+
+func (r *TagDescriptionRule) Category() string {
+ return CategoryStyle
+}
+
+func (r *TagDescriptionRule) DefaultSeverity() validation.Severity {
+ return validation.SeverityHint
+}
+
+func (r *TagDescriptionRule) Link() string {
+ return "https://github.com/speakeasy-api/openapi/blob/main/openapi/linter/README.md#style-tag-description"
+}
+
+func (r *TagDescriptionRule) Versions() []string {
+ return nil // applies to all versions
+}
+
+func (r *TagDescriptionRule) Run(ctx context.Context, docInfo *linter.DocumentInfo[*openapi.OpenAPI], config *linter.RuleConfig) []error {
+ if docInfo == nil || docInfo.Document == nil {
+ return nil
+ }
+
+ var errs []error
+ doc := docInfo.Document
+
+ tags := doc.GetTags()
+ if len(tags) == 0 {
+ return nil
+ }
+
+ for _, tag := range tags {
+ if tag == nil {
+ continue
+ }
+
+ description := tag.GetDescription()
+ name := tag.GetName()
+
+ if description == "" {
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleStyleTagDescription,
+ fmt.Errorf("tag `%s` must have a description", name),
+ tag.GetRootNode(),
+ ))
+ }
+ }
+
+ return errs
+}
diff --git a/openapi/linter/rules/tag_description_test.go b/openapi/linter/rules/tag_description_test.go
new file mode 100644
index 00000000..353e1b52
--- /dev/null
+++ b/openapi/linter/rules/tag_description_test.go
@@ -0,0 +1,163 @@
+package rules_test
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/openapi/linter/rules"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestTagDescriptionRule_ValidCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "tag with description",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+tags:
+ - name: users
+ description: User management endpoints
+paths: {}
+`,
+ },
+ {
+ name: "multiple tags with descriptions",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+tags:
+ - name: users
+ description: User management endpoints
+ - name: products
+ description: Product management endpoints
+paths: {}
+`,
+ },
+ {
+ name: "no tags defined",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths: {}
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.TagDescriptionRule{}
+ config := &linter.RuleConfig{}
+ docInfo := linter.NewDocumentInfo(doc, "test.yaml")
+
+ errs := rule.Run(ctx, docInfo, config)
+ assert.Empty(t, errs)
+ })
+ }
+}
+
+func TestTagDescriptionRule_Violations(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ expectedError string
+ }{
+ {
+ name: "tag without description",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+tags:
+ - name: users
+paths: {}
+`,
+ expectedError: "[7:5] hint style-tag-description tag `users` must have a description",
+ },
+ {
+ name: "tag with empty description",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+tags:
+ - name: users
+ description: ""
+paths: {}
+`,
+ expectedError: "[7:5] hint style-tag-description tag `users` must have a description",
+ },
+ {
+ name: "one tag with description, one without",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+tags:
+ - name: users
+ description: User management endpoints
+ - name: products
+paths: {}
+`,
+ expectedError: "[9:5] hint style-tag-description tag `products` must have a description",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.TagDescriptionRule{}
+ config := &linter.RuleConfig{}
+ docInfo := linter.NewDocumentInfo(doc, "test.yaml")
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ require.NotEmpty(t, errs)
+ assert.Equal(t, tt.expectedError, errs[0].Error())
+ })
+ }
+}
+
+func TestTagDescriptionRule_RuleMetadata(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.TagDescriptionRule{}
+
+ assert.Equal(t, "style-tag-description", rule.ID())
+ assert.Equal(t, rules.CategoryStyle, rule.Category())
+ assert.NotEmpty(t, rule.Description())
+ assert.NotEmpty(t, rule.Link())
+ assert.Equal(t, validation.SeverityHint, rule.DefaultSeverity())
+ assert.Nil(t, rule.Versions())
+}
diff --git a/openapi/linter/rules/tags_alphabetical.go b/openapi/linter/rules/tags_alphabetical.go
new file mode 100644
index 00000000..ca12214a
--- /dev/null
+++ b/openapi/linter/rules/tags_alphabetical.go
@@ -0,0 +1,94 @@
+package rules
+
+import (
+ "context"
+ "fmt"
+ "strings"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/validation"
+)
+
+const RuleStyleTagsAlphabetical = "style-tags-alphabetical"
+
+type TagsAlphabeticalRule struct{}
+
+func (r *TagsAlphabeticalRule) ID() string {
+ return RuleStyleTagsAlphabetical
+}
+
+func (r *TagsAlphabeticalRule) Description() string {
+ return "Tags should be listed in alphabetical order to improve documentation organization and navigation. Alphabetical ordering makes it easier for developers to find specific tag groups in API documentation."
+}
+
+func (r *TagsAlphabeticalRule) Summary() string {
+ return "Tags should be listed in alphabetical order."
+}
+
+func (r *TagsAlphabeticalRule) HowToFix() string {
+ return "Sort the tags array alphabetically by tag name."
+}
+
+func (r *TagsAlphabeticalRule) Category() string {
+ return CategoryStyle
+}
+
+func (r *TagsAlphabeticalRule) DefaultSeverity() validation.Severity {
+ return validation.SeverityWarning
+}
+
+func (r *TagsAlphabeticalRule) Link() string {
+ return "https://github.com/speakeasy-api/openapi/blob/main/openapi/linter/README.md#style-tags-alphabetical"
+}
+
+func (r *TagsAlphabeticalRule) Versions() []string {
+ return nil // applies to all versions
+}
+
+func (r *TagsAlphabeticalRule) Run(ctx context.Context, docInfo *linter.DocumentInfo[*openapi.OpenAPI], config *linter.RuleConfig) []error {
+ if docInfo == nil || docInfo.Document == nil {
+ return nil
+ }
+
+ var errs []error
+ doc := docInfo.Document
+
+ tags := doc.GetTags()
+ if len(tags) < 2 {
+ return nil // Need at least 2 tags to check ordering
+ }
+
+ // Check if tags are in alphabetical order by name
+ for i := 0; i < len(tags)-1; i++ {
+ currentTag := tags[i]
+ nextTag := tags[i+1]
+
+ if currentTag == nil || nextTag == nil {
+ continue
+ }
+
+ currentName := currentTag.GetName()
+ nextName := nextTag.GetName()
+
+ // Compare case-insensitively
+ if strings.Compare(strings.ToLower(currentName), strings.ToLower(nextName)) > 0 {
+ // Get the node for the tags array
+ tagsNode := doc.GetCore().Tags.ValueNode
+ if tagsNode == nil {
+ tagsNode = doc.GetRootNode()
+ }
+
+ errs = append(errs, validation.NewValidationError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleStyleTagsAlphabetical,
+ fmt.Errorf("tag `%s` must be placed before `%s` (alphabetical)", nextName, currentName),
+ tagsNode,
+ ))
+ // Report only the first violation for deterministic behavior
+ break
+ }
+ }
+
+ return errs
+}
diff --git a/openapi/linter/rules/tags_alphabetical_test.go b/openapi/linter/rules/tags_alphabetical_test.go
new file mode 100644
index 00000000..b8941a51
--- /dev/null
+++ b/openapi/linter/rules/tags_alphabetical_test.go
@@ -0,0 +1,192 @@
+package rules_test
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/openapi/linter/rules"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestTagsAlphabeticalRule_ValidCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "tags in alphabetical order",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+tags:
+ - name: auth
+ description: Authentication
+ - name: products
+ description: Products
+ - name: users
+ description: Users
+paths: {}
+`,
+ },
+ {
+ name: "single tag",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+tags:
+ - name: users
+ description: Users
+paths: {}
+`,
+ },
+ {
+ name: "no tags",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths: {}
+`,
+ },
+ {
+ name: "tags with case variations in alphabetical order",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+tags:
+ - name: Auth
+ description: Authentication
+ - name: products
+ description: Products
+ - name: Users
+ description: Users
+paths: {}
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.TagsAlphabeticalRule{}
+ config := &linter.RuleConfig{}
+ docInfo := linter.NewDocumentInfo(doc, "test.yaml")
+
+ errs := rule.Run(ctx, docInfo, config)
+ assert.Empty(t, errs)
+ })
+ }
+}
+
+func TestTagsAlphabeticalRule_Violations(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ expectedError string
+ }{
+ {
+ name: "tags not in alphabetical order",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+tags:
+ - name: users
+ description: Users
+ - name: auth
+ description: Authentication
+paths: {}
+`,
+ expectedError: "[7:3] warning style-tags-alphabetical tag `auth` must be placed before `users` (alphabetical)",
+ },
+ {
+ name: "tags reversed",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+tags:
+ - name: users
+ description: Users
+ - name: products
+ description: Products
+ - name: auth
+ description: Authentication
+paths: {}
+`,
+ expectedError: "[7:3] warning style-tags-alphabetical tag `products` must be placed before `users` (alphabetical)",
+ },
+ {
+ name: "middle tags out of order",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+tags:
+ - name: auth
+ description: Authentication
+ - name: users
+ description: Users
+ - name: products
+ description: Products
+paths: {}
+`,
+ expectedError: "[7:3] warning style-tags-alphabetical tag `products` must be placed before `users` (alphabetical)",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.TagsAlphabeticalRule{}
+ config := &linter.RuleConfig{}
+ docInfo := linter.NewDocumentInfo(doc, "test.yaml")
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ require.NotEmpty(t, errs)
+ assert.Equal(t, tt.expectedError, errs[0].Error())
+ })
+ }
+}
+
+func TestTagsAlphabeticalRule_RuleMetadata(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.TagsAlphabeticalRule{}
+
+ assert.Equal(t, "style-tags-alphabetical", rule.ID())
+ assert.Equal(t, rules.CategoryStyle, rule.Category())
+ assert.NotEmpty(t, rule.Description())
+ assert.NotEmpty(t, rule.Link())
+ assert.Equal(t, validation.SeverityWarning, rule.DefaultSeverity())
+ assert.Nil(t, rule.Versions())
+}
diff --git a/openapi/linter/rules/typed_enum.go b/openapi/linter/rules/typed_enum.go
new file mode 100644
index 00000000..9cece69f
--- /dev/null
+++ b/openapi/linter/rules/typed_enum.go
@@ -0,0 +1,207 @@
+package rules
+
+import (
+ "context"
+ "fmt"
+ "strings"
+
+ "github.com/speakeasy-api/openapi/jsonschema/oas3"
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/validation"
+ "gopkg.in/yaml.v3"
+)
+
+const RuleSemanticTypedEnum = "semantic-typed-enum"
+
+type TypedEnumRule struct{}
+
+func (r *TypedEnumRule) ID() string { return RuleSemanticTypedEnum }
+func (r *TypedEnumRule) Category() string { return CategorySemantic }
+func (r *TypedEnumRule) Description() string {
+ return "Enum values must match the specified type - for example, if type is `string`, all enum values must be strings. Type mismatches in enums cause validation failures and break code generation tools."
+}
+func (r *TypedEnumRule) Summary() string {
+ return "Enum values must match the specified schema type."
+}
+func (r *TypedEnumRule) HowToFix() string {
+ return "Update enum values to match the schema type or adjust the schema type to include the enum value types."
+}
+func (r *TypedEnumRule) Link() string {
+ return "https://github.com/speakeasy-api/openapi/blob/main/openapi/linter/README.md#semantic-typed-enum"
+}
+func (r *TypedEnumRule) DefaultSeverity() validation.Severity {
+ return validation.SeverityWarning
+}
+func (r *TypedEnumRule) Versions() []string {
+ return nil // Applies to all OpenAPI versions
+}
+
+func (r *TypedEnumRule) Run(ctx context.Context, docInfo *linter.DocumentInfo[*openapi.OpenAPI], config *linter.RuleConfig) []error {
+ if docInfo == nil || docInfo.Document == nil || docInfo.Index == nil {
+ return nil
+ }
+
+ var errs []error
+
+ // Get OpenAPI version for version-specific error messages
+ openapiVersion := docInfo.Document.GetOpenAPI()
+
+ // Use the pre-computed schema indexes to find all schemas with enums
+ for _, schemaNode := range docInfo.Index.GetAllSchemas() {
+ refSchema := schemaNode.Node
+ schema := refSchema.GetSchema()
+ if schema == nil {
+ continue
+ }
+
+ // Check if schema has enum values
+ if len(schema.GetEnum()) == 0 {
+ continue
+ }
+
+ // Get the schema type
+ schemaTypes := schema.GetType()
+ if len(schemaTypes) == 0 {
+ // No type specified, skip validation
+ continue
+ }
+
+ // Validate each enum value against the type
+ for i, enumValueNode := range schema.GetEnum() {
+ if !isNodeMatchingType(enumValueNode, schemaTypes, schema.GetNullable()) {
+ errorMsg := createTypeMismatchError(i, enumValueNode, schemaTypes, schema.GetNullable(), openapiVersion)
+ errs = append(errs, validation.NewSliceError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleSemanticTypedEnum,
+ fmt.Errorf("%s", errorMsg),
+ schema.GetCore(),
+ schema.GetCore().Enum,
+ i,
+ ))
+ }
+ }
+ }
+
+ return errs
+}
+
+// createTypeMismatchError creates an appropriate error message for type mismatches
+func createTypeMismatchError(index int, node *yaml.Node, schemaTypes []oas3.SchemaType, nullable bool, openapiVersion string) string {
+ isNull := isNullNode(node)
+
+ if isNull && !nullable && !containsType(schemaTypes, oas3.SchemaTypeNull) {
+ // Special error message for null values without proper nullable declaration
+ if len(openapiVersion) >= 3 && openapiVersion[:3] == "3.0" {
+ // OpenAPI 3.0.x - suggest nullable: true
+ return fmt.Sprintf("enum contains null at index `%d` but schema does not have `nullable: true`. Add `nullable: true` to allow null values", index)
+ }
+ // OpenAPI 3.1.x or later - suggest type array with null
+ typeWithNull := formatTypeArrayWithNull(schemaTypes)
+ return fmt.Sprintf("enum contains null at index `%d` but schema type does not include null. Change `type: %s` to `type: %s` to allow null values", index, formatTypeArray(schemaTypes), typeWithNull)
+ }
+
+ // Generic type mismatch error
+ return fmt.Sprintf("enum value at index `%d` does not match schema type %s", index, formatTypeArray(schemaTypes))
+}
+
+// isNullNode checks if a YAML node represents a null value
+func isNullNode(node *yaml.Node) bool {
+ if node == nil {
+ return true
+ }
+ if node.Kind == yaml.AliasNode {
+ return true
+ }
+ return node.Tag == "!!null"
+}
+
+// formatTypeArray formats a type array for display in error messages
+func formatTypeArray(schemaTypes []oas3.SchemaType) string {
+ if len(schemaTypes) == 0 {
+ return "[]"
+ }
+ if len(schemaTypes) == 1 {
+ return fmt.Sprintf("[`%s`]", schemaTypes[0])
+ }
+ // Multiple types
+ var result strings.Builder
+ result.WriteString("[")
+ for i, t := range schemaTypes {
+ if i > 0 {
+ result.WriteString(", ")
+ }
+ result.WriteString("`")
+ result.WriteString(string(t))
+ result.WriteString("`")
+ }
+ result.WriteString("]")
+ return result.String()
+}
+
+// formatTypeArrayWithNull formats a type array suggestion with null included
+func formatTypeArrayWithNull(schemaTypes []oas3.SchemaType) string {
+ if len(schemaTypes) == 0 {
+ return `["null"]`
+ }
+ if len(schemaTypes) == 1 {
+ return fmt.Sprintf(`[%q, "null"]`, schemaTypes[0])
+ }
+ // Multiple types - add null to the array
+ types := make([]string, len(schemaTypes)+1)
+ for i, t := range schemaTypes {
+ types[i] = fmt.Sprintf("%q", t)
+ }
+ types[len(types)-1] = `"null"`
+
+ var result strings.Builder
+ result.WriteString("[")
+ for i, t := range types {
+ if i > 0 {
+ result.WriteString(", ")
+ }
+ result.WriteString(t)
+ }
+ result.WriteString("]")
+ return result.String()
+}
+
+// isNodeMatchingType checks if a yaml.Node value matches the schema type
+func isNodeMatchingType(node *yaml.Node, schemaTypes []oas3.SchemaType, nullable bool) bool {
+ if node == nil || node.Kind == yaml.AliasNode {
+ // nil or alias nodes - check for null type or nullable schema
+ return containsType(schemaTypes, oas3.SchemaTypeNull) || nullable
+ }
+
+ // Check based on yaml node tag
+ switch node.Tag {
+ case "!!str":
+ return containsType(schemaTypes, oas3.SchemaTypeString)
+ case "!!int":
+ // Integer can match both integer and number types
+ return containsType(schemaTypes, oas3.SchemaTypeInteger) || containsType(schemaTypes, oas3.SchemaTypeNumber)
+ case "!!float":
+ // Float can match number or integer types
+ return containsType(schemaTypes, oas3.SchemaTypeNumber) || containsType(schemaTypes, oas3.SchemaTypeInteger)
+ case "!!bool":
+ return containsType(schemaTypes, oas3.SchemaTypeBoolean)
+ case "!!seq":
+ return containsType(schemaTypes, oas3.SchemaTypeArray)
+ case "!!map":
+ return containsType(schemaTypes, oas3.SchemaTypeObject)
+ case "!!null":
+ return containsType(schemaTypes, oas3.SchemaTypeNull) || nullable
+ default:
+ // Unknown tag, be permissive
+ return true
+ }
+}
+
+func containsType(schemaType []oas3.SchemaType, targetType oas3.SchemaType) bool {
+ for _, t := range schemaType {
+ if t == targetType {
+ return true
+ }
+ }
+ return false
+}
diff --git a/openapi/linter/rules/typed_enum_test.go b/openapi/linter/rules/typed_enum_test.go
new file mode 100644
index 00000000..c6d2bb25
--- /dev/null
+++ b/openapi/linter/rules/typed_enum_test.go
@@ -0,0 +1,352 @@
+package rules_test
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/openapi/linter/rules"
+ "github.com/speakeasy-api/openapi/references"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestTypedEnumRule_ValidCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "string enum with string values",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Status:
+ type: string
+ enum:
+ - active
+ - inactive
+ - pending
+`,
+ },
+ {
+ name: "integer enum with integer values",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Priority:
+ type: integer
+ enum:
+ - 1
+ - 2
+ - 3
+`,
+ },
+ {
+ name: "number enum with numeric values",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Rating:
+ type: number
+ enum:
+ - 1.5
+ - 2.0
+ - 4.5
+`,
+ },
+ {
+ name: "boolean enum",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Flag:
+ type: boolean
+ enum:
+ - true
+ - false
+`,
+ },
+ {
+ name: "number type with integer value is valid",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Count:
+ type: number
+ enum:
+ - 1
+ - 2
+`,
+ },
+ {
+ name: "null type with null value",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Nullable:
+ type: "null"
+ enum:
+ - null
+`,
+ },
+ {
+ name: "enum without type specified",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Mixed:
+ enum:
+ - value1
+ - 123
+`,
+ },
+ {
+ name: "schema without enum",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ User:
+ type: object
+ properties:
+ name:
+ type: string
+`,
+ },
+ {
+ name: "nullable integer enum with null value",
+ yaml: `
+openapi: 3.0.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ NullableIntEnum:
+ type: integer
+ nullable: true
+ enum:
+ - 1
+ - 2
+ - 3
+ - null
+`,
+ },
+ {
+ name: "nullable string enum with null value",
+ yaml: `
+openapi: 3.0.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ NullableStringEnum:
+ type: string
+ nullable: true
+ enum:
+ - First
+ - Second
+ - Third
+ - null
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.TypedEnumRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+ assert.Empty(t, errs)
+ })
+ }
+}
+
+func TestTypedEnumRule_TypeMismatch(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ expectedError string
+ }{
+ {
+ name: "string type with integer value",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Status:
+ type: string
+ enum:
+ - active
+ - 123
+`,
+ expectedError: "[12:11] warning semantic-typed-enum enum value at index `1` does not match schema type [`string`]",
+ },
+ {
+ name: "integer type with string value",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Priority:
+ type: integer
+ enum:
+ - 1
+ - high
+`,
+ expectedError: "[12:11] warning semantic-typed-enum enum value at index `1` does not match schema type [`integer`]",
+ },
+ {
+ name: "boolean type with string value",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Flag:
+ type: boolean
+ enum:
+ - true
+ - yes
+`,
+ expectedError: "[12:11] warning semantic-typed-enum enum value at index `1` does not match schema type [`boolean`]",
+ },
+ {
+ name: "openapi 3.0 null in enum without nullable true",
+ yaml: `
+openapi: 3.0.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Status:
+ type: string
+ enum:
+ - active
+ - inactive
+ - null
+`,
+ expectedError: "[13:11] warning semantic-typed-enum enum contains null at index `2` but schema does not have `nullable: true`. Add `nullable: true` to allow null values",
+ },
+ {
+ name: "openapi 3.1 null in enum without null in type",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+components:
+ schemas:
+ Priority:
+ type: integer
+ enum:
+ - 1
+ - 2
+ - null
+`,
+ expectedError: `[13:11] warning semantic-typed-enum enum contains null at index ` + "`2`" + ` but schema type does not include null. Change ` + "`type: [`integer`]`" + ` to ` + "`type: [\"integer\", \"null\"]`" + ` to allow null values`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err)
+
+ rule := &rules.TypedEnumRule{}
+ config := &linter.RuleConfig{}
+
+ // Build index for the rule
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ docInfo := linter.NewDocumentInfoWithIndex(doc, "test.yaml", idx)
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ require.NotEmpty(t, errs, "should have lint errors")
+ assert.Equal(t, tt.expectedError, errs[0].Error())
+ })
+ }
+}
+
+func TestTypedEnumRule_RuleMetadata(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.TypedEnumRule{}
+
+ assert.Equal(t, "semantic-typed-enum", rule.ID())
+ assert.Equal(t, rules.CategorySemantic, rule.Category())
+ assert.NotEmpty(t, rule.Description())
+ assert.NotEmpty(t, rule.Link())
+ assert.Equal(t, validation.SeverityWarning, rule.DefaultSeverity())
+ assert.Nil(t, rule.Versions())
+}
diff --git a/openapi/linter/rules/unused_components.go b/openapi/linter/rules/unused_components.go
new file mode 100644
index 00000000..a64ce75e
--- /dev/null
+++ b/openapi/linter/rules/unused_components.go
@@ -0,0 +1,467 @@
+package rules
+
+import (
+ "context"
+ "fmt"
+ "strings"
+
+ "github.com/speakeasy-api/openapi/extensions"
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/references"
+ "github.com/speakeasy-api/openapi/validation"
+ "gopkg.in/yaml.v3"
+)
+
+const RuleSemanticUnusedComponent = "semantic-unused-component"
+
+type UnusedComponentRule struct{}
+
+func (r *UnusedComponentRule) ID() string { return RuleSemanticUnusedComponent }
+func (r *UnusedComponentRule) Category() string { return CategorySemantic }
+func (r *UnusedComponentRule) Description() string {
+ return "Components that are declared but never referenced should be removed to keep the specification clean. Unused components create maintenance burden, increase specification size, and may confuse developers about which schemas are actually used."
+}
+func (r *UnusedComponentRule) Summary() string {
+ return "Components should not be declared if they are never referenced."
+}
+func (r *UnusedComponentRule) HowToFix() string {
+ return "Remove unused components or reference them where needed in the specification."
+}
+func (r *UnusedComponentRule) Link() string {
+ return "https://github.com/speakeasy-api/openapi/blob/main/openapi/linter/README.md#semantic-unused-component"
+}
+func (r *UnusedComponentRule) DefaultSeverity() validation.Severity {
+ return validation.SeverityWarning
+}
+func (r *UnusedComponentRule) Versions() []string {
+ // Applies to all OAS3 versions
+ return nil
+}
+
+func (r *UnusedComponentRule) Run(_ context.Context, docInfo *linter.DocumentInfo[*openapi.OpenAPI], config *linter.RuleConfig) []error {
+ if docInfo == nil || docInfo.Document == nil || docInfo.Index == nil {
+ return nil
+ }
+
+ doc := docInfo.Document
+
+ // Step 1: Collect all referenced component pointers from $ref strings
+ referencedPointers := collectReferencedComponentPointers(docInfo.Index, doc, docInfo.Location)
+
+ // Step 2: Check each component against the referenced set
+ return checkUnusedComponents(doc, docInfo.Index, referencedPointers, config, r.DefaultSeverity())
+}
+
+// collectReferencedComponentPointers iterates through all reference slices in the index
+// and collects the component JSON pointers (e.g., "/components/schemas/Pet").
+func collectReferencedComponentPointers(idx *openapi.Index, doc *openapi.OpenAPI, docLocation string) map[string]struct{} {
+ refs := make(map[string]struct{})
+ self := ""
+ if doc != nil {
+ self = doc.GetSelf()
+ }
+
+ // Schema references
+ for _, node := range idx.SchemaReferences {
+ if node == nil || node.Node == nil {
+ continue
+ }
+ if ptr := extractComponentPointer(node.Node.GetReference(), docLocation, self); ptr != "" {
+ refs[ptr] = struct{}{}
+ }
+ }
+
+ // Parameter references
+ for _, node := range idx.ParameterReferences {
+ if node == nil || node.Node == nil {
+ continue
+ }
+ if ptr := extractComponentPointer(node.Node.GetReference(), docLocation, self); ptr != "" {
+ refs[ptr] = struct{}{}
+ }
+ }
+
+ // Response references
+ for _, node := range idx.ResponseReferences {
+ if node == nil || node.Node == nil {
+ continue
+ }
+ if ptr := extractComponentPointer(node.Node.GetReference(), docLocation, self); ptr != "" {
+ refs[ptr] = struct{}{}
+ }
+ }
+
+ // RequestBody references
+ for _, node := range idx.RequestBodyReferences {
+ if node == nil || node.Node == nil {
+ continue
+ }
+ if ptr := extractComponentPointer(node.Node.GetReference(), docLocation, self); ptr != "" {
+ refs[ptr] = struct{}{}
+ }
+ }
+
+ // Header references
+ for _, node := range idx.HeaderReferences {
+ if node == nil || node.Node == nil {
+ continue
+ }
+ if ptr := extractComponentPointer(node.Node.GetReference(), docLocation, self); ptr != "" {
+ refs[ptr] = struct{}{}
+ }
+ }
+
+ // Example references
+ for _, node := range idx.ExampleReferences {
+ if node == nil || node.Node == nil {
+ continue
+ }
+ if ptr := extractComponentPointer(node.Node.GetReference(), docLocation, self); ptr != "" {
+ refs[ptr] = struct{}{}
+ }
+ }
+
+ // Link references
+ for _, node := range idx.LinkReferences {
+ if node == nil || node.Node == nil {
+ continue
+ }
+ if ptr := extractComponentPointer(node.Node.GetReference(), docLocation, self); ptr != "" {
+ refs[ptr] = struct{}{}
+ }
+ }
+
+ // Callback references
+ for _, node := range idx.CallbackReferences {
+ if node == nil || node.Node == nil {
+ continue
+ }
+ if ptr := extractComponentPointer(node.Node.GetReference(), docLocation, self); ptr != "" {
+ refs[ptr] = struct{}{}
+ }
+ }
+
+ // PathItem references
+ for _, node := range idx.PathItemReferences {
+ if node == nil || node.Node == nil {
+ continue
+ }
+ if ptr := extractComponentPointer(node.Node.GetReference(), docLocation, self); ptr != "" {
+ refs[ptr] = struct{}{}
+ }
+ }
+
+ // SecurityScheme references
+ for _, node := range idx.SecuritySchemeReferences {
+ if node == nil || node.Node == nil {
+ continue
+ }
+ if ptr := extractComponentPointer(node.Node.GetReference(), docLocation, self); ptr != "" {
+ refs[ptr] = struct{}{}
+ }
+ }
+
+ // Security requirements reference security schemes by name (not $ref)
+ for _, node := range idx.SecurityRequirements {
+ if node == nil || node.Node == nil {
+ continue
+ }
+ for schemeName := range node.Node.All() {
+ // Security requirements reference security schemes by name
+ refs["/components/securitySchemes/"+schemeName] = struct{}{}
+ }
+ }
+
+ return refs
+}
+
+// extractComponentPointer extracts the top-level component JSON pointer from a $ref.
+// For example, "#/components/schemas/Pet/properties/name" becomes "/components/schemas/Pet".
+// Returns empty string if the reference is not to a component or is external.
+func extractComponentPointer(ref references.Reference, docLocation string, docSelf string) string {
+ if ref == "" {
+ return ""
+ }
+
+ uri := ref.GetURI()
+ if uri != "" && uri != docLocation && uri != docSelf {
+ return ""
+ }
+
+ pointer := ref.GetJSONPointer().String()
+ if pointer == "" {
+ return ""
+ }
+
+ // Must start with /components/
+ if !strings.HasPrefix(pointer, "/components/") {
+ return ""
+ }
+
+ // Extract the component type and name: /components/{type}/{name}
+ // Skip "/components/" (12 chars), then find the type and name
+ rest := strings.TrimPrefix(pointer, "/components/")
+ parts := strings.SplitN(rest, "/", 3) // Split into at most 3 parts: type, name, rest
+ if len(parts) < 2 || parts[0] == "" || parts[1] == "" {
+ return ""
+ }
+
+ // Return the normalized component pointer (keep escaped form for comparison)
+ return "/components/" + parts[0] + "/" + parts[1]
+}
+
+// checkUnusedComponents iterates through all component entries in the index
+// and flags those not in the referenced set using ToJSONPointer.
+func checkUnusedComponents(doc *openapi.OpenAPI, idx *openapi.Index, refs map[string]struct{}, config *linter.RuleConfig, severity validation.Severity) []error {
+ var errs []error
+
+ // Check component schemas
+ for _, node := range idx.ComponentSchemas {
+ if node == nil || node.Node == nil {
+ continue
+ }
+ pointer := node.Location.ToJSONPointer().String()
+ if _, found := refs[pointer]; !found {
+ // Skip if component has a usage-marking extension
+ if hasUsageMarkingExtension(node.Node.GetExtensions()) {
+ continue
+ }
+ errNode := getComponentKeyNode(doc, node.Location)
+ errs = append(errs, createUnusedComponentError(pointer, errNode, config, severity))
+ }
+ }
+
+ // Check component parameters
+ for _, node := range idx.ComponentParameters {
+ if node == nil || node.Node == nil {
+ continue
+ }
+ pointer := node.Location.ToJSONPointer().String()
+ if _, found := refs[pointer]; !found {
+ // Skip if component has a usage-marking extension
+ if obj := node.Node.GetObject(); obj != nil && hasUsageMarkingExtension(obj.GetExtensions()) {
+ continue
+ }
+ errNode := getComponentKeyNode(doc, node.Location)
+ errs = append(errs, createUnusedComponentError(pointer, errNode, config, severity))
+ }
+ }
+
+ // Check component responses
+ for _, node := range idx.ComponentResponses {
+ if node == nil || node.Node == nil {
+ continue
+ }
+ pointer := node.Location.ToJSONPointer().String()
+ if _, found := refs[pointer]; !found {
+ // Skip if component has a usage-marking extension
+ if obj := node.Node.GetObject(); obj != nil && hasUsageMarkingExtension(obj.GetExtensions()) {
+ continue
+ }
+ errNode := getComponentKeyNode(doc, node.Location)
+ errs = append(errs, createUnusedComponentError(pointer, errNode, config, severity))
+ }
+ }
+
+ // Check component request bodies
+ for _, node := range idx.ComponentRequestBodies {
+ if node == nil || node.Node == nil {
+ continue
+ }
+ pointer := node.Location.ToJSONPointer().String()
+ if _, found := refs[pointer]; !found {
+ // Skip if component has a usage-marking extension
+ if obj := node.Node.GetObject(); obj != nil && hasUsageMarkingExtension(obj.Extensions) {
+ continue
+ }
+ errNode := getComponentKeyNode(doc, node.Location)
+ errs = append(errs, createUnusedComponentError(pointer, errNode, config, severity))
+ }
+ }
+
+ // Check component headers
+ for _, node := range idx.ComponentHeaders {
+ if node == nil || node.Node == nil {
+ continue
+ }
+ pointer := node.Location.ToJSONPointer().String()
+ if _, found := refs[pointer]; !found {
+ // Skip if component has a usage-marking extension
+ if obj := node.Node.GetObject(); obj != nil && hasUsageMarkingExtension(obj.GetExtensions()) {
+ continue
+ }
+ errNode := getComponentKeyNode(doc, node.Location)
+ errs = append(errs, createUnusedComponentError(pointer, errNode, config, severity))
+ }
+ }
+
+ // Check component examples
+ for _, node := range idx.ComponentExamples {
+ if node == nil || node.Node == nil {
+ continue
+ }
+ pointer := node.Location.ToJSONPointer().String()
+ if _, found := refs[pointer]; !found {
+ // Skip if component has a usage-marking extension
+ if obj := node.Node.GetObject(); obj != nil && hasUsageMarkingExtension(obj.GetExtensions()) {
+ continue
+ }
+ errNode := getComponentKeyNode(doc, node.Location)
+ errs = append(errs, createUnusedComponentError(pointer, errNode, config, severity))
+ }
+ }
+
+ // Check component links
+ for _, node := range idx.ComponentLinks {
+ if node == nil || node.Node == nil {
+ continue
+ }
+ pointer := node.Location.ToJSONPointer().String()
+ if _, found := refs[pointer]; !found {
+ // Skip if component has a usage-marking extension
+ if obj := node.Node.GetObject(); obj != nil && hasUsageMarkingExtension(obj.GetExtensions()) {
+ continue
+ }
+ errNode := getComponentKeyNode(doc, node.Location)
+ errs = append(errs, createUnusedComponentError(pointer, errNode, config, severity))
+ }
+ }
+
+ // Check component callbacks
+ for _, node := range idx.ComponentCallbacks {
+ if node == nil || node.Node == nil {
+ continue
+ }
+ pointer := node.Location.ToJSONPointer().String()
+ if _, found := refs[pointer]; !found {
+ // Skip if component has a usage-marking extension
+ if obj := node.Node.GetObject(); obj != nil && hasUsageMarkingExtension(obj.GetExtensions()) {
+ continue
+ }
+ errNode := getComponentKeyNode(doc, node.Location)
+ errs = append(errs, createUnusedComponentError(pointer, errNode, config, severity))
+ }
+ }
+
+ // Check component path items
+ for _, node := range idx.ComponentPathItems {
+ if node == nil || node.Node == nil {
+ continue
+ }
+ pointer := node.Location.ToJSONPointer().String()
+ if _, found := refs[pointer]; !found {
+ // Skip if component has a usage-marking extension
+ if obj := node.Node.GetObject(); obj != nil && hasUsageMarkingExtension(obj.GetExtensions()) {
+ continue
+ }
+ errNode := getComponentKeyNode(doc, node.Location)
+ errs = append(errs, createUnusedComponentError(pointer, errNode, config, severity))
+ }
+ }
+
+ // Check component security schemes
+ for _, node := range idx.ComponentSecuritySchemes {
+ if node == nil || node.Node == nil {
+ continue
+ }
+ pointer := node.Location.ToJSONPointer().String()
+ if _, found := refs[pointer]; !found {
+ // Skip if component has a usage-marking extension
+ if obj := node.Node.GetObject(); obj != nil && hasUsageMarkingExtension(obj.GetExtensions()) {
+ continue
+ }
+ errNode := getComponentKeyNode(doc, node.Location)
+ errs = append(errs, createUnusedComponentError(pointer, errNode, config, severity))
+ }
+ }
+
+ return errs
+}
+
+func getComponentKeyNode(doc *openapi.OpenAPI, location openapi.Locations) *yaml.Node {
+ if doc == nil || len(location) == 0 {
+ return nil
+ }
+ last := location[len(location)-1]
+ if last.ParentKey == nil {
+ return nil
+ }
+ componentName := *last.ParentKey
+ componentType := last.ParentField
+
+ core := doc.GetCore()
+ if core == nil {
+ return nil
+ }
+ rootNode := core.GetRootNode()
+ if !core.Components.Present || core.Components.Value == nil {
+ return rootNode
+ }
+ componentsCore := core.Components.Value
+ componentsRoot := componentsCore.GetRootNode()
+ if componentsRoot == nil {
+ componentsRoot = rootNode
+ }
+
+ switch componentType {
+ case "schemas":
+ return componentsCore.Schemas.GetMapKeyNodeOrRoot(componentName, componentsRoot)
+ case "responses":
+ return componentsCore.Responses.GetMapKeyNodeOrRoot(componentName, componentsRoot)
+ case "parameters":
+ return componentsCore.Parameters.GetMapKeyNodeOrRoot(componentName, componentsRoot)
+ case "examples":
+ return componentsCore.Examples.GetMapKeyNodeOrRoot(componentName, componentsRoot)
+ case "requestBodies":
+ return componentsCore.RequestBodies.GetMapKeyNodeOrRoot(componentName, componentsRoot)
+ case "headers":
+ return componentsCore.Headers.GetMapKeyNodeOrRoot(componentName, componentsRoot)
+ case "securitySchemes":
+ return componentsCore.SecuritySchemes.GetMapKeyNodeOrRoot(componentName, componentsRoot)
+ case "links":
+ return componentsCore.Links.GetMapKeyNodeOrRoot(componentName, componentsRoot)
+ case "callbacks":
+ return componentsCore.Callbacks.GetMapKeyNodeOrRoot(componentName, componentsRoot)
+ case "pathItems":
+ return componentsCore.PathItems.GetMapKeyNodeOrRoot(componentName, componentsRoot)
+ default:
+ return componentsRoot
+ }
+}
+
+// usageMarkingExtensions is the list of extensions that mark a component as being used
+// even when not directly referenced in the specification.
+var usageMarkingExtensions = []string{
+ "x-speakeasy-include",
+ "x-include",
+ "x-used",
+}
+
+// hasUsageMarkingExtension checks if the extensions contain any of the usage-marking
+// extensions (x-speakeasy-include, x-include, x-used) set to true.
+func hasUsageMarkingExtension(exts *extensions.Extensions) bool {
+ if exts == nil {
+ return false
+ }
+
+ for _, ext := range usageMarkingExtensions {
+ val, err := extensions.GetExtensionValue[bool](exts, ext)
+ if err == nil && val != nil && *val {
+ return true
+ }
+ }
+
+ return false
+}
+
+// createUnusedComponentError creates a validation error for an unused component.
+func createUnusedComponentError(pointer string, errNode *yaml.Node, config *linter.RuleConfig, severity validation.Severity) error {
+ componentRef := "#" + pointer
+ return validation.NewValidationError(
+ config.GetSeverity(severity),
+ RuleSemanticUnusedComponent,
+ fmt.Errorf("`%s` is potentially unused or has been orphaned", componentRef),
+ errNode,
+ )
+}
diff --git a/openapi/linter/rules/unused_components_test.go b/openapi/linter/rules/unused_components_test.go
new file mode 100644
index 00000000..0f41f307
--- /dev/null
+++ b/openapi/linter/rules/unused_components_test.go
@@ -0,0 +1,513 @@
+package rules_test
+
+import (
+ "context"
+ "fmt"
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "testing"
+
+ "github.com/speakeasy-api/openapi/linter"
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/openapi/linter/rules"
+ "github.com/speakeasy-api/openapi/references"
+ "github.com/speakeasy-api/openapi/validation"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func createDocInfoWithIndexUnusedComponents(t *testing.T, ctx context.Context, doc *openapi.OpenAPI, location string) *linter.DocumentInfo[*openapi.OpenAPI] {
+ t.Helper()
+ idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: location,
+ })
+ return linter.NewDocumentInfoWithIndex(doc, location, idx)
+}
+
+func TestUnusedComponentRule_ValidCases(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ }{
+ {
+ name: "all components referenced",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /pets:
+ get:
+ security:
+ - ApiKey: []
+ parameters:
+ - $ref: '#/components/parameters/PetId'
+ responses:
+ '200':
+ $ref: '#/components/responses/PetResponse'
+components:
+ schemas:
+ Pet:
+ type: string
+ parameters:
+ PetId:
+ name: petId
+ in: query
+ schema:
+ type: string
+ responses:
+ PetResponse:
+ description: ok
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/Pet'
+ securitySchemes:
+ ApiKey:
+ type: apiKey
+ in: header
+ name: X-API-Key
+`,
+ },
+ {
+ name: "no components",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /pets:
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err, "unmarshal should succeed")
+
+ rule := &rules.UnusedComponentRule{}
+ config := &linter.RuleConfig{}
+
+ docInfo := createDocInfoWithIndexUnusedComponents(t, ctx, doc, "test.yaml")
+
+ errs := rule.Run(ctx, docInfo, config)
+ assert.Empty(t, errs, "should have no lint errors")
+ })
+ }
+}
+
+func TestUnusedComponentRule_Violations(t *testing.T) {
+ t.Parallel()
+
+ yamlInput := `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /pets:
+ get:
+ responses:
+ '200':
+ description: ok
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/Pet'
+components:
+ schemas:
+ Pet:
+ type: string
+ Orphan:
+ type: string
+ responses:
+ UnusedResponse:
+ description: not used
+ securitySchemes:
+ ApiKey:
+ type: apiKey
+ in: header
+ name: X-API-Key
+security:
+ - ApiKey: []
+`
+
+ ctx := t.Context()
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(yamlInput))
+ require.NoError(t, err, "unmarshal should succeed")
+
+ rule := &rules.UnusedComponentRule{}
+ config := &linter.RuleConfig{}
+
+ docInfo := createDocInfoWithIndexUnusedComponents(t, ctx, doc, "test.yaml")
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ expectedErrors := []string{
+ "[20:5] warning semantic-unused-component `#/components/schemas/Orphan` is potentially unused or has been orphaned",
+ "[23:5] warning semantic-unused-component `#/components/responses/UnusedResponse` is potentially unused or has been orphaned",
+ }
+
+ var errMsgs []string
+ for _, lintErr := range errs {
+ errMsgs = append(errMsgs, lintErr.Error())
+ }
+
+ assert.ElementsMatch(t, expectedErrors, errMsgs)
+}
+
+func TestUnusedComponentRule_RuleMetadata(t *testing.T) {
+ t.Parallel()
+
+ rule := &rules.UnusedComponentRule{}
+
+ assert.Equal(t, "semantic-unused-component", rule.ID(), "rule ID should match")
+ assert.Equal(t, rules.CategorySemantic, rule.Category(), "rule category should match")
+ assert.NotEmpty(t, rule.Description(), "rule should have description")
+ assert.NotEmpty(t, rule.Link(), "rule should have documentation link")
+ assert.Equal(t, validation.SeverityWarning, rule.DefaultSeverity(), "default severity should be warning")
+ assert.Nil(t, rule.Versions(), "versions should be nil (all versions)")
+}
+
+func TestUnusedComponentRule_UsageMarkingExtensions(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yaml string
+ expectedErrors []string
+ }{
+ {
+ name: "x-speakeasy-include marks schema as used",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /pets:
+ get:
+ responses:
+ '200':
+ description: ok
+components:
+ schemas:
+ MarkedUsed:
+ type: string
+ x-speakeasy-include: true
+ ActuallyUnused:
+ type: string
+`,
+ expectedErrors: []string{
+ "[17:5] warning semantic-unused-component `#/components/schemas/ActuallyUnused` is potentially unused or has been orphaned",
+ },
+ },
+ {
+ name: "x-include marks schema as used",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /pets:
+ get:
+ responses:
+ '200':
+ description: ok
+components:
+ schemas:
+ MarkedUsed:
+ type: string
+ x-include: true
+ ActuallyUnused:
+ type: string
+`,
+ expectedErrors: []string{
+ "[17:5] warning semantic-unused-component `#/components/schemas/ActuallyUnused` is potentially unused or has been orphaned",
+ },
+ },
+ {
+ name: "x-used marks schema as used",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /pets:
+ get:
+ responses:
+ '200':
+ description: ok
+components:
+ schemas:
+ MarkedUsed:
+ type: string
+ x-used: true
+ ActuallyUnused:
+ type: string
+`,
+ expectedErrors: []string{
+ "[17:5] warning semantic-unused-component `#/components/schemas/ActuallyUnused` is potentially unused or has been orphaned",
+ },
+ },
+ {
+ name: "extension set to false does not mark as used",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /pets:
+ get:
+ responses:
+ '200':
+ description: ok
+components:
+ schemas:
+ NotMarked:
+ type: string
+ x-speakeasy-include: false
+`,
+ expectedErrors: []string{
+ "[14:5] warning semantic-unused-component `#/components/schemas/NotMarked` is potentially unused or has been orphaned",
+ },
+ },
+ {
+ name: "x-speakeasy-include marks parameter as used",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /pets:
+ get:
+ responses:
+ '200':
+ description: ok
+components:
+ parameters:
+ MarkedUsed:
+ name: test
+ in: query
+ x-speakeasy-include: true
+ ActuallyUnused:
+ name: unused
+ in: query
+`,
+ expectedErrors: []string{
+ "[18:5] warning semantic-unused-component `#/components/parameters/ActuallyUnused` is potentially unused or has been orphaned",
+ },
+ },
+ {
+ name: "x-include marks response as used",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /pets:
+ get:
+ responses:
+ '200':
+ description: ok
+components:
+ responses:
+ MarkedUsed:
+ description: marked
+ x-include: true
+ ActuallyUnused:
+ description: unused
+`,
+ expectedErrors: []string{
+ "[17:5] warning semantic-unused-component `#/components/responses/ActuallyUnused` is potentially unused or has been orphaned",
+ },
+ },
+ {
+ name: "x-used marks security scheme as used",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /pets:
+ get:
+ responses:
+ '200':
+ description: ok
+components:
+ securitySchemes:
+ MarkedUsed:
+ type: apiKey
+ in: header
+ name: X-API-Key
+ x-used: true
+ ActuallyUnused:
+ type: apiKey
+ in: header
+ name: X-Unused
+`,
+ expectedErrors: []string{
+ "[19:5] warning semantic-unused-component `#/components/securitySchemes/ActuallyUnused` is potentially unused or has been orphaned",
+ },
+ },
+ {
+ name: "all components with extensions are not flagged",
+ yaml: `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /pets:
+ get:
+ responses:
+ '200':
+ description: ok
+components:
+ schemas:
+ Schema1:
+ type: string
+ x-speakeasy-include: true
+ Schema2:
+ type: string
+ x-include: true
+ Schema3:
+ type: string
+ x-used: true
+`,
+ expectedErrors: []string{},
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(tt.yaml))
+ require.NoError(t, err, "unmarshal should succeed")
+
+ rule := &rules.UnusedComponentRule{}
+ config := &linter.RuleConfig{}
+
+ docInfo := createDocInfoWithIndexUnusedComponents(t, ctx, doc, "test.yaml")
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ var errMsgs []string
+ for _, lintErr := range errs {
+ errMsgs = append(errMsgs, lintErr.Error())
+ }
+
+ assert.ElementsMatch(t, tt.expectedErrors, errMsgs, "should match expected errors")
+ })
+ }
+}
+
+func TestUnusedComponentRule_ExternalReferenceChainMarksUsed(t *testing.T) {
+ t.Parallel()
+
+ ctx := t.Context()
+
+ mainYaml := `
+openapi: 3.1.0
+info:
+ title: Test
+ version: 1.0.0
+paths:
+ /pets:
+ get:
+ responses:
+ '200':
+ description: ok
+ content:
+ application/json:
+ schema:
+ $ref: '%s/external.yaml#/components/schemas/ExternalSchema'
+components:
+ schemas:
+ SharedUsed:
+ type: string
+ SharedUnused:
+ type: string`
+
+ externalYaml := `
+openapi: 3.1.0
+info:
+ title: External
+ version: 1.0.0
+paths:
+ /external:
+ get:
+ responses:
+ '200':
+ description: ok
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ExternalUnused'
+components:
+ schemas:
+ ExternalSchema:
+ type: object
+ properties:
+ shared:
+ $ref: '%s/main.yaml#/components/schemas/SharedUsed'
+ ExternalUnused:
+ type: object
+ properties:
+ unused:
+ $ref: '%s/main.yaml#/components/schemas/SharedUnused'
+`
+
+ var server *httptest.Server
+ server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ switch r.URL.Path {
+ case "/external.yaml":
+ w.Header().Set("Content-Type", "application/yaml")
+ w.WriteHeader(http.StatusOK)
+ _, _ = fmt.Fprintf(w, externalYaml, server.URL, server.URL)
+ case "/main.yaml":
+ w.Header().Set("Content-Type", "application/yaml")
+ w.WriteHeader(http.StatusOK)
+ _, _ = fmt.Fprintf(w, mainYaml, server.URL)
+ default:
+ w.WriteHeader(http.StatusNotFound)
+ }
+ }))
+ defer server.Close()
+
+ doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(fmt.Sprintf(mainYaml, server.URL)))
+ require.NoError(t, err, "unmarshal should succeed")
+
+ rule := &rules.UnusedComponentRule{}
+ config := &linter.RuleConfig{}
+
+ docInfo := createDocInfoWithIndexUnusedComponents(t, ctx, doc, server.URL+"/main.yaml")
+
+ errs := rule.Run(ctx, docInfo, config)
+
+ require.Len(t, errs, 1, "should only flag unreferenced components in main doc")
+ assert.Contains(t, errs[0].Error(), "`#/components/schemas/SharedUnused`", "should flag SharedUnused as unused")
+}
diff --git a/openapi/localize.go b/openapi/localize.go
index 82e00f70..25757109 100644
--- a/openapi/localize.go
+++ b/openapi/localize.go
@@ -25,6 +25,8 @@ const (
LocalizeNamingPathBased LocalizeNamingStrategy = iota
// LocalizeNamingCounter uses counter-based suffixes like "address_1.yaml" for conflicts
LocalizeNamingCounter
+ // LocalizeNamingCustom uses a user-provided function for naming
+ LocalizeNamingCustom
)
// LocalizeOptions represents the options available when localizing an OpenAPI document.
@@ -39,6 +41,11 @@ type LocalizeOptions struct {
HTTPClient system.Client
// NamingStrategy determines how external reference files are named when localized.
NamingStrategy LocalizeNamingStrategy
+ // CustomNamingFunc is used when NamingStrategy is LocalizeNamingCustom.
+ // It receives the original reference path and the resolved file content,
+ // and should return the desired filename for the localized file.
+ // The caller is responsible for ensuring filenames are unique.
+ CustomNamingFunc func(originalRef string, content []byte) string
}
// Localize transforms an OpenAPI document by copying all external reference files to a target directory
@@ -143,7 +150,7 @@ func Localize(ctx context.Context, doc *OpenAPI, opts LocalizeOptions) error {
}
// Phase 2: Generate conflict-free filenames for all external references
- generateLocalizedFilenames(localizeStorage, opts.NamingStrategy)
+ generateLocalizedFilenames(localizeStorage, opts.NamingStrategy, opts.CustomNamingFunc)
// Phase 3: Copy external files to target directory
if err := copyExternalFiles(ctx, localizeStorage, opts); err != nil {
@@ -241,7 +248,7 @@ func discoverSchemaReference(ctx context.Context, schema *oas3.JSONSchema[oas3.R
if resolutionInfo != nil {
storage.externalRefs.Set(normalizedFilePath, "") // Will be filled in filename generation phase
- if data, found := opts.RootDocument.GetCachedReferenceDocument(resolutionInfo.AbsoluteReference); found {
+ if data, found := opts.RootDocument.GetCachedReferenceDocument(resolutionInfo.AbsoluteDocumentPath); found {
storage.resolvedContent[normalizedFilePath] = data
} else {
return fmt.Errorf("failed to get cached content for reference %s", normalizedFilePath)
@@ -266,7 +273,7 @@ func discoverSchemaReference(ctx context.Context, schema *oas3.JSONSchema[oas3.R
return discoverSchemaReference(ctx, s, ResolveOptions{
RootDocument: opts.RootDocument,
TargetDocument: targetDocInfo.ResolvedDocument,
- TargetLocation: targetDocInfo.AbsoluteReference,
+ TargetLocation: targetDocInfo.AbsoluteDocumentPath,
VirtualFS: opts.VirtualFS,
HTTPClient: opts.HTTPClient,
}, storage)
@@ -320,7 +327,7 @@ func discoverGenericReference[T any, V interfaces.Validator[T], C marshaller.Cor
if resolutionInfo != nil {
storage.externalRefs.Set(normalizedFilePath, "") // Will be filled in filename generation phase
- if data, found := opts.RootDocument.GetCachedReferenceDocument(resolutionInfo.AbsoluteReference); found {
+ if data, found := opts.RootDocument.GetCachedReferenceDocument(resolutionInfo.AbsoluteDocumentPath); found {
storage.resolvedContent[normalizedFilePath] = data
} else {
return fmt.Errorf("failed to get cached content for reference %s", normalizedFilePath)
@@ -337,7 +344,7 @@ func discoverGenericReference[T any, V interfaces.Validator[T], C marshaller.Cor
resolveOpts := ResolveOptions{
RootDocument: opts.RootDocument,
TargetDocument: targetDocInfo.ResolvedDocument,
- TargetLocation: targetDocInfo.AbsoluteReference,
+ TargetLocation: targetDocInfo.AbsoluteDocumentPath,
VirtualFS: opts.VirtualFS,
HTTPClient: opts.HTTPClient,
}
@@ -386,7 +393,18 @@ func discoverGenericReference[T any, V interfaces.Validator[T], C marshaller.Cor
}
// generateLocalizedFilenames creates conflict-free filenames for all external references
-func generateLocalizedFilenames(storage *localizeStorage, strategy LocalizeNamingStrategy) {
+func generateLocalizedFilenames(storage *localizeStorage, strategy LocalizeNamingStrategy, customNamingFunc func(string, []byte) string) {
+ // Custom naming: delegate entirely to the caller's function
+ if strategy == LocalizeNamingCustom && customNamingFunc != nil {
+ for ref := range storage.externalRefs.All() {
+ content := storage.resolvedContent[ref]
+ filename := customNamingFunc(ref, content)
+ storage.externalRefs.Set(ref, filename)
+ storage.usedFilenames[filename] = true
+ }
+ return
+ }
+
// First pass: collect all base filenames to detect conflicts
baseFilenames := make(map[string][]string) // base filename -> list of full paths
for ref := range storage.externalRefs.All() {
diff --git a/openapi/localize_test.go b/openapi/localize_test.go
index 2b3cae0c..d0502dd7 100644
--- a/openapi/localize_test.go
+++ b/openapi/localize_test.go
@@ -2,6 +2,8 @@ package openapi_test
import (
"bytes"
+ "crypto/sha256"
+ "fmt"
"net/http"
"net/http/httptest"
"os"
@@ -181,6 +183,93 @@ func TestLocalize_CounterBased_Success(t *testing.T) {
}
}
+func TestLocalize_CustomNaming_Success(t *testing.T) {
+ t.Parallel()
+
+ ctx := t.Context()
+
+ // Create a mock HTTP server to serve remote schemas
+ server := createMockRemoteServer(t)
+ defer server.Close()
+
+ // Load the input document
+ inputFile, err := os.Open("testdata/localize/input/spec.yaml")
+ require.NoError(t, err)
+ defer inputFile.Close()
+
+ inputDoc, validationErrs, err := openapi.Unmarshal(ctx, inputFile)
+ require.NoError(t, err)
+ require.Empty(t, validationErrs, "Input document should be valid")
+
+ // Create a temporary directory for output
+ tempDir := t.TempDir()
+
+ // Create custom HTTP client that redirects api.example.com to our test server
+ httpClient := createRedirectHTTPClient(server.URL)
+
+ // Track which refs the custom naming function is called with
+ var calledRefs []string
+
+ // Custom naming function that uses a content SHA prefix (similar to speakeasy bundler)
+ customNaming := func(originalRef string, content []byte) string {
+ calledRefs = append(calledRefs, originalRef)
+
+ base := filepath.Base(originalRef)
+ ext := filepath.Ext(base)
+ if ext == "" {
+ ext = ".yaml"
+ }
+ name := strings.TrimSuffix(base, ext)
+ sha := sha256.Sum256(content)
+ return fmt.Sprintf("%s-%x%s", name, sha[:4], ext)
+ }
+
+ opts := openapi.LocalizeOptions{
+ DocumentLocation: "testdata/localize/input/spec.yaml",
+ TargetDirectory: tempDir,
+ VirtualFS: &system.FileSystem{},
+ HTTPClient: httpClient,
+ NamingStrategy: openapi.LocalizeNamingCustom,
+ CustomNamingFunc: customNaming,
+ }
+
+ err = openapi.Localize(ctx, inputDoc, opts)
+ require.NoError(t, err)
+
+ // Verify the custom naming function was called for each external reference
+ assert.NotEmpty(t, calledRefs, "Custom naming function should have been called")
+
+ // Verify that files with custom names exist in the target directory
+ entries, err := os.ReadDir(tempDir)
+ require.NoError(t, err)
+ assert.NotEmpty(t, entries, "Target directory should contain localized files")
+
+ // All output filenames should contain a hex SHA suffix
+ for _, entry := range entries {
+ assert.Regexp(t, `-[0-9a-f]{8}\.yaml$`, entry.Name(),
+ "File %s should match custom naming pattern", entry.Name())
+ }
+
+ // Verify the document references were rewritten to use the custom filenames
+ var buf bytes.Buffer
+ err = openapi.Marshal(ctx, inputDoc, &buf)
+ require.NoError(t, err)
+ output := buf.String()
+
+ // The output should not contain any of the original external references
+ assert.NotContains(t, output, "./components.yaml")
+ assert.NotContains(t, output, "./api/components.yaml")
+ assert.NotContains(t, output, "./shared/address.yaml")
+ assert.NotContains(t, output, "https://api.example.com/schemas/")
+
+ // The main document should reference custom-named files (only direct refs, not transitive ones)
+ // Transitive refs (category, geo, metadata) live inside the localized files, not the main doc
+ assert.Contains(t, output, "components-")
+ assert.Contains(t, output, "address-")
+ assert.Contains(t, output, "UserProfile-")
+ assert.Contains(t, output, "UserPreferences-")
+}
+
// createMockRemoteServer creates a mock HTTP server that serves remote schema files
func createMockRemoteServer(t *testing.T) *httptest.Server {
t.Helper()
diff --git a/openapi/mediatype.go b/openapi/mediatype.go
index 6cc46c90..c4018499 100644
--- a/openapi/mediatype.go
+++ b/openapi/mediatype.go
@@ -2,6 +2,7 @@ package openapi
import (
"context"
+ "errors"
"strings"
"github.com/speakeasy-api/openapi/extensions"
@@ -136,11 +137,7 @@ func (m *MediaType) Validate(ctx context.Context, opts ...validation.Option) []e
// Validate mutual exclusivity: encoding MUST NOT be present with prefixEncoding or itemEncoding
if core.Encoding.Present && (core.PrefixEncoding.Present || core.ItemEncoding.Present) {
- errs = append(errs, validation.NewValueError(
- validation.NewValueValidationError("encoding field MUST NOT be present when prefixEncoding or itemEncoding is present"),
- core,
- core.Encoding,
- ))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationMutuallyExclusiveFields, errors.New("mediaType.encoding is mutually exclusive with mediaType.prefixEncoding and mediaType.itemEncoding"), core, core.Encoding))
}
// Validate multipart-only constraint for encoding, prefixEncoding, and itemEncoding
@@ -151,27 +148,15 @@ func (m *MediaType) Validate(ctx context.Context, opts ...validation.Option) []e
isFormURLEncoded := strings.ToLower(mtCtx.MediaType) == "application/x-www-form-urlencoded"
if core.PrefixEncoding.Present && !isMultipart {
- errs = append(errs, validation.NewValueError(
- validation.NewValueValidationError("prefixEncoding field SHALL only apply when the media type is multipart"),
- core,
- core.PrefixEncoding,
- ))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationAllowedValues, errors.New("mediaType.prefixEncoding is only valid when the media type is multipart"), core, core.PrefixEncoding))
}
if core.ItemEncoding.Present && !isMultipart {
- errs = append(errs, validation.NewValueError(
- validation.NewValueValidationError("itemEncoding field SHALL only apply when the media type is multipart"),
- core,
- core.ItemEncoding,
- ))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationAllowedValues, errors.New("mediaType.itemEncoding is only valid when the media type is multipart"), core, core.ItemEncoding))
}
if core.Encoding.Present && !isMultipart && !isFormURLEncoded {
- errs = append(errs, validation.NewValueError(
- validation.NewValueValidationError("encoding field SHALL only apply when the media type is multipart or application/x-www-form-urlencoded"),
- core,
- core.Encoding,
- ))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationAllowedValues, errors.New("mediaType.encoding is only valid when the media type is multipart or application/x-www-form-urlencoded"), core, core.Encoding))
}
}
diff --git a/openapi/mediatype_multipart_validate_test.go b/openapi/mediatype_multipart_validate_test.go
index 03a66e39..0e796cec 100644
--- a/openapi/mediatype_multipart_validate_test.go
+++ b/openapi/mediatype_multipart_validate_test.go
@@ -108,14 +108,14 @@ func TestMediaType_MultipartValidation_Error(t *testing.T) {
yml: `
description: Test response
content:
- application/json:
- schema:
- type: array
- prefixEncoding:
- - contentType: application/json
+ application/json:
+ schema:
+ type: array
+ prefixEncoding:
+ - contentType: application/json
`,
wantErrs: []string{
- "prefixEncoding field SHALL only apply when the media type is multipart",
+ "error validation-allowed-values mediaType.prefixEncoding is only valid when the media type is multipart",
},
},
{
@@ -123,14 +123,14 @@ content:
yml: `
description: Test response
content:
- application/json:
- itemSchema:
- type: object
- itemEncoding:
- contentType: application/json
+ application/json:
+ itemSchema:
+ type: object
+ itemEncoding:
+ contentType: application/json
`,
wantErrs: []string{
- "itemEncoding field SHALL only apply when the media type is multipart",
+ "error validation-allowed-values mediaType.itemEncoding is only valid when the media type is multipart",
},
},
{
@@ -138,18 +138,18 @@ content:
yml: `
description: Test response
content:
- application/json:
- schema:
- type: object
- properties:
- file:
- type: string
- encoding:
- file:
- contentType: image/png
+ application/json:
+ schema:
+ type: object
+ properties:
+ file:
+ type: string
+ encoding:
+ file:
+ contentType: image/png
`,
wantErrs: []string{
- "encoding field SHALL only apply when the media type is multipart or application/x-www-form-urlencoded",
+ "error validation-allowed-values mediaType.encoding is only valid when the media type is multipart or application/x-www-form-urlencoded",
},
},
}
diff --git a/openapi/mediatype_validate_test.go b/openapi/mediatype_validate_test.go
index eace23f0..cf224582 100644
--- a/openapi/mediatype_validate_test.go
+++ b/openapi/mediatype_validate_test.go
@@ -220,8 +220,8 @@ encoding:
type: invalid-type
`,
wantErrs: []string{
- "[13:17] schema.type value must be one of 'array', 'boolean', 'integer', 'null', 'number', 'object', 'string'",
- "[13:17] schema.type expected array, got string",
+ "[13:17] error validation-invalid-schema schema.type value must be one of 'array', 'boolean', 'integer', 'null', 'number', 'object', 'string'",
+ "[13:17] error validation-type-mismatch schema.type expected `array`, got `string`",
},
},
{
@@ -239,7 +239,7 @@ prefixEncoding:
- contentType: application/json
`,
wantErrs: []string{
- "[8:3] encoding field MUST NOT be present when prefixEncoding or itemEncoding is present",
+ "[8:3] error validation-mutually-exclusive-fields mediaType.encoding is mutually exclusive with mediaType.prefixEncoding and mediaType.itemEncoding",
},
},
{
@@ -257,7 +257,7 @@ itemEncoding:
contentType: application/json
`,
wantErrs: []string{
- "[8:3] encoding field MUST NOT be present when prefixEncoding or itemEncoding is present",
+ "[8:3] error validation-mutually-exclusive-fields mediaType.encoding is mutually exclusive with mediaType.prefixEncoding and mediaType.itemEncoding",
},
},
}
diff --git a/openapi/multifile_test.go b/openapi/multifile_test.go
new file mode 100644
index 00000000..5267de20
--- /dev/null
+++ b/openapi/multifile_test.go
@@ -0,0 +1,156 @@
+package openapi_test
+
+import (
+ "bytes"
+ "os"
+ "testing"
+
+ "github.com/speakeasy-api/openapi/openapi"
+ "github.com/speakeasy-api/openapi/references"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func Test_MultiFile_BasicReferences(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ // Read the root OpenAPI file
+ data, err := os.ReadFile("testdata/multifile-basic/openapi.yaml")
+ require.NoError(t, err, "failed to read openapi.yaml")
+
+ // Unmarshal the document
+ doc, validationErrs, err := openapi.Unmarshal(ctx, bytes.NewReader(data))
+ require.NoError(t, err, "unmarshal should succeed")
+ require.NotNil(t, doc, "document should not be nil")
+
+ t.Logf("Unmarshal validation errors: %d", len(validationErrs))
+ for _, verr := range validationErrs {
+ t.Logf(" - %v", verr)
+ }
+
+ // Build index with proper resolve options
+ resolveOpts := references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "testdata/multifile-basic/openapi.yaml",
+ }
+
+ index := openapi.BuildIndex(ctx, doc, resolveOpts)
+ require.NotNil(t, index, "index should not be nil")
+
+ // Check for index errors
+ indexErrors := index.GetAllErrors()
+ t.Logf("Index errors: %d", len(indexErrors))
+ for i, ierr := range indexErrors {
+ t.Logf(" %d: %v", i+1, ierr)
+ }
+
+ // The key test: verify no "source is nil" errors
+ sourceNilErrors := []error{}
+ for _, ierr := range indexErrors {
+ if assert.Contains(t, ierr.Error(), "source is nil") {
+ sourceNilErrors = append(sourceNilErrors, ierr)
+ }
+ }
+
+ if len(sourceNilErrors) > 0 {
+ t.Errorf("Found %d 'source is nil' errors - this indicates reference resolution failure:", len(sourceNilErrors))
+ for i, err := range sourceNilErrors {
+ t.Logf(" %d: %v", i+1, err)
+ }
+ t.FailNow()
+ }
+
+ // Verify external components were indexed
+ t.Logf("External schemas: %d", len(index.ExternalSchemas))
+ t.Logf("External responses: %d", len(index.ExternalResponses))
+ t.Logf("External headers: %d", len(index.ExternalHeaders))
+ t.Logf("External links: %d", len(index.ExternalLinks))
+ t.Logf("External callbacks: %d", len(index.ExternalCallbacks))
+ t.Logf("External pathItems: %d", len(index.ExternalPathItems))
+
+ // We should have external components from components.yaml
+ assert.NotEmpty(t, index.ExternalSchemas, "should have external schemas")
+ assert.NotEmpty(t, index.ExternalResponses, "should have external responses")
+ assert.NotEmpty(t, index.ExternalHeaders, "should have external headers")
+ assert.NotEmpty(t, index.ExternalLinks, "should have external links")
+ assert.NotEmpty(t, index.ExternalCallbacks, "should have external callbacks")
+ assert.NotEmpty(t, index.ExternalPathItems, "should have external pathItems")
+
+ // Verify references can be resolved
+ t.Run("references resolve successfully", func(t *testing.T) {
+ t.Parallel()
+ // Get the operation that has the external response reference
+ require.NotNil(t, doc.Paths, "paths should not be nil")
+ pathItemRef, found := doc.Paths.Get("/test")
+ require.True(t, found, "should find /test path")
+ require.NotNil(t, pathItemRef, "pathItem should not be nil")
+
+ // Get the actual PathItem (may need to resolve if it's a reference)
+ if pathItemRef.IsReference() {
+ _, err := pathItemRef.Resolve(ctx, resolveOpts)
+ require.NoError(t, err, "pathItem should resolve")
+ }
+ pathItem := pathItemRef.GetObject()
+ require.NotNil(t, pathItem, "resolved pathItem should not be nil")
+ getOp := pathItem.Get()
+ require.NotNil(t, getOp, "should have GET operation")
+
+ // Try to resolve the 200 response reference
+ require.NotNil(t, getOp.Responses, "responses should not be nil")
+ response200, found := getOp.Responses.Get("200")
+ require.True(t, found, "should have 200 response")
+ require.True(t, response200.IsReference(), "200 response should be a reference")
+
+ // Resolve it
+ validationErrs, err := response200.Resolve(ctx, resolveOpts)
+ require.NoError(t, err, "resolving 200 response should not error")
+ assert.Empty(t, validationErrs, "should have no validation errors")
+
+ // Verify the resolved object
+ resolvedResponse := response200.GetObject()
+ require.NotNil(t, resolvedResponse, "resolved response should not be nil")
+ assert.Equal(t, "Successful response", resolvedResponse.Description, "should have correct description")
+ })
+}
+
+// Test the specific pattern: external file with internal component references
+// This is failing because when resolving a component from an external file,
+// internal references within that component (#/components/...) cannot be resolved
+func Test_MultiFile_InternalReferencesInExternalFile(t *testing.T) {
+ t.Parallel()
+ ctx := t.Context()
+
+ data, err := os.ReadFile("testdata/multifile-simple/openapi.yaml")
+ require.NoError(t, err)
+
+ doc, _, err := openapi.Unmarshal(ctx, bytes.NewReader(data))
+ require.NoError(t, err)
+ require.NotNil(t, doc)
+
+ resolveOpts := references.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "testdata/multifile-simple/openapi.yaml",
+ }
+
+ index := openapi.BuildIndex(ctx, doc, resolveOpts)
+ require.NotNil(t, index)
+
+ indexErrors := index.GetAllErrors()
+ t.Logf("Index errors: %d", len(indexErrors))
+ for i, ierr := range indexErrors {
+ t.Logf(" %d: %v", i+1, ierr)
+ }
+
+ // This test demonstrates the bug:
+ // When TestResponse (from components.yaml) contains an internal reference
+ // to #/components/schemas/TestSchema, that reference cannot be resolved
+ // because the external file is not unmarshalled as a full document
+ for _, ierr := range indexErrors {
+ if assert.Contains(t, ierr.Error(), "source is nil") {
+ t.Logf("BUG CONFIRMED: %v", ierr)
+ }
+ }
+}
diff --git a/openapi/nested_reference_tracking_test.go b/openapi/nested_reference_tracking_test.go
index f706c7ab..39d01141 100644
--- a/openapi/nested_reference_tracking_test.go
+++ b/openapi/nested_reference_tracking_test.go
@@ -393,3 +393,105 @@ paths:
topLevelRef := resolvedSchema.GetTopLevelReference()
assert.Nil(t, topLevelRef, "inline schema should have no top-level reference")
}
+
+// TestGetReferenceChain_NestedProperty tests that reference chains are properly maintained
+// when accessing a schema through a property of another schema.
+//
+// This is a regression test for a bug where nested property references would lose their
+// parent chain context, returning only the immediate reference instead of the full chain.
+//
+// Expected: ContainerSchema.nested → SharedSchema should have chain [ContainerSchema, SharedSchema]
+// Bug was: Chain only contained [SharedSchema], losing the parent context
+func TestGetReferenceChain_NestedProperty(t *testing.T) {
+ t.Parallel()
+
+ ctx := t.Context()
+
+ yml := `openapi: "3.1.0"
+info:
+ title: Test API
+ version: 1.0.0
+paths:
+ /container:
+ get:
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/ContainerSchema"
+components:
+ schemas:
+ SharedSchema:
+ type: object
+ properties:
+ value:
+ type: string
+ ContainerSchema:
+ type: object
+ properties:
+ nested:
+ $ref: "#/components/schemas/SharedSchema"
+`
+
+ doc, validationErrs, err := Unmarshal(ctx, bytes.NewBufferString(yml))
+ require.NoError(t, err, "should parse OpenAPI document")
+ assert.Empty(t, validationErrs, "should have no validation errors")
+
+ // Get the ContainerSchema from the path response
+ pathItem, _ := doc.Paths.Get("/container")
+ require.NotNil(t, pathItem.GetObject(), "should have path item")
+
+ getOp := pathItem.GetObject().Get()
+ require.NotNil(t, getOp, "should have GET operation")
+
+ response, _ := getOp.Responses.Get("200")
+ require.NotNil(t, response.GetObject(), "should have response")
+
+ containerSchema, _ := response.GetObject().Content.Get("application/json")
+ require.NotNil(t, containerSchema.Schema, "should have schema")
+
+ // Resolve ContainerSchema
+ _, err = containerSchema.Schema.Resolve(ctx, oas3.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ require.NoError(t, err, "should resolve container schema")
+
+ containerResolved := containerSchema.Schema.MustGetResolvedSchema()
+ props := containerResolved.GetSchema().GetProperties()
+ nestedProp, _ := props.Get("nested")
+ require.NotNil(t, nestedProp, "should have nested property")
+
+ // Resolve the nested property
+ _, err = nestedProp.Resolve(ctx, oas3.ResolveOptions{
+ RootDocument: doc,
+ TargetDocument: doc,
+ TargetLocation: "test.yaml",
+ })
+ require.NoError(t, err, "should resolve nested property")
+
+ // Get the reference chain for the nested property
+ // This should include BOTH ContainerSchema and SharedSchema
+ nestedResolved := nestedProp.MustGetResolvedSchema()
+ chain := nestedResolved.GetReferenceChain()
+
+ require.Len(t, chain, 2, "reference chain should include both parent and target schemas")
+ assert.Equal(t, "#/components/schemas/ContainerSchema", string(chain[0].Reference),
+ "first entry should be the parent schema (ContainerSchema)")
+ assert.Equal(t, "#/components/schemas/SharedSchema", string(chain[1].Reference),
+ "second entry should be the target schema (SharedSchema)")
+
+ // Verify convenience methods
+ immediateRef := nestedResolved.GetImmediateReference()
+ require.NotNil(t, immediateRef, "should have immediate reference")
+ assert.Equal(t, "#/components/schemas/SharedSchema", string(immediateRef.Reference),
+ "immediate reference should be SharedSchema")
+
+ topLevelRef := nestedResolved.GetTopLevelReference()
+ require.NotNil(t, topLevelRef, "should have top-level reference")
+ assert.Equal(t, "#/components/schemas/ContainerSchema", string(topLevelRef.Reference),
+ "top-level reference should be ContainerSchema")
+}
diff --git a/openapi/openapi.go b/openapi/openapi.go
index 0cb42c17..bfcf2efa 100644
--- a/openapi/openapi.go
+++ b/openapi/openapi.go
@@ -2,7 +2,9 @@ package openapi
import (
"context"
+ "fmt"
"net/url"
+ "strings"
"github.com/speakeasy-api/openapi/extensions"
"github.com/speakeasy-api/openapi/internal/interfaces"
@@ -13,6 +15,7 @@ import (
"github.com/speakeasy-api/openapi/pointer"
"github.com/speakeasy-api/openapi/sequencedmap"
"github.com/speakeasy-api/openapi/validation"
+ "gopkg.in/yaml.v3"
)
// Version is the version of the OpenAPI Specification that this package conforms to.
@@ -219,11 +222,11 @@ func (o *OpenAPI) Validate(ctx context.Context, opts ...validation.Option) []err
docVersion, err := version.Parse(o.OpenAPI)
if err != nil {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("openapi.openapi invalid OpenAPI version %s: %s", o.OpenAPI, err.Error()), core, core.OpenAPI))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationSupportedVersion, fmt.Errorf("openapi.openapi invalid OpenAPI version %s: %w", o.OpenAPI, err), core, core.OpenAPI))
}
if docVersion != nil {
if docVersion.LessThan(*MinimumSupportedVersion) || docVersion.GreaterThan(*MaximumSupportedVersion) {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("openapi.openapi only OpenAPI versions between %s and %s are supported", MinimumSupportedVersion, MaximumSupportedVersion), core, core.OpenAPI))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationSupportedVersion, fmt.Errorf("openapi.openapi only OpenAPI versions between %s and %s are supported", MinimumSupportedVersion, MaximumSupportedVersion), core, core.OpenAPI))
}
}
@@ -259,17 +262,191 @@ func (o *OpenAPI) Validate(ctx context.Context, opts ...validation.Option) []err
if core.Self.Present && o.Self != nil {
if _, err := url.Parse(*o.Self); err != nil {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("openapi.$self is not a valid uri reference: %s", err), core, core.Self))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationInvalidFormat, fmt.Errorf("openapi.$self is not a valid uri reference: %w", err), core, core.Self))
}
}
if core.JSONSchemaDialect.Present && o.JSONSchemaDialect != nil {
if _, err := url.Parse(*o.JSONSchemaDialect); err != nil {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("openapi.jsonSchemaDialect is not a valid uri: %s", err), core, core.JSONSchemaDialect))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationInvalidFormat, fmt.Errorf("`openapi.jsonSchemaDialect` is not a valid uri: %w", err), core, core.JSONSchemaDialect))
}
}
+ operationIdErrs := validateOperationIDUniqueness(ctx, o)
+ errs = append(errs, operationIdErrs...)
+
+ operationParameterErrs := validateOperationParameterUniqueness(ctx, o)
+ errs = append(errs, operationParameterErrs...)
+
o.Valid = len(errs) == 0 && core.GetValid()
return errs
}
+
+func validateOperationIDUniqueness(ctx context.Context, doc *OpenAPI) []error {
+ if doc == nil {
+ return nil
+ }
+
+ seen := make(map[string]struct{})
+ var errs []error
+
+ for item := range Walk(ctx, doc) {
+ if err := item.Match(Matcher{
+ Operation: func(op *Operation) error {
+ method, path := ExtractMethodAndPath(item.Location)
+ if method == "" || path == "" {
+ return nil
+ }
+
+ operationID := op.GetOperationID()
+ if operationID == "" {
+ return nil
+ }
+
+ if _, ok := seen[operationID]; ok {
+ errNode := getOperationIDValueNode(op)
+ if errNode == nil {
+ errNode = op.GetRootNode()
+ }
+ err := validation.NewValidationError(
+ validation.SeverityError,
+ validation.RuleValidationOperationIdUnique,
+ fmt.Errorf("the `%s` operation at path `%s` contains a duplicate operationId `%s`", method, path, operationID),
+ errNode,
+ )
+ errs = append(errs, err)
+ return nil
+ }
+
+ seen[operationID] = struct{}{}
+ return nil
+ },
+ }); err != nil {
+ errs = append(errs, err)
+ }
+ }
+
+ return errs
+}
+
+func getOperationIDValueNode(op *Operation) *yaml.Node {
+ if op == nil {
+ return nil
+ }
+
+ core := op.GetCore()
+ if core == nil || !core.OperationID.Present {
+ return nil
+ }
+
+ return core.OperationID.ValueNode
+}
+
+// validateParameterUniqueness checks for duplicate parameters in a list
+// methodOrLevel should be the HTTP method (GET, POST, etc.) or "TOP" for path-level
+func validateParameterUniqueness(parameters []*ReferencedParameter, methodOrLevel, path string, fallbackNode *yaml.Node) []error {
+ if len(parameters) == 0 {
+ return nil
+ }
+
+ var errs []error
+ seen := make(map[string]bool)
+
+ for _, paramRef := range parameters {
+ param := paramRef.GetObject()
+ if param == nil {
+ continue
+ }
+
+ paramName := param.GetName()
+ paramIn := param.GetIn().String()
+ if paramName == "" || paramIn == "" {
+ continue
+ }
+
+ key := paramName + "::" + paramIn
+ if seen[key] {
+ core := param.GetCore()
+ errNode := core.GetRootNode()
+ if errNode == nil {
+ errNode = fallbackNode
+ }
+
+ var errMsg string
+ if methodOrLevel == "TOP" {
+ errMsg = fmt.Sprintf("parameter %q is duplicated in path %q", paramName, path)
+ } else {
+ errMsg = fmt.Sprintf("parameter %q is duplicated in %s operation at path %q", paramName, methodOrLevel, path)
+ }
+
+ err := validation.NewValidationError(
+ validation.SeverityError,
+ validation.RuleValidationOperationParameters,
+ fmt.Errorf("%s", errMsg),
+ errNode,
+ )
+ errs = append(errs, err)
+ }
+ seen[key] = true
+ }
+
+ return errs
+}
+
+func validateOperationParameterUniqueness(ctx context.Context, doc *OpenAPI) []error {
+ if doc == nil {
+ return nil
+ }
+
+ var errs []error
+
+ for item := range Walk(ctx, doc) {
+ if err := item.Match(Matcher{
+ // Check duplicate parameters at Operation level
+ Operation: func(op *Operation) error {
+ method, path := ExtractMethodAndPath(item.Location)
+ if method == "" || path == "" {
+ return nil
+ }
+
+ paramErrs := validateParameterUniqueness(
+ op.GetParameters(),
+ strings.ToUpper(method),
+ path,
+ op.GetRootNode(),
+ )
+ errs = append(errs, paramErrs...)
+
+ return nil
+ },
+ // Check duplicate parameters at PathItem level
+ ReferencedPathItem: func(refPathItem *ReferencedPathItem) error {
+ pathItem := refPathItem.GetObject()
+ if pathItem == nil {
+ return nil
+ }
+
+ // Get the path from the location (parent key)
+ path := item.Location.ParentKey()
+ if path == "" {
+ return nil
+ }
+
+ paramErrs := validateParameterUniqueness(
+ pathItem.Parameters,
+ "TOP",
+ path,
+ pathItem.GetRootNode(),
+ )
+ errs = append(errs, paramErrs...)
+
+ return nil
+ },
+ }); err != nil {
+ errs = append(errs, err)
+ }
+ }
+
+ return errs
+}
diff --git a/openapi/openapi_examples_test.go b/openapi/openapi_examples_test.go
index 01565b08..f4f50c86 100644
--- a/openapi/openapi_examples_test.go
+++ b/openapi/openapi_examples_test.go
@@ -254,22 +254,22 @@ func Example_validating() {
fmt.Printf("\nReduced validation errors from %d to %d\n", len(validationErrs), len(newValidationErrs))
// Output: Initial validation errors: 16
- // [3:3] info.version is missing
- // [22:17] schema.type.0 expected string, got null
- // [28:30] response.content.application/json expected object, got ``
- // [31:18] responses must have at least one response code
- // [34:7] operation.responses is missing
- // [43:17] schema.properties.required failed to validate either Schema [schema.properties.required expected object, got sequence] or bool [schema.properties.required expected bool, got sequence]
- // [51:25] schema.properties.name.type expected array, got string
- // [51:25] schema.properties.name.type value must be one of 'array', 'boolean', 'integer', 'null', 'number', 'object', 'string'
- // [56:7] schema.examples expected array, got object
- // [59:15] schema.properties.name expected one of [boolean, object], got string
- // [59:15] schema.properties.name expected one of [boolean, object], got string
- // [59:15] schema.properties.name failed to validate either Schema [schema.properties.name expected object, got `str...`] or bool [schema.properties.name line 59: cannot unmarshal !!str `string` into bool]
- // [60:18] schema.properties.example expected one of [boolean, object], got string
- // [60:18] schema.properties.example expected one of [boolean, object], got string
- // [60:18] schema.properties.example failed to validate either Schema [schema.properties.example expected object, got `John Do...`] or bool [schema.properties.example line 60: cannot unmarshal !!str `John Doe` into bool]
- // [63:9] schema.examples expected sequence, got object
+ // [3:3] error validation-required-field `info.version` is required
+ // [22:17] error validation-type-mismatch schema.type.0 expected `string`, got `null`
+ // [28:30] error validation-type-mismatch response.content.application/json expected `object`, got ``
+ // [31:18] error validation-allowed-values responses must have at least one response code
+ // [34:7] error validation-required-field `operation.responses` is required
+ // [43:17] error validation-type-mismatch schema.properties.required failed to validate either Schema [schema.properties.required expected `object`, got `sequence`] or bool [schema.properties.required expected `bool`, got `sequence`]
+ // [51:25] error validation-invalid-schema schema.properties.name.type value must be one of 'array', 'boolean', 'integer', 'null', 'number', 'object', 'string'
+ // [51:25] error validation-type-mismatch schema.properties.name.type expected `array`, got `string`
+ // [56:7] error validation-type-mismatch schema.examples expected `array`, got `object`
+ // [59:15] error validation-type-mismatch schema.properties.name expected one of [`boolean`, `object`], got `string`
+ // [59:15] error validation-type-mismatch schema.properties.name expected one of [`boolean`, `object`], got `string`
+ // [59:15] error validation-type-mismatch schema.properties.name failed to validate either Schema [schema.properties.name expected `object`, got `str...`] or bool [schema.properties.name line 59: cannot unmarshal !!str `string` into bool]
+ // [60:18] error validation-type-mismatch schema.properties.example expected one of [`boolean`, `object`], got `string`
+ // [60:18] error validation-type-mismatch schema.properties.example expected one of [`boolean`, `object`], got `string`
+ // [60:18] error validation-type-mismatch schema.properties.example failed to validate either Schema [schema.properties.example expected `object`, got `John Do...`] or bool [schema.properties.example line 60: cannot unmarshal !!str `John Doe` into bool]
+ // [63:9] error validation-type-mismatch schema.examples expected `sequence`, got `object`
//
// Fixing validation errors...
// ✓ Added missing info.version
@@ -277,13 +277,13 @@ func Example_validating() {
// ✓ Added missing responses to POST /invalid
//
// Validation errors after fixes: 7
- // [51:25] schema.properties.name.type expected array, got string
- // [51:25] schema.properties.name.type value must be one of 'array', 'boolean', 'integer', 'null', 'number', 'object', 'string'
- // [56:7] schema.examples expected array, got object
- // [59:15] schema.properties.name expected one of [boolean, object], got string
- // [59:15] schema.properties.name expected one of [boolean, object], got string
- // [60:18] schema.properties.example expected one of [boolean, object], got string
- // [60:18] schema.properties.example expected one of [boolean, object], got string
+ // [51:25] error validation-invalid-schema schema.properties.name.type value must be one of 'array', 'boolean', 'integer', 'null', 'number', 'object', 'string'
+ // [51:25] error validation-type-mismatch schema.properties.name.type expected `array`, got `string`
+ // [56:7] error validation-type-mismatch schema.examples expected `array`, got `object`
+ // [59:15] error validation-type-mismatch schema.properties.name expected one of [`boolean`, `object`], got `string`
+ // [59:15] error validation-type-mismatch schema.properties.name expected one of [`boolean`, `object`], got `string`
+ // [60:18] error validation-type-mismatch schema.properties.example expected one of [`boolean`, `object`], got `string`
+ // [60:18] error validation-type-mismatch schema.properties.example expected one of [`boolean`, `object`], got `string`
//
// Reduced validation errors from 16 to 7
}
diff --git a/openapi/openapi_unmarshal_test.go b/openapi/openapi_unmarshal_test.go
index b3ed5de5..51d659f9 100644
--- a/openapi/openapi_unmarshal_test.go
+++ b/openapi/openapi_unmarshal_test.go
@@ -120,15 +120,15 @@ func TestOpenAPI_Unmarshal_Error(t *testing.T) {
version: 1.0.0
paths: {}`,
wantErrs: []string{
- "[1:1] openapi.openapi invalid OpenAPI version : invalid version ",
- "[1:1] openapi.openapi is missing",
+ "[1:1] error validation-required-field `openapi.openapi` is required",
+ "[1:1] error validation-supported-version openapi.openapi invalid OpenAPI version : invalid version ",
},
},
{
name: "missing info field",
yaml: `openapi: 3.1.0
paths: {}`,
- wantErrs: []string{"[1:1] openapi.info is missing"},
+ wantErrs: []string{"[1:1] error validation-required-field `openapi.info` is required"},
},
{
name: "invalid openapi version",
@@ -137,7 +137,7 @@ info:
title: Test API
version: 1.0.0
paths: {}`,
- wantErrs: []string{fmt.Sprintf("[1:10] openapi.openapi only OpenAPI versions between %s and %s are supported", openapi.MinimumSupportedVersion, openapi.MaximumSupportedVersion)},
+ wantErrs: []string{fmt.Sprintf("[1:10] error validation-supported-version openapi.openapi only OpenAPI versions between %s and %s are supported", openapi.MinimumSupportedVersion, openapi.MaximumSupportedVersion)},
},
}
diff --git a/openapi/openapi_validate_test.go b/openapi/openapi_validate_test.go
index f7bd6703..a06c7762 100644
--- a/openapi/openapi_validate_test.go
+++ b/openapi/openapi_validate_test.go
@@ -196,7 +196,7 @@ info:
version: 1.0.0
paths: {}
`,
- wantErrs: []string{"openapi.openapi invalid OpenAPI version invalid-version"},
+ wantErrs: []string{"error validation-supported-version openapi.openapi invalid OpenAPI version invalid-version"},
},
{
name: "unsupported_openapi_version",
@@ -207,7 +207,7 @@ info:
version: 1.0.0
paths: {}
`,
- wantErrs: []string{"openapi.openapi only OpenAPI versions between"},
+ wantErrs: []string{"error validation-supported-version openapi.openapi only OpenAPI versions between"},
},
{
name: "invalid_info_missing_title",
@@ -217,7 +217,7 @@ info:
version: 1.0.0
paths: {}
`,
- wantErrs: []string{"[4:3] info.title is missing"},
+ wantErrs: []string{"[4:3] error validation-required-field `info.title` is required"},
},
{
name: "invalid_info_missing_version",
@@ -227,7 +227,7 @@ info:
title: Test API
paths: {}
`,
- wantErrs: []string{"[4:3] info.version is missing"},
+ wantErrs: []string{"[4:3] error validation-required-field `info.version` is required"},
},
{
name: "invalid_server",
@@ -240,7 +240,7 @@ servers:
- description: Invalid server without URL
paths: {}
`,
- wantErrs: []string{"[7:5] server.url is missing"},
+ wantErrs: []string{"[7:5] error validation-required-field `server.url` is required"},
},
{
name: "invalid_tag",
@@ -253,7 +253,7 @@ tags:
- description: Tag without name
paths: {}
`,
- wantErrs: []string{"[7:5] tag.name is missing"},
+ wantErrs: []string{"[7:5] error validation-required-field `tag.name` is required"},
},
{
name: "invalid_external_docs",
@@ -266,7 +266,7 @@ externalDocs:
description: External docs without URL
paths: {}
`,
- wantErrs: []string{"[7:3] externalDocumentation.url is missing"},
+ wantErrs: []string{"[7:3] error validation-required-field `externalDocumentation.url` is required"},
},
{
name: "invalid_self_not_uri",
@@ -278,7 +278,84 @@ info:
version: 1.0.0
paths: {}
`,
- wantErrs: []string{"openapi.$self is not a valid uri reference"},
+ wantErrs: []string{"error validation-invalid-format openapi.$self is not a valid uri reference"},
+ },
+ {
+ name: "duplicate_operation_id",
+ yml: `
+openapi: 3.1.0
+info:
+ title: Test API
+ version: 1.0.0
+paths:
+ /melody:
+ post:
+ operationId: littleSong
+ responses:
+ '200':
+ description: ok
+ /ember:
+ get:
+ operationId: littleSong
+ responses:
+ '200':
+ description: ok
+`,
+ wantErrs: []string{"error validation-operation-id-unique the `get` operation at path `/ember` contains a duplicate operationId `littleSong`"},
+ },
+ {
+ name: "duplicate_operation_parameter",
+ yml: `
+openapi: 3.1.0
+info:
+ title: Test API
+ version: 1.0.0
+paths:
+ /users/{id}:
+ get:
+ parameters:
+ - in: path
+ name: id
+ required: true
+ schema:
+ type: string
+ - in: path
+ name: id
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: ok
+`,
+ wantErrs: []string{"error validation-operation-parameters parameter \"id\" is duplicated in GET operation at path \"/users/{id}\""},
+ },
+ {
+ name: "duplicate_pathitem_parameter",
+ yml: `
+openapi: 3.1.0
+info:
+ title: Test API
+ version: 1.0.0
+paths:
+ /users/{id}:
+ parameters:
+ - in: path
+ name: id
+ required: true
+ schema:
+ type: string
+ - in: path
+ name: id
+ required: true
+ schema:
+ type: string
+ get:
+ responses:
+ '200':
+ description: ok
+`,
+ wantErrs: []string{"error validation-operation-parameters parameter \"id\" is duplicated in path \"/users/{id}\""},
},
}
diff --git a/openapi/operation_validate_test.go b/openapi/operation_validate_test.go
index 92c878d6..30ebd333 100644
--- a/openapi/operation_validate_test.go
+++ b/openapi/operation_validate_test.go
@@ -139,7 +139,7 @@ externalDocs:
description: Invalid docs
url: ":invalid"
`,
- wantErrs: []string{"[7:8] externalDocumentation.url is not a valid uri: parse \":invalid\": missing protocol scheme"},
+ wantErrs: []string{"[7:8] warning validation-invalid-format externalDocumentation.url is not a valid uri: parse \":invalid\": missing protocol scheme"},
},
{
name: "invalid server URL",
@@ -151,7 +151,7 @@ servers:
- url: ":invalid"
description: Invalid server
`,
- wantErrs: []string{"[6:10] server.url is not a valid uri: parse \":invalid\": missing protocol scheme"},
+ wantErrs: []string{"[6:10] error validation-invalid-format `server.url` is not a valid uri: parse \":invalid\": missing protocol scheme"},
},
}
diff --git a/openapi/parameter.go b/openapi/parameter.go
index 68304dce..0ff38226 100644
--- a/openapi/parameter.go
+++ b/openapi/parameter.go
@@ -2,6 +2,7 @@ package openapi
import (
"context"
+ "errors"
"fmt"
"slices"
"strings"
@@ -212,51 +213,51 @@ func (p *Parameter) Validate(ctx context.Context, opts ...validation.Option) []e
errs := []error{}
if core.Name.Present && p.Name == "" {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("parameter.name is required"), core, core.Name))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("`parameter.name` is required"), core, core.Name))
}
if core.In.Present && p.In == "" {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("parameter.in is required"), core, core.In))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("`parameter.in` is required"), core, core.In))
} else {
switch p.In {
case ParameterInQuery, ParameterInQueryString, ParameterInHeader, ParameterInPath, ParameterInCookie:
default:
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("parameter.in must be one of [%s]", strings.Join([]string{string(ParameterInQuery), string(ParameterInQueryString), string(ParameterInHeader), string(ParameterInPath), string(ParameterInCookie)}, ", ")), core, core.In))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationAllowedValues, fmt.Errorf("parameter.in must be one of [`%s`]", strings.Join([]string{string(ParameterInQuery), string(ParameterInQueryString), string(ParameterInHeader), string(ParameterInPath), string(ParameterInCookie)}, ", ")), core, core.In))
}
}
if p.In == ParameterInPath && (!core.Required.Present || !*p.Required) {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("parameter.in=path requires required=true"), core, core.Required))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("`parameter.in=path` requires `required=true`"), core, core.Required))
}
if core.AllowEmptyValue.Present && p.In != ParameterInQuery {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("parameter.allowEmptyValue is only valid for in=query"), core, core.AllowEmptyValue))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationAllowedValues, errors.New("`parameter.allowEmptyValue` is only valid for `in=query`"), core, core.AllowEmptyValue))
}
if core.Style.Present {
switch p.In {
case ParameterInQueryString:
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("parameter field style is not allowed for in=querystring"), core, core.Style))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationAllowedValues, errors.New("parameter field style is not allowed for in=querystring"), core, core.Style))
case ParameterInPath:
allowedStyles := []string{string(SerializationStyleSimple), string(SerializationStyleLabel), string(SerializationStyleMatrix)}
if !slices.Contains(allowedStyles, string(*p.Style)) {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("parameter.style must be one of [%s] for in=path", strings.Join(allowedStyles, ", ")), core, core.Style))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationAllowedValues, fmt.Errorf("parameter.style must be one of [`%s`] for in=path", strings.Join(allowedStyles, ", ")), core, core.Style))
}
case ParameterInQuery:
allowedStyles := []string{string(SerializationStyleForm), string(SerializationStyleSpaceDelimited), string(SerializationStylePipeDelimited), string(SerializationStyleDeepObject)}
if !slices.Contains(allowedStyles, string(*p.Style)) {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("parameter.style must be one of [%s] for in=query", strings.Join(allowedStyles, ", ")), core, core.Style))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationAllowedValues, fmt.Errorf("parameter.style must be one of [`%s`] for in=query", strings.Join(allowedStyles, ", ")), core, core.Style))
}
case ParameterInHeader:
allowedStyles := []string{string(SerializationStyleSimple)}
if !slices.Contains(allowedStyles, string(*p.Style)) {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("parameter.style must be one of [%s] for in=header", strings.Join(allowedStyles, ", ")), core, core.Style))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationAllowedValues, fmt.Errorf("parameter.style must be one of [`%s`] for in=header", strings.Join(allowedStyles, ", ")), core, core.Style))
}
case ParameterInCookie:
allowedStyles := []string{string(SerializationStyleForm)}
if !slices.Contains(allowedStyles, string(*p.Style)) {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("parameter.style must be one of [%s] for in=cookie", strings.Join(allowedStyles, ", ")), core, core.Style))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationAllowedValues, fmt.Errorf("parameter.style must be one of [`%s`] for in=cookie", strings.Join(allowedStyles, ", ")), core, core.Style))
}
}
}
@@ -264,7 +265,7 @@ func (p *Parameter) Validate(ctx context.Context, opts ...validation.Option) []e
if core.Schema.Present {
switch p.In {
case ParameterInQueryString:
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("parameter field schema is not allowed for in=querystring"), core, core.Schema))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationAllowedValues, errors.New("`parameter.schema` is not allowed for `in=querystring`"), core, core.Schema))
default:
errs = append(errs, p.Schema.Validate(ctx, opts...)...)
}
@@ -273,11 +274,11 @@ func (p *Parameter) Validate(ctx context.Context, opts ...validation.Option) []e
if !core.Content.Present || p.Content == nil {
// Querystring parameters must use content instead of schema
if p.In == ParameterInQueryString {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("parameter field content is required for in=querystring"), core, core.Content))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("`parameter.content` is required for `in=querystring`"), core, core.Content))
}
} else if p.Content.Len() != 1 {
// If present, content must have exactly one entry
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("parameter field content must have exactly one entry"), core, core.Content))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationAllowedValues, errors.New("`parameter.content` must have exactly one entry"), core, core.Content))
}
for mediaType, obj := range p.Content.All() {
diff --git a/openapi/parameter_validate_test.go b/openapi/parameter_validate_test.go
index 84a17768..729546f5 100644
--- a/openapi/parameter_validate_test.go
+++ b/openapi/parameter_validate_test.go
@@ -181,7 +181,7 @@ in: query
schema:
type: string
`,
- wantErrs: []string{"[2:1] parameter.name is missing"},
+ wantErrs: []string{"[2:1] error validation-required-field `parameter.name` is required"},
},
{
name: "empty name",
@@ -191,7 +191,7 @@ in: query
schema:
type: string
`,
- wantErrs: []string{"[2:7] parameter.name is required"},
+ wantErrs: []string{"[2:7] error validation-required-field `parameter.name` is required"},
},
{
name: "missing in",
@@ -200,7 +200,7 @@ name: test
schema:
type: string
`,
- wantErrs: []string{"[2:1] parameter.in is missing"},
+ wantErrs: []string{"[2:1] error validation-required-field `parameter.in` is required"},
},
{
name: "path parameter not required",
@@ -211,7 +211,7 @@ required: false
schema:
type: string
`,
- wantErrs: []string{"[4:11] parameter.in=path requires required=true"},
+ wantErrs: []string{"[4:11] error validation-required-field `parameter.in=path` requires `required=true`"},
},
{
name: "invalid parameter location",
@@ -221,7 +221,7 @@ in: invalid
schema:
type: string
`,
- wantErrs: []string{"[3:5] parameter.in must be one of [query, querystring, header, path, cookie]"},
+ wantErrs: []string{"[3:5] error validation-allowed-values parameter.in must be one of [`query, querystring, header, path, cookie`]"},
},
{
name: "multiple validation errors",
@@ -231,8 +231,8 @@ in: path
required: false
`,
wantErrs: []string{
- "[2:7] parameter.name is required",
- "[4:11] parameter.in=path requires required=true",
+ "[2:7] error validation-required-field `parameter.name` is required",
+ "[4:11] error validation-required-field `parameter.in=path` requires `required=true`",
},
},
{
@@ -244,8 +244,8 @@ schema:
type: object
`,
wantErrs: []string{
- "parameter field schema is not allowed for in=querystring",
- "parameter field content is required for in=querystring",
+ "error validation-allowed-values `parameter.schema` is not allowed for `in=querystring`",
+ "error validation-required-field `parameter.content` is required for `in=querystring`",
},
},
{
@@ -259,7 +259,7 @@ content:
schema:
type: object
`,
- wantErrs: []string{"parameter field style is not allowed for in=querystring"},
+ wantErrs: []string{"error validation-allowed-values parameter field style is not allowed for in=querystring"},
},
{
name: "querystring parameter missing content",
@@ -268,7 +268,7 @@ name: filter
in: querystring
description: Missing content field
`,
- wantErrs: []string{"parameter field content is required for in=querystring"},
+ wantErrs: []string{"error validation-required-field `parameter.content` is required for `in=querystring`"},
},
{
name: "parameter with multiple content entries",
@@ -283,7 +283,7 @@ content:
schema:
type: object
`,
- wantErrs: []string{"parameter field content must have exactly one entry"},
+ wantErrs: []string{"error validation-allowed-values `parameter.content` must have exactly one entry"},
},
}
diff --git a/openapi/paths.go b/openapi/paths.go
index 1b597781..57fba06e 100644
--- a/openapi/paths.go
+++ b/openapi/paths.go
@@ -2,6 +2,8 @@ package openapi
import (
"context"
+ "fmt"
+ "iter"
"slices"
"strings"
@@ -41,6 +43,14 @@ func (p *Paths) Len() int {
return p.Map.Len()
}
+// All returns an iterator over all path items in the paths map. nil safe.
+func (p *Paths) All() iter.Seq2[string, *ReferencedPathItem] {
+ if p == nil {
+ return func(yield func(string, *ReferencedPathItem) bool) {}
+ }
+ return p.Map.All()
+}
+
// GetExtensions returns the value of the Extensions field. Returns an empty extensions map if not set.
func (p *Paths) GetExtensions() *extensions.Extensions {
if p == nil || p.Extensions == nil {
@@ -102,6 +112,10 @@ func (m HTTPMethod) Is(method string) bool {
return strings.EqualFold(string(m), method)
}
+func (m HTTPMethod) String() string {
+ return string(m)
+}
+
func IsStandardMethod(s string) bool {
return slices.Contains(standardHttpMethods, HTTPMethod(s))
}
@@ -316,20 +330,20 @@ func (p *PathItem) Validate(ctx context.Context, opts ...validation.Option) []er
for methodName, op := range p.AdditionalOperations.All() {
errs = append(errs, op.Validate(ctx, opts...)...)
if IsStandardMethod(strings.ToLower(methodName)) {
- errs = append(errs, validation.NewMapKeyError(validation.NewValueValidationError("method [%s] is a standard HTTP method and must be defined in its own field", methodName), core, core.AdditionalOperations, methodName))
+ errs = append(errs, validation.NewMapKeyError(validation.SeverityError, validation.RuleValidationAllowedValues, fmt.Errorf("pathItem.additionalOperations method [%s] is a standardized HTTP method and must be defined in its own field", methodName), core, core.AdditionalOperations, methodName))
}
}
}
for methodName := range p.Keys() {
if !IsStandardMethod(strings.ToLower(string(methodName))) {
- errs = append(errs, validation.NewMapKeyError(validation.NewValueValidationError("method [%s] is not a standard HTTP method and must be defined in the additionalOperations field", methodName), core, core, string(methodName)))
+ errs = append(errs, validation.NewMapKeyError(validation.SeverityError, validation.RuleValidationAllowedValues, fmt.Errorf("pathItem method [%s] is not a standardized HTTP method and must be listed under additionalOperations", methodName), core, core, methodName.String()))
}
}
case !supportsAdditionalOperations:
if core.AdditionalOperations.Present {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("additionalOperations is not supported in OpenAPI version %s", openapiVersion), core, core.AdditionalOperations))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationSupportedVersion, fmt.Errorf("pathItem.additionalOperations is not supported in OpenAPI version %s", openapiVersion), core, core.AdditionalOperations))
}
}
diff --git a/openapi/paths_validate_test.go b/openapi/paths_validate_test.go
index 30461c26..3e51294e 100644
--- a/openapi/paths_validate_test.go
+++ b/openapi/paths_validate_test.go
@@ -309,7 +309,7 @@ get:
'200':
description: Successful response
`,
- wantErrs: []string{"[3:5] server.url is missing"},
+ wantErrs: []string{"[3:5] error validation-required-field `server.url` is required"},
},
{
name: "invalid_parameter",
@@ -324,7 +324,7 @@ get:
'200':
description: Successful response
`,
- wantErrs: []string{"[3:5] parameter.name is missing"},
+ wantErrs: []string{"[3:5] error validation-required-field `parameter.name` is required"},
},
{
name: "unexpected_additional_operations",
@@ -360,7 +360,7 @@ additionalOperations:
description: Successful response
x-test: some-value
`,
- wantErrs: []string{"method [GET] is a standard HTTP method and must be defined in its own field"},
+ wantErrs: []string{"method [GET] is a standardized HTTP method and must be defined in its own field"},
},
{
name: "invalid_openapi_version",
@@ -384,7 +384,7 @@ copy:
'201':
description: Resource copied
`,
- wantErrs: []string{"method [copy] is not a standard HTTP method and must be defined in the additionalOperations field"},
+ wantErrs: []string{"method [copy] is not a standardized HTTP method and must be listed under additionalOperations"},
},
}
diff --git a/openapi/reference.go b/openapi/reference.go
index c4b4c649..ec5d7c24 100644
--- a/openapi/reference.go
+++ b/openapi/reference.go
@@ -340,6 +340,29 @@ func (r *Reference[T, V, C]) GetDescription() string {
return *r.Description
}
+// GetRootNode returns the root YAML node of the referenced object if it exists.
+// Returns nil if the object is not resolved or doesn't have a root node.
+func (r *Reference[T, V, C]) GetRootNode() *yaml.Node {
+ if r == nil {
+ return nil
+ }
+
+ obj := r.GetObject()
+ if obj == nil {
+ return nil
+ }
+
+ // Try to get the root node from the object via GetRootNode method
+ type nodeWithRootNode interface {
+ GetRootNode() *yaml.Node
+ }
+ if nodeWithRoot, ok := any(obj).(nodeWithRootNode); ok {
+ return nodeWithRoot.GetRootNode()
+ }
+
+ return nil
+}
+
// GetParent returns the immediate parent reference if this reference was resolved via a reference chain.
//
// Returns nil if:
@@ -413,7 +436,7 @@ func (r *Reference[T, V, C]) Validate(ctx context.Context, opts ...validation.Op
if core.Reference.Present {
if err := r.Reference.Validate(); err != nil {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("reference.$ref is invalid: %s", err.Error()), core, core.Reference))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationInvalidSyntax, fmt.Errorf("reference.$ref is invalid: %w", err), core, core.Reference))
}
} else if r.Object != nil {
// Use the validator interface V to validate the object
@@ -617,7 +640,7 @@ func resolveObjectWithTracking[T any, V interfaces.Validator[T], C marshaller.Co
ref.ensureMutex()
ref.cacheMutex.RLock()
targetDoc := ref.referenceResolutionCache.ResolvedDocument
- targetLoc := ref.referenceResolutionCache.AbsoluteReference
+ targetLoc := ref.referenceResolutionCache.AbsoluteDocumentPath
ref.cacheMutex.RUnlock()
opts.TargetDocument = targetDoc
diff --git a/openapi/reference_validate_test.go b/openapi/reference_validate_test.go
index 4468ff55..87e74cba 100644
--- a/openapi/reference_validate_test.go
+++ b/openapi/reference_validate_test.go
@@ -218,7 +218,7 @@ value:
id: 123
externalValue: https://example.com/user.json
`,
- wantErrs: []string{"value and externalValue are mutually exclusive"},
+ wantErrs: []string{"error validation-mutually-exclusive-fields example.value and example.externalValue are mutually exclusive"},
},
}
diff --git a/openapi/requests.go b/openapi/requests.go
index 07560005..9ab850f5 100644
--- a/openapi/requests.go
+++ b/openapi/requests.go
@@ -2,6 +2,7 @@ package openapi
import (
"context"
+ "errors"
"github.com/speakeasy-api/openapi/extensions"
"github.com/speakeasy-api/openapi/internal/interfaces"
@@ -57,7 +58,7 @@ func (r *RequestBody) Validate(ctx context.Context, opts ...validation.Option) [
errs := []error{}
if core.Content.Present && r.Content.Len() == 0 {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("requestBody.content is required"), core, core.Content))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("`requestBody.content` is required"), core, core.Content))
}
for mediaType, content := range r.Content.All() {
diff --git a/openapi/requests_validate_test.go b/openapi/requests_validate_test.go
index 0a571639..79db033b 100644
--- a/openapi/requests_validate_test.go
+++ b/openapi/requests_validate_test.go
@@ -130,7 +130,7 @@ func TestRequestBody_Validate_Error(t *testing.T) {
description: Request body without content
required: true
`,
- wantErrs: []string{"[2:1] requestBody.content is missing"},
+ wantErrs: []string{"[2:1] error validation-required-field `requestBody.content` is required"},
},
{
name: "empty content",
@@ -138,7 +138,7 @@ required: true
content: {}
description: Request body with empty content
`,
- wantErrs: []string{"[2:10] requestBody.content is required"},
+ wantErrs: []string{"[2:10] error validation-required-field `requestBody.content` is required"},
},
{
name: "invalid schema in content",
@@ -150,8 +150,8 @@ content:
description: Request body with invalid schema
`,
wantErrs: []string{
- "[5:13] schema.type value must be one of 'array', 'boolean', 'integer', 'null', 'number', 'object', 'string'",
- "[5:13] schema.type expected array, got string",
+ "[5:13] error validation-invalid-schema schema.type value must be one of 'array', 'boolean', 'integer', 'null', 'number', 'object', 'string'",
+ "[5:13] error validation-type-mismatch schema.type expected `array`, got `string`",
},
},
}
diff --git a/openapi/responses.go b/openapi/responses.go
index 00714624..970ce6cc 100644
--- a/openapi/responses.go
+++ b/openapi/responses.go
@@ -2,6 +2,7 @@ package openapi
import (
"context"
+ "errors"
"fmt"
"github.com/speakeasy-api/openapi/extensions"
@@ -114,7 +115,7 @@ func (r *Responses) Validate(ctx context.Context, opts ...validation.Option) []e
}
if r.Len() == 0 && r.Default == nil {
- errs = append(errs, validation.NewValidationError(validation.NewValueValidationError("responses must have at least one response code"), core.RootNode))
+ errs = append(errs, validation.NewValidationError(validation.SeverityError, validation.RuleValidationAllowedValues, errors.New("responses must have at least one response code"), core.RootNode))
}
for _, response := range r.All() {
@@ -191,7 +192,7 @@ func (r *Response) Validate(ctx context.Context, opts ...validation.Option) []er
errs := []error{}
if core.Description.Present && r.Description == "" {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("response.description is required"), core, core.Description))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("`response.description` is required"), core, core.Description))
}
for _, header := range r.GetHeaders().All() {
diff --git a/openapi/responses_validate_test.go b/openapi/responses_validate_test.go
index 2a44a5f9..c7ae35b2 100644
--- a/openapi/responses_validate_test.go
+++ b/openapi/responses_validate_test.go
@@ -148,7 +148,7 @@ content:
schema:
type: object
`,
- wantErrs: []string{"[2:1] response.description is missing"},
+ wantErrs: []string{"[2:1] error validation-required-field `response.description` is required"},
},
{
name: "empty description",
@@ -159,7 +159,7 @@ content:
schema:
type: object
`,
- wantErrs: []string{"[2:14] response.description is required"},
+ wantErrs: []string{"[2:14] error validation-required-field `response.description` is required"},
},
{
name: "invalid schema in content",
@@ -171,8 +171,8 @@ content:
type: invalid-type
`,
wantErrs: []string{
- "[6:13] schema.type value must be one of 'array', 'boolean', 'integer', 'null', 'number', 'object', 'string'",
- "[6:13] schema.type expected array, got string",
+ "[6:13] error validation-invalid-schema schema.type value must be one of 'array', 'boolean', 'integer', 'null', 'number', 'object', 'string'",
+ "[6:13] error validation-type-mismatch schema.type expected `array`, got `string`",
},
},
}
@@ -298,19 +298,19 @@ func TestResponses_Validate_Error(t *testing.T) {
"404":
description: Not found
`,
- wantErrs: []string{"description is required"},
+ wantErrs: []string{"error validation-required-field `response.description` is required"},
},
{
name: "no response codes",
yml: `
x-test: some-value
`,
- wantErrs: []string{"responses must have at least one response code"},
+ wantErrs: []string{"error validation-allowed-values responses must have at least one response code"},
},
{
name: "empty responses object",
yml: `{}`,
- wantErrs: []string{"responses must have at least one response code"},
+ wantErrs: []string{"error validation-allowed-values responses must have at least one response code"},
},
}
diff --git a/openapi/sanitize.go b/openapi/sanitize.go
index bf37826f..2aa6a985 100644
--- a/openapi/sanitize.go
+++ b/openapi/sanitize.go
@@ -606,10 +606,17 @@ func getCoreModelFromAny(model any) any {
GetCoreAny() any
}
+ var directCore any
if coreModel, ok := model.(coreGetter); ok {
- core := coreModel.GetCoreAny()
- if core != nil {
- return core
+ directCore = coreModel.GetCoreAny()
+ if directCore != nil {
+ if coreModeler, ok := directCore.(marshaller.CoreModeler); ok {
+ if len(coreModeler.GetUnknownProperties()) > 0 {
+ return directCore
+ }
+ } else {
+ return directCore
+ }
}
}
@@ -622,7 +629,48 @@ func getCoreModelFromAny(model any) any {
inner, err := navigable.GetNavigableNode()
if err == nil && inner != nil {
// Recursively try to get core from the inner value
- return getCoreModelFromAny(inner)
+ if innerCore := getCoreModelFromAny(inner); innerCore != nil {
+ return innerCore
+ }
+ }
+ }
+
+ return directCore
+}
+
+// getRootNodeFromAny attempts to extract the root yaml.Node from various OpenAPI types.
+// This is used for node-to-operation mapping during indexing.
+func getRootNodeFromAny(model any) *yaml.Node {
+ if model == nil {
+ return nil
+ }
+
+ // Try direct GetRootNode()
+ type rootNodeGetter interface {
+ GetRootNode() *yaml.Node
+ }
+
+ if getter, ok := model.(rootNodeGetter); ok {
+ return getter.GetRootNode()
+ }
+
+ // Try navigable node (for EitherValue wrappers)
+ type navigableNoder interface {
+ GetNavigableNode() (any, error)
+ }
+
+ if navigable, ok := model.(navigableNoder); ok {
+ inner, err := navigable.GetNavigableNode()
+ if err == nil && inner != nil {
+ // Recursively try to get root node from the inner value
+ return getRootNodeFromAny(inner)
+ }
+ }
+
+ // Try to get core model and extract root node from there
+ if core := getCoreModelFromAny(model); core != nil {
+ if getter, ok := core.(rootNodeGetter); ok {
+ return getter.GetRootNode()
}
}
diff --git a/openapi/security.go b/openapi/security.go
index 82d77151..eca14325 100644
--- a/openapi/security.go
+++ b/openapi/security.go
@@ -2,6 +2,7 @@ package openapi
import (
"context"
+ "errors"
"fmt"
"net/url"
"strings"
@@ -169,47 +170,59 @@ func (s *SecurityScheme) Validate(ctx context.Context, opts ...validation.Option
if core.Type.Present {
if s.Type == "" {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("securityScheme.type is required"), core, core.Type))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("`securityScheme.type` is required"), core, core.Type))
} else {
switch s.Type {
case SecuritySchemeTypeAPIKey:
if !core.Name.Present || *s.Name == "" {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("securityScheme.name is required for type=apiKey"), core, core.Name))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("`securityScheme.name` is required for type=apiKey"), core, core.Name))
}
if !core.In.Present || *s.In == "" {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("securityScheme.in is required for type=apiKey"), core, core.In))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("`securityScheme.in` is required for type=apiKey"), core, core.In))
} else {
switch *s.In {
case SecuritySchemeInHeader:
case SecuritySchemeInQuery:
case SecuritySchemeInCookie:
default:
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("securityScheme.in must be one of [%s] for type=apiKey", strings.Join([]string{string(SecuritySchemeInHeader), string(SecuritySchemeInQuery), string(SecuritySchemeInCookie)}, ", ")), core, core.In))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationAllowedValues, fmt.Errorf("securityScheme.in must be one of [`%s`] for type=apiKey", strings.Join([]string{string(SecuritySchemeInHeader), string(SecuritySchemeInQuery), string(SecuritySchemeInCookie)}, ", ")), core, core.In))
}
}
case SecuritySchemeTypeHTTP:
if !core.Scheme.Present || *s.Scheme == "" {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("securityScheme.scheme is required for type=http"), core, core.Scheme))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("`securityScheme.scheme` is required for type=http"), core, core.Scheme))
}
case SecuritySchemeTypeMutualTLS:
case SecuritySchemeTypeOAuth2:
if !core.Flows.Present || s.Flows == nil {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("securityScheme.flows is required for type=oauth2"), core, core.Flows))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("`securityScheme.flows` is required for type=oauth2"), core, core.Flows))
} else {
errs = append(errs, s.Flows.Validate(ctx, opts...)...)
}
// Validate oauth2MetadataUrl if present
if core.OAuth2MetadataUrl.Present && s.OAuth2MetadataUrl != nil && *s.OAuth2MetadataUrl != "" {
if _, err := url.Parse(*s.OAuth2MetadataUrl); err != nil {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("securityScheme.oauth2MetadataUrl is not a valid uri: %s", err), core, core.OAuth2MetadataUrl))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationInvalidFormat, fmt.Errorf("`securityScheme.oauth2MetadataUrl` is not a valid uri: %w", err), core, core.OAuth2MetadataUrl))
}
}
case SecuritySchemeTypeOpenIDConnect:
if !core.OpenIdConnectUrl.Present || *s.OpenIdConnectUrl == "" {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("securityScheme.openIdConnectUrl is required for type=openIdConnect"), core, core.OpenIdConnectUrl))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("`securityScheme.openIdConnectUrl` is required for type=openIdConnect"), core, core.OpenIdConnectUrl))
+ } else {
+ if _, err := url.Parse(*s.OpenIdConnectUrl); err != nil {
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationInvalidFormat, fmt.Errorf("`securityScheme.openIdConnectUrl` is not a valid uri: %w", err), core, core.OpenIdConnectUrl))
+ }
}
default:
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("securityScheme.type must be one of [%s]", strings.Join([]string{string(SecuritySchemeTypeAPIKey), string(SecuritySchemeTypeHTTP), string(SecuritySchemeTypeMutualTLS), string(SecuritySchemeTypeOAuth2), string(SecuritySchemeTypeOpenIDConnect)}, ", ")), core, core.Type))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationAllowedValues, fmt.Errorf("securityScheme.type must be one of [`%s`]", strings.Join([]string{string(SecuritySchemeTypeAPIKey), string(SecuritySchemeTypeHTTP), string(SecuritySchemeTypeMutualTLS), string(SecuritySchemeTypeOAuth2), string(SecuritySchemeTypeOpenIDConnect)}, ", ")), core, core.Type))
+ }
+ }
+
+ // Check for unused properties based on security scheme type
+ if s.Type != "" {
+ unusedFields := getUnusedFields(s.Type.String(), core)
+ for _, field := range unusedFields {
+ errs = append(errs, field.error)
}
}
}
@@ -219,6 +232,115 @@ func (s *SecurityScheme) Validate(ctx context.Context, opts ...validation.Option
return errs
}
+type unusedFieldError struct {
+ fieldName string
+ error error
+}
+
+func getUnusedFields(schemeType string, coreScheme *core.SecurityScheme) []unusedFieldError {
+ var unused []unusedFieldError
+
+ // Define which fields are invalid for each type
+ invalidFields := map[string]struct {
+ name bool
+ in bool
+ scheme bool
+ bearerFormat bool
+ flows bool
+ openIdConnectUrl bool
+ oauth2MetadataUrl bool
+ }{
+ string(SecuritySchemeTypeAPIKey): {
+ scheme: true,
+ bearerFormat: true,
+ flows: true,
+ openIdConnectUrl: true,
+ oauth2MetadataUrl: true,
+ },
+ string(SecuritySchemeTypeHTTP): {
+ name: true,
+ in: true,
+ flows: true,
+ openIdConnectUrl: true,
+ oauth2MetadataUrl: true,
+ },
+ string(SecuritySchemeTypeMutualTLS): {
+ name: true,
+ in: true,
+ scheme: true,
+ bearerFormat: true,
+ flows: true,
+ openIdConnectUrl: true,
+ oauth2MetadataUrl: true,
+ },
+ string(SecuritySchemeTypeOAuth2): {
+ name: true,
+ in: true,
+ scheme: true,
+ bearerFormat: true,
+ openIdConnectUrl: true,
+ },
+ string(SecuritySchemeTypeOpenIDConnect): {
+ name: true,
+ in: true,
+ scheme: true,
+ bearerFormat: true,
+ flows: true,
+ oauth2MetadataUrl: true,
+ },
+ }
+
+ invalid, exists := invalidFields[schemeType]
+ if !exists {
+ return unused
+ }
+
+ if invalid.name && coreScheme.Name.Present {
+ unused = append(unused, unusedFieldError{
+ fieldName: "name",
+ error: validation.NewValueError(validation.SeverityWarning, validation.RuleValidationAllowedValues, errors.New("securityScheme.name is not used for type="+schemeType+" (only valid for type=apiKey)"), coreScheme, coreScheme.Name),
+ })
+ }
+ if invalid.in && coreScheme.In.Present {
+ unused = append(unused, unusedFieldError{
+ fieldName: "in",
+ error: validation.NewValueError(validation.SeverityWarning, validation.RuleValidationAllowedValues, errors.New("securityScheme.in is not used for type="+schemeType+" (only valid for type=apiKey)"), coreScheme, coreScheme.In),
+ })
+ }
+ if invalid.scheme && coreScheme.Scheme.Present {
+ unused = append(unused, unusedFieldError{
+ fieldName: "scheme",
+ error: validation.NewValueError(validation.SeverityWarning, validation.RuleValidationAllowedValues, errors.New("securityScheme.scheme is not used for type="+schemeType+" (only valid for type=http)"), coreScheme, coreScheme.Scheme),
+ })
+ }
+ if invalid.bearerFormat && coreScheme.BearerFormat.Present {
+ unused = append(unused, unusedFieldError{
+ fieldName: "bearerFormat",
+ error: validation.NewValueError(validation.SeverityWarning, validation.RuleValidationAllowedValues, errors.New("securityScheme.bearerFormat is not used for type="+schemeType+" (only valid for type=http)"), coreScheme, coreScheme.BearerFormat),
+ })
+ }
+ if invalid.flows && coreScheme.Flows.Present {
+ unused = append(unused, unusedFieldError{
+ fieldName: "flows",
+ error: validation.NewValueError(validation.SeverityWarning, validation.RuleValidationAllowedValues, errors.New("securityScheme.flows is not used for type="+schemeType+" (only valid for type=oauth2)"), coreScheme, coreScheme.Flows),
+ })
+ }
+ if invalid.openIdConnectUrl && coreScheme.OpenIdConnectUrl.Present {
+ unused = append(unused, unusedFieldError{
+ fieldName: "openIdConnectUrl",
+ error: validation.NewValueError(validation.SeverityWarning, validation.RuleValidationAllowedValues, errors.New("securityScheme.openIdConnectUrl is not used for type="+schemeType+" (only valid for type=openIdConnect)"), coreScheme, coreScheme.OpenIdConnectUrl),
+ })
+ }
+ if invalid.oauth2MetadataUrl && coreScheme.OAuth2MetadataUrl.Present {
+ unused = append(unused, unusedFieldError{
+ fieldName: "oauth2MetadataUrl",
+ error: validation.NewValueError(validation.SeverityWarning, validation.RuleValidationAllowedValues, errors.New("securityScheme.oauth2MetadataUrl is not used for type="+schemeType+" (only valid for type=oauth2)"), coreScheme, coreScheme.OAuth2MetadataUrl),
+ })
+ }
+
+ return unused
+}
+
// SecurityRequirement represents a security requirement for an API or operation.
// Each name in the map represents a security scheme that can be used to secure the API or operation.
// If the security scheme is of type "oauth2" or "openIdConnect", then the value is a list of scope names required by the operation.
@@ -302,7 +424,7 @@ func (s *SecurityRequirement) Validate(ctx context.Context, opts ...validation.O
}
// Not found as component name and not a valid URI
- errs = append(errs, validation.NewMapKeyError(validation.NewValueValidationError("securityRequirement scheme %s is not defined in components.securitySchemes and is not a valid URI reference", securityScheme), core, core, securityScheme))
+ errs = append(errs, validation.NewMapKeyError(validation.SeverityError, validation.RuleValidationSchemeNotFound, fmt.Errorf("securityRequirement scheme %s is not defined in components.securitySchemes and is not a valid URI reference", securityScheme), core, core, securityScheme))
}
s.Valid = len(errs) == 0 && core.GetValid()
@@ -498,68 +620,68 @@ func (o *OAuthFlow) Validate(ctx context.Context, opts ...validation.Option) []e
switch *oAuthFlowType {
case OAuthFlowTypeImplicit:
if !core.AuthorizationURL.Present || *o.AuthorizationURL == "" {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("oAuthFlow.authorizationUrl is required for type=implicit"), core, core.AuthorizationURL))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("oAuthFlow.authorizationUrl is required for type=implicit"), core, core.AuthorizationURL))
} else {
if _, err := url.Parse(*o.AuthorizationURL); err != nil {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("oAuthFlow.authorizationUrl is not a valid uri: %s", err), core, core.AuthorizationURL))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationInvalidFormat, fmt.Errorf("oAuthFlow.authorizationUrl is not a valid uri: %w", err), core, core.AuthorizationURL))
}
}
case OAuthFlowTypePassword:
if !core.TokenURL.Present || *o.TokenURL == "" {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("oAuthFlow.tokenUrl is required for type=password"), core, core.TokenURL))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("oAuthFlow.tokenUrl is required for type=password"), core, core.TokenURL))
} else {
if _, err := url.Parse(*o.TokenURL); err != nil {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("oAuthFlow.tokenUrl is not a valid uri: %s", err), core, core.TokenURL))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationInvalidFormat, fmt.Errorf("oAuthFlow.tokenUrl is not a valid uri: %w", err), core, core.TokenURL))
}
}
case OAuthFlowTypeClientCredentials:
if !core.TokenURL.Present || *o.TokenURL == "" {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("oAuthFlow.tokenUrl is required for type=clientCredentials"), core, core.TokenURL))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("oAuthFlow.tokenUrl is required for type=clientCredentials"), core, core.TokenURL))
} else {
if _, err := url.Parse(*o.TokenURL); err != nil {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("oAuthFlow.tokenUrl is not a valid uri: %s", err), core, core.TokenURL))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationInvalidFormat, fmt.Errorf("oAuthFlow.tokenUrl is not a valid uri: %w", err), core, core.TokenURL))
}
}
case OAuthFlowTypeAuthorizationCode:
if !core.AuthorizationURL.Present || *o.AuthorizationURL == "" {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("oAuthFlow.authorizationUrl is required for type=authorizationCode"), core, core.AuthorizationURL))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("oAuthFlow.authorizationUrl is required for type=authorizationCode"), core, core.AuthorizationURL))
} else {
if _, err := url.Parse(*o.AuthorizationURL); err != nil {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("oAuthFlow.authorizationUrl is not a valid uri: %s", err), core, core.AuthorizationURL))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationInvalidFormat, fmt.Errorf("oAuthFlow.authorizationUrl is not a valid uri: %w", err), core, core.AuthorizationURL))
}
}
if !core.TokenURL.Present || *o.TokenURL == "" {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("oAuthFlow.tokenUrl is required for type=authorizationCode"), core, core.TokenURL))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("oAuthFlow.tokenUrl is required for type=authorizationCode"), core, core.TokenURL))
} else {
if _, err := url.Parse(*o.TokenURL); err != nil {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("oAuthFlow.tokenUrl is not a valid uri: %s", err), core, core.TokenURL))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationInvalidFormat, fmt.Errorf("oAuthFlow.tokenUrl is not a valid uri: %w", err), core, core.TokenURL))
}
}
case OAuthFlowTypeDeviceAuthorization:
if !core.DeviceAuthorizationURL.Present || *o.DeviceAuthorizationURL == "" {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("oAuthFlow.deviceAuthorizationUrl is required for type=deviceAuthorization"), core, core.DeviceAuthorizationURL))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("oAuthFlow.deviceAuthorizationUrl is required for type=deviceAuthorization"), core, core.DeviceAuthorizationURL))
} else {
if _, err := url.Parse(*o.DeviceAuthorizationURL); err != nil {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("oAuthFlow.deviceAuthorizationUrl is not a valid uri: %s", err), core, core.DeviceAuthorizationURL))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationInvalidFormat, fmt.Errorf("oAuthFlow.deviceAuthorizationUrl is not a valid uri: %w", err), core, core.DeviceAuthorizationURL))
}
}
if !core.TokenURL.Present || *o.TokenURL == "" {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("oAuthFlow.tokenUrl is required for type=deviceAuthorization"), core, core.TokenURL))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("oAuthFlow.tokenUrl is required for type=deviceAuthorization"), core, core.TokenURL))
} else {
if _, err := url.Parse(*o.TokenURL); err != nil {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("oAuthFlow.tokenUrl is not a valid uri: %s", err), core, core.TokenURL))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationInvalidFormat, fmt.Errorf("oAuthFlow.tokenUrl is not a valid uri: %w", err), core, core.TokenURL))
}
}
}
if core.RefreshURL.Present {
if _, err := url.Parse(*o.RefreshURL); err != nil {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("oAuthFlow.refreshUrl is not a valid uri: %s", err), core, core.RefreshURL))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationInvalidFormat, fmt.Errorf("oAuthFlow.refreshUrl is not a valid uri: %w", err), core, core.RefreshURL))
}
}
if !core.Scopes.Present {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("oAuthFlow.scopes is required (empty map is allowed)"), core, core.Scopes))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("oAuthFlow.scopes is required (empty map is allowed)"), core, core.Scopes))
}
o.Valid = len(errs) == 0 && core.GetValid()
diff --git a/openapi/security_validate_test.go b/openapi/security_validate_test.go
index 306ae1f6..ac82a99e 100644
--- a/openapi/security_validate_test.go
+++ b/openapi/security_validate_test.go
@@ -2,6 +2,7 @@ package openapi_test
import (
"bytes"
+ "errors"
"strings"
"testing"
@@ -160,7 +161,7 @@ func TestSecurityScheme_Validate_Error(t *testing.T) {
yml: `
description: Some security scheme
`,
- wantErrs: []string{"[2:1] securityScheme.type is missing"},
+ wantErrs: []string{"[2:1] error validation-required-field `securityScheme.type` is required"},
},
{
name: "invalid_type",
@@ -175,7 +176,7 @@ type: invalid
type: apiKey
in: header
`,
- wantErrs: []string{"name is required for type=apiKey"},
+ wantErrs: []string{"`securityScheme.name` is required for type=apiKey"},
},
{
name: "api_key_missing_in",
@@ -183,7 +184,7 @@ in: header
type: apiKey
name: X-API-Key
`,
- wantErrs: []string{"in is required for type=apiKey"},
+ wantErrs: []string{"`securityScheme.in` is required for type=apiKey"},
},
{
name: "api_key_invalid_in",
@@ -192,28 +193,28 @@ type: apiKey
name: X-API-Key
in: invalid
`,
- wantErrs: []string{"in must be one of"},
+ wantErrs: []string{"securityScheme.in must be one of"},
},
{
name: "http_missing_scheme",
yml: `
type: http
`,
- wantErrs: []string{"scheme is required for type=http"},
+ wantErrs: []string{"`securityScheme.scheme` is required for type=http"},
},
{
name: "oauth2_missing_flows",
yml: `
type: oauth2
`,
- wantErrs: []string{"flows is required for type=oauth2"},
+ wantErrs: []string{"`securityScheme.flows` is required for type=oauth2"},
},
{
name: "openid_missing_url",
yml: `
type: openIdConnect
`,
- wantErrs: []string{"openIdConnectUrl is required for type=openIdConnect"},
+ wantErrs: []string{"`securityScheme.openIdConnectUrl` is required for type=openIdConnect"},
},
{
name: "oauth2_invalid_metadata_url",
@@ -227,7 +228,27 @@ flows:
read: Read access
oauth2MetadataUrl: ://invalid-url
`,
- wantErrs: []string{"oauth2MetadataUrl is not a valid uri"},
+ wantErrs: []string{"`securityScheme.oauth2MetadataUrl` is not a valid uri"},
+ },
+ {
+ name: "oauth2_flow_invalid_authorization_url",
+ yml: `
+type: oauth2
+flows:
+ implicit:
+ authorizationUrl: http:// blah.
+ scopes:
+ read: Read access
+`,
+ wantErrs: []string{"oAuthFlow.authorizationUrl is not a valid uri"},
+ },
+ {
+ name: "openid_invalid_url",
+ yml: `
+type: openIdConnect
+openIdConnectUrl: http:// blah.
+`,
+ wantErrs: []string{"`securityScheme.openIdConnectUrl` is not a valid uri"},
},
}
@@ -263,6 +284,191 @@ oauth2MetadataUrl: ://invalid-url
}
}
+func TestSecurityScheme_Validate_UnusedProperties(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ yml string
+ wantWarnings []string
+ }{
+ {
+ name: "http_with_in_property",
+ yml: `
+type: http
+scheme: bearer
+in: header
+`,
+ wantWarnings: []string{"in is not used for type=http"},
+ },
+ {
+ name: "http_with_name_property",
+ yml: `
+type: http
+scheme: bearer
+name: X-API-Key
+`,
+ wantWarnings: []string{"name is not used for type=http"},
+ },
+ {
+ name: "http_with_flows_property",
+ yml: `
+type: http
+scheme: bearer
+flows:
+ implicit:
+ authorizationUrl: https://example.com/oauth/authorize
+ scopes: {}
+`,
+ wantWarnings: []string{"flows is not used for type=http"},
+ },
+ {
+ name: "apiKey_with_scheme_property",
+ yml: `
+type: apiKey
+name: X-API-Key
+in: header
+scheme: bearer
+`,
+ wantWarnings: []string{"scheme is not used for type=apiKey"},
+ },
+ {
+ name: "apiKey_with_bearerFormat_property",
+ yml: `
+type: apiKey
+name: X-API-Key
+in: header
+bearerFormat: JWT
+`,
+ wantWarnings: []string{"bearerFormat is not used for type=apiKey"},
+ },
+ {
+ name: "apiKey_with_flows_property",
+ yml: `
+type: apiKey
+name: X-API-Key
+in: header
+flows:
+ implicit:
+ authorizationUrl: https://example.com/oauth/authorize
+ scopes: {}
+`,
+ wantWarnings: []string{"flows is not used for type=apiKey"},
+ },
+ {
+ name: "mutualTLS_with_scheme_property",
+ yml: `
+type: mutualTLS
+scheme: bearer
+`,
+ wantWarnings: []string{"scheme is not used for type=mutualTLS"},
+ },
+ {
+ name: "mutualTLS_with_name_and_in_properties",
+ yml: `
+type: mutualTLS
+name: X-API-Key
+in: header
+`,
+ wantWarnings: []string{
+ "name is not used for type=mutualTLS",
+ "in is not used for type=mutualTLS",
+ },
+ },
+ {
+ name: "oauth2_with_scheme_property",
+ yml: `
+type: oauth2
+flows:
+ authorizationCode:
+ authorizationUrl: https://example.com/oauth/authorize
+ tokenUrl: https://example.com/oauth/token
+ scopes: {}
+scheme: bearer
+`,
+ wantWarnings: []string{"scheme is not used for type=oauth2"},
+ },
+ {
+ name: "oauth2_with_name_and_in_properties",
+ yml: `
+type: oauth2
+flows:
+ authorizationCode:
+ authorizationUrl: https://example.com/oauth/authorize
+ tokenUrl: https://example.com/oauth/token
+ scopes: {}
+name: X-API-Key
+in: header
+`,
+ wantWarnings: []string{
+ "name is not used for type=oauth2",
+ "in is not used for type=oauth2",
+ },
+ },
+ {
+ name: "openIdConnect_with_scheme_property",
+ yml: `
+type: openIdConnect
+openIdConnectUrl: https://example.com/.well-known/openid-configuration
+scheme: bearer
+`,
+ wantWarnings: []string{"scheme is not used for type=openIdConnect"},
+ },
+ {
+ name: "openIdConnect_with_flows_property",
+ yml: `
+type: openIdConnect
+openIdConnectUrl: https://example.com/.well-known/openid-configuration
+flows:
+ implicit:
+ authorizationUrl: https://example.com/oauth/authorize
+ scopes: {}
+`,
+ wantWarnings: []string{"flows is not used for type=openIdConnect"},
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+
+ var securityScheme openapi.SecurityScheme
+
+ validationErrs, err := marshaller.Unmarshal(t.Context(), bytes.NewBufferString(tt.yml), &securityScheme)
+ require.NoError(t, err)
+
+ errs := securityScheme.Validate(t.Context())
+
+ // Combine unmarshalling and validation errors
+ validationErrs = append(validationErrs, errs...)
+
+ // Extract warnings (severity = warning)
+ var warnings []error
+ for _, e := range validationErrs {
+ var verr *validation.Error
+ if errors.As(e, &verr) && verr.Severity == validation.SeverityWarning {
+ warnings = append(warnings, e)
+ }
+ }
+
+ require.NotEmpty(t, warnings, "Expected validation warnings")
+ require.Len(t, warnings, len(tt.wantWarnings), "Expected %d warnings, got %d: %v", len(tt.wantWarnings), len(warnings), warnings)
+
+ // Check that all expected warnings are present
+ for _, wantWarning := range tt.wantWarnings {
+ found := false
+ for _, gotWarning := range warnings {
+ if gotWarning != nil && strings.Contains(gotWarning.Error(), wantWarning) {
+ found = true
+ break
+ }
+ }
+ require.True(t, found, "Expected warning containing '%s' not found in: %v", wantWarning, warnings)
+ }
+ })
+ }
+}
+
func TestSecurityRequirement_Validate_Success(t *testing.T) {
t.Parallel()
diff --git a/openapi/server.go b/openapi/server.go
index 83789bd6..f71f644d 100644
--- a/openapi/server.go
+++ b/openapi/server.go
@@ -87,16 +87,23 @@ func (s *Server) Validate(ctx context.Context, opts ...validation.Option) []erro
if core.URL.Present {
switch {
case s.URL == "":
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("server.url is required"), core, core.URL))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("`server.url` is required"), core, core.URL))
case !strings.Contains(s.URL, "{"):
if _, err := url.Parse(s.URL); err != nil {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("server.url is not a valid uri: %s", err), core, core.URL))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationInvalidFormat, fmt.Errorf("`server.url` is not a valid uri: %w", err), core, core.URL))
}
default:
- if resolvedURL, err := resolveServerVariables(s.URL, s.Variables); err != nil {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("server.url is not a valid uri: %s", err), core, core.URL))
+ resolvedURL, resolveErrs := resolveServerVariables(s.URL, s.Variables)
+ if len(resolveErrs) > 0 {
+ for _, resolveErr := range resolveErrs {
+ err := resolveErr
+ if err == nil {
+ continue
+ }
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationInvalidSyntax, err, core, core.URL))
+ }
} else if _, err := url.Parse(resolvedURL); err != nil {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("server.url is not a valid uri: %s", err), core, core.URL))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationInvalidFormat, fmt.Errorf("`server.url` is not a valid uri: %w", err), core, core.URL))
}
}
}
@@ -157,12 +164,12 @@ func (v *ServerVariable) Validate(ctx context.Context, opts ...validation.Option
errs := []error{}
if core.Default.Present && v.Default == "" {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("serverVariable.default is required"), core, core.Default))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("`serverVariable.default` is required"), core, core.Default))
}
if core.Enum.Present {
if !slices.Contains(v.Enum, v.Default) {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("serverVariable.default must be one of [%s]", strings.Join(v.Enum, ", ")), core, core.Enum))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationAllowedValues, fmt.Errorf("serverVariable.default must be one of [`%s`]", strings.Join(v.Enum, ", ")), core, core.Default))
}
}
@@ -171,13 +178,15 @@ func (v *ServerVariable) Validate(ctx context.Context, opts ...validation.Option
return errs
}
-func resolveServerVariables(serverURL string, variables *sequencedmap.Map[string, *ServerVariable]) (string, error) {
+func resolveServerVariables(serverURL string, variables *sequencedmap.Map[string, *ServerVariable]) (string, []error) {
if variables.Len() == 0 {
- return "", errors.New("serverURL contains variables but no variables are defined")
+ return "", []error{errors.New("serverURL contains variables but no variables are defined")}
}
resolvedURL := serverURL
+ var resolveErrs []error
+
matches := variablePattern.FindAllStringSubmatch(serverURL, -1)
for _, match := range matches {
if len(match) < 2 {
@@ -189,15 +198,39 @@ func resolveServerVariables(serverURL string, variables *sequencedmap.Map[string
variable, exists := variables.Get(variableName)
if !exists {
- return "", fmt.Errorf("server variable '%s' is not defined", variableName)
+ err := fmt.Errorf("server variable `%s` is not defined%s", formatServerVariableName(variableName), doubleCurlyBraceHint(serverURL))
+ resolveErrs = append(resolveErrs, err)
+ continue
}
if variable.Default == "" {
- return "", fmt.Errorf("server variable '%s' has no default value", variableName)
+ err := fmt.Errorf("server variable `%s` has no default value", formatServerVariableName(variableName))
+ resolveErrs = append(resolveErrs, err)
+ continue
}
resolvedURL = strings.ReplaceAll(resolvedURL, placeholder, variable.Default)
}
+ if len(resolveErrs) > 0 {
+ return "", resolveErrs
+ }
+
return resolvedURL, nil
}
+
+func formatServerVariableName(variableName string) string {
+ if strings.HasPrefix(variableName, "{") {
+ return "{" + strings.TrimPrefix(variableName, "{") + "}"
+ }
+
+ return variableName
+}
+
+func doubleCurlyBraceHint(serverURL string) string {
+ if strings.Contains(serverURL, "{{") || strings.Contains(serverURL, "}}") {
+ return ". Use single curly braces for variable substitution"
+ }
+
+ return ""
+}
diff --git a/openapi/server_test.go b/openapi/server_test.go
index 2b927ce5..5d4eaa2a 100644
--- a/openapi/server_test.go
+++ b/openapi/server_test.go
@@ -1,6 +1,7 @@
package openapi
import (
+ "strings"
"testing"
"github.com/speakeasy-api/openapi/sequencedmap"
@@ -103,8 +104,8 @@ func Test_resolveServerVariables_Success(t *testing.T) {
t.Run(tt.name, func(t *testing.T) {
t.Parallel()
- result, err := resolveServerVariables(tt.args.serverURL, tt.args.variables)
- require.NoError(t, err)
+ result, errs := resolveServerVariables(tt.args.serverURL, tt.args.variables)
+ require.Empty(t, errs, "expected no errors")
assert.Equal(t, tt.expected, result)
})
}
@@ -118,9 +119,9 @@ func Test_resolveServerVariables_Error(t *testing.T) {
variables *sequencedmap.Map[string, *ServerVariable]
}
tests := []struct {
- name string
- args args
- expectedErr string
+ name string
+ args args
+ expectedErrs []string
}{
{
name: "no variables defined",
@@ -128,7 +129,7 @@ func Test_resolveServerVariables_Error(t *testing.T) {
serverURL: "https://{host}/api",
variables: sequencedmap.New[string, *ServerVariable](),
},
- expectedErr: "serverURL contains variables but no variables are defined",
+ expectedErrs: []string{"serverURL contains variables but no variables are defined"},
},
{
name: "undefined variable",
@@ -140,7 +141,7 @@ func Test_resolveServerVariables_Error(t *testing.T) {
return vars
}(),
},
- expectedErr: "server variable 'host' is not defined",
+ expectedErrs: []string{"server variable `host` is not defined"},
},
{
name: "variable with empty default",
@@ -152,7 +153,7 @@ func Test_resolveServerVariables_Error(t *testing.T) {
return vars
}(),
},
- expectedErr: "server variable 'host' has no default value",
+ expectedErrs: []string{"server variable `host` has no default value"},
},
{
name: "multiple variables with one undefined",
@@ -164,7 +165,7 @@ func Test_resolveServerVariables_Error(t *testing.T) {
return vars
}(),
},
- expectedErr: "server variable 'port' is not defined",
+ expectedErrs: []string{"server variable `port` is not defined"},
},
{
name: "multiple variables with one having empty default",
@@ -177,7 +178,7 @@ func Test_resolveServerVariables_Error(t *testing.T) {
return vars
}(),
},
- expectedErr: "server variable 'port' has no default value",
+ expectedErrs: []string{"server variable `port` has no default value"},
},
{
name: "malformed nested brackets creates invalid variable name",
@@ -189,7 +190,23 @@ func Test_resolveServerVariables_Error(t *testing.T) {
return vars
}(),
},
- expectedErr: "server variable 'incomplete/path/{host' is not defined",
+ expectedErrs: []string{"server variable `incomplete/path/{host` is not defined"},
+ },
+ {
+ name: "double curly braces produces multiple errors",
+ args: args{
+ serverURL: "https://{{host}}{{port}}/api",
+ variables: func() *sequencedmap.Map[string, *ServerVariable] {
+ vars := sequencedmap.New[string, *ServerVariable]()
+ vars.Set("host", &ServerVariable{Default: "api.example.com"})
+ vars.Set("port", &ServerVariable{Default: "8080"})
+ return vars
+ }(),
+ },
+ expectedErrs: []string{
+ "server variable `{host}` is not defined. Use single curly braces for variable substitution",
+ "server variable `{port}` is not defined. Use single curly braces for variable substitution",
+ },
},
}
@@ -197,10 +214,27 @@ func Test_resolveServerVariables_Error(t *testing.T) {
t.Run(tt.name, func(t *testing.T) {
t.Parallel()
- result, err := resolveServerVariables(tt.args.serverURL, tt.args.variables)
- require.Error(t, err)
+ result, errs := resolveServerVariables(tt.args.serverURL, tt.args.variables)
+ require.NotEmpty(t, errs, "expected errors")
assert.Empty(t, result)
- assert.Contains(t, err.Error(), tt.expectedErr)
+ for _, expectedErr := range tt.expectedErrs {
+ assertErrorContains(t, errs, expectedErr)
+ }
})
}
}
+
+func assertErrorContains(t *testing.T, errs []error, expected string) {
+ t.Helper()
+
+ for _, err := range errs {
+ if err == nil {
+ continue
+ }
+ if strings.Contains(err.Error(), expected) {
+ return
+ }
+ }
+
+ assert.Fail(t, "expected error not found", "expected %q in errors: %v", expected, errs)
+}
diff --git a/openapi/server_validate_test.go b/openapi/server_validate_test.go
index 6ed72673..27dcf557 100644
--- a/openapi/server_validate_test.go
+++ b/openapi/server_validate_test.go
@@ -109,7 +109,7 @@ func TestServer_Validate_Error(t *testing.T) {
yml: `
description: Server without URL
`,
- wantErrs: []string{"[2:1] server.url is missing"},
+ wantErrs: []string{"[2:1] error validation-required-field `server.url` is required"},
},
{
name: "empty URL",
@@ -117,7 +117,7 @@ description: Server without URL
url: ""
description: Server with empty URL
`,
- wantErrs: []string{"[2:6] server.url is required"},
+ wantErrs: []string{"[2:6] error validation-required-field `server.url` is required"},
},
{
name: "variable without default value",
@@ -127,7 +127,7 @@ variables:
environment:
description: Environment name
`,
- wantErrs: []string{"[5:5] serverVariable.default is missing"},
+ wantErrs: []string{"[5:5] error validation-required-field `serverVariable.default` is required"},
},
{
name: "variable with empty default",
@@ -138,7 +138,7 @@ variables:
default: ""
description: Environment name
`,
- wantErrs: []string{"[5:14] serverVariable.default is required"},
+ wantErrs: []string{"[5:14] error validation-required-field `serverVariable.default` is required"},
},
{
name: "variable with invalid enum value",
@@ -152,7 +152,7 @@ variables:
- development
description: Environment name
`,
- wantErrs: []string{"[7:7] serverVariable.default must be one of [staging, development]"},
+ wantErrs: []string{"[5:14] error validation-allowed-values serverVariable.default must be one of [`staging, development`]"},
},
{
name: "multiple validation errors",
@@ -164,8 +164,47 @@ variables:
description: Environment name
`,
wantErrs: []string{
- "[2:6] server.url is required",
- "[5:14] serverVariable.default is required",
+ "[2:6] error validation-required-field `server.url` is required",
+ "[5:14] error validation-required-field `serverVariable.default` is required",
+ },
+ },
+ {
+ name: "double curly braces variable",
+ yml: `
+url: http://{{hostname}}:8080
+variables:
+ hostname:
+ default: api
+`,
+ wantErrs: []string{
+ "error validation-invalid-syntax server variable `{hostname}` is not defined. Use single curly braces for variable substitution",
+ },
+ },
+ {
+ name: "double curly braces multiple variables",
+ yml: `
+url: http://{{hostname}}{{port}}
+variables:
+ hostname:
+ default: api
+ port:
+ default: "8080"
+`,
+ wantErrs: []string{
+ "error validation-invalid-syntax server variable `{hostname}` is not defined. Use single curly braces for variable substitution",
+ "error validation-invalid-syntax server variable `{port}` is not defined. Use single curly braces for variable substitution",
+ },
+ },
+ {
+ name: "missing variable with single braces",
+ yml: `
+url: http://{hostname}:8080
+variables:
+ port:
+ default: "8080"
+`,
+ wantErrs: []string{
+ "error validation-invalid-syntax server variable `hostname` is not defined",
},
},
}
@@ -280,7 +319,7 @@ func TestServerVariable_Validate_Error(t *testing.T) {
yml: `
description: Variable without default
`,
- wantErrs: []string{"[2:1] serverVariable.default is missing"},
+ wantErrs: []string{"[2:1] error validation-required-field `serverVariable.default` is required"},
},
{
name: "empty default",
@@ -288,7 +327,7 @@ description: Variable without default
default: ""
description: Variable with empty default
`,
- wantErrs: []string{"[2:10] serverVariable.default is required"},
+ wantErrs: []string{"[2:10] error validation-required-field `serverVariable.default` is required"},
},
{
name: "default not in enum",
@@ -299,7 +338,7 @@ enum:
- valid2
description: Variable with invalid default
`,
- wantErrs: []string{"[4:3] serverVariable.default must be one of [valid1, valid2]"},
+ wantErrs: []string{"[2:10] error validation-allowed-values serverVariable.default must be one of [`valid1, valid2`]"},
},
}
diff --git a/openapi/tag.go b/openapi/tag.go
index bba656f7..4c851abc 100644
--- a/openapi/tag.go
+++ b/openapi/tag.go
@@ -2,6 +2,8 @@ package openapi
import (
"context"
+ "errors"
+ "fmt"
"github.com/speakeasy-api/openapi/extensions"
"github.com/speakeasy-api/openapi/internal/interfaces"
@@ -96,7 +98,7 @@ func (t *Tag) Validate(ctx context.Context, opts ...validation.Option) []error {
errs := []error{}
if core.Name.Present && t.Name == "" {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("tag.name is required"), core, core.Name))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("`tag.name` is required"), core, core.Name))
}
if t.ExternalDocs != nil {
@@ -121,15 +123,15 @@ func (t *Tag) Validate(ctx context.Context, opts ...validation.Option) []error {
}
if !parentExists {
- errs = append(errs, validation.NewValueError(
- validation.NewMissingValueError("parent tag '%s' does not exist", *t.Parent),
+ errs = append(errs, validation.NewValueError(validation.SeverityWarning, validation.RuleValidationTagNotFound,
+ fmt.Errorf("parent tag `%s` does not exist", *t.Parent),
core, core.Parent))
}
// Check for circular references
if t.hasCircularParentReference(allTags, make(map[string]bool)) {
- errs = append(errs, validation.NewValueError(
- validation.NewValueValidationError("circular parent reference detected for tag '%s'", t.Name),
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationCircularReference,
+ fmt.Errorf("circular parent reference detected for tag `%s`", t.Name),
core, core.Parent))
}
}
diff --git a/openapi/tag_validate_test.go b/openapi/tag_validate_test.go
index 95a5a22d..a24e6319 100644
--- a/openapi/tag_validate_test.go
+++ b/openapi/tag_validate_test.go
@@ -117,7 +117,7 @@ func TestTag_Validate_Error(t *testing.T) {
yml: `
description: A tag without name
`,
- wantErrs: []string{"[2:1] tag.name is missing"},
+ wantErrs: []string{"[2:1] error validation-required-field `tag.name` is required"},
},
{
name: "empty name",
@@ -125,7 +125,7 @@ description: A tag without name
name: ""
description: A tag with empty name
`,
- wantErrs: []string{"[2:7] tag.name is required"},
+ wantErrs: []string{"[2:7] error validation-required-field `tag.name` is required"},
},
{
name: "invalid external docs URL",
@@ -134,7 +134,7 @@ name: test
externalDocs:
url: ":invalid"
`,
- wantErrs: []string{"[4:8] externalDocumentation.url is not a valid uri: parse \":invalid\": missing protocol scheme"},
+ wantErrs: []string{"[4:8] warning validation-invalid-format externalDocumentation.url is not a valid uri: parse \":invalid\": missing protocol scheme"},
},
{
name: "external docs without URL",
@@ -143,7 +143,7 @@ name: test
externalDocs:
description: Documentation without URL
`,
- wantErrs: []string{"[4:3] externalDocumentation.url is missing"},
+ wantErrs: []string{"[4:3] error validation-required-field `externalDocumentation.url` is required"},
},
{
name: "multiple validation errors",
@@ -153,8 +153,8 @@ externalDocs:
url: ":invalid"
`,
wantErrs: []string{
- "[2:7] tag.name is required",
- "[4:8] externalDocumentation.url is not a valid uri: parse \":invalid\": missing protocol scheme",
+ "[2:7] error validation-required-field `tag.name` is required",
+ "[4:8] warning validation-invalid-format externalDocumentation.url is not a valid uri: parse \":invalid\": missing protocol scheme",
},
},
}
@@ -247,7 +247,7 @@ func TestTag_ValidateWithTags_ParentNotFound_Error(t *testing.T) {
found := false
for _, err := range errs {
- if strings.Contains(err.Error(), "parent tag 'nonexistent' does not exist") {
+ if strings.Contains(err.Error(), "parent tag `nonexistent` does not exist") {
found = true
break
}
diff --git a/openapi/testdata/bundle/issue50/expected.yaml b/openapi/testdata/bundle/issue50/expected.yaml
index 1ed26581..e3dc9d51 100644
--- a/openapi/testdata/bundle/issue50/expected.yaml
+++ b/openapi/testdata/bundle/issue50/expected.yaml
@@ -28,7 +28,7 @@ paths:
"500":
$ref: "#/components/responses/internal-server-error"
parameters:
- - $ref: "#/components/parameters/X-Idempotency-Key"
+ - $ref: '#/components/parameters/X-Idempotency-Key'
components:
securitySchemes:
bearerAuth:
diff --git a/openapi/testdata/inline/bundled_counter_expected.yaml b/openapi/testdata/inline/bundled_counter_expected.yaml
index cf9b92a6..35a7c435 100644
--- a/openapi/testdata/inline/bundled_counter_expected.yaml
+++ b/openapi/testdata/inline/bundled_counter_expected.yaml
@@ -108,7 +108,7 @@ paths:
tags:
- posts
parameters:
- - $ref: "#/components/parameters/DestinationParam"
+ - $ref: '#/components/parameters/DestinationParam'
requestBody:
$ref: "#/components/requestBodies/CopyRequest"
responses:
@@ -300,8 +300,8 @@ paths:
tags: [external]
summary: Test external parameter with complex reference chain
parameters:
- - $ref: "#/components/parameters/ComplexFilterParam"
- - $ref: "#/components/parameters/PaginationParam"
+ - $ref: '#/components/parameters/ComplexFilterParam'
+ - $ref: '#/components/parameters/PaginationParam'
responses:
"200":
description: Filtered results
diff --git a/openapi/testdata/inline/bundled_expected.yaml b/openapi/testdata/inline/bundled_expected.yaml
index f5e76158..2824f374 100644
--- a/openapi/testdata/inline/bundled_expected.yaml
+++ b/openapi/testdata/inline/bundled_expected.yaml
@@ -108,7 +108,7 @@ paths:
tags:
- posts
parameters:
- - $ref: "#/components/parameters/DestinationParam"
+ - $ref: '#/components/parameters/DestinationParam'
requestBody:
$ref: "#/components/requestBodies/CopyRequest"
responses:
@@ -300,8 +300,8 @@ paths:
tags: [external]
summary: Test external parameter with complex reference chain
parameters:
- - $ref: "#/components/parameters/ComplexFilterParam"
- - $ref: "#/components/parameters/PaginationParam"
+ - $ref: '#/components/parameters/ComplexFilterParam'
+ - $ref: '#/components/parameters/PaginationParam'
responses:
"200":
description: Filtered results
diff --git a/openapi/testdata/multifile-basic/components.yaml b/openapi/testdata/multifile-basic/components.yaml
new file mode 100644
index 00000000..4983adb2
--- /dev/null
+++ b/openapi/testdata/multifile-basic/components.yaml
@@ -0,0 +1,78 @@
+components:
+ schemas:
+ TestObject:
+ type: object
+ properties:
+ id:
+ type: string
+ name:
+ type: string
+ required:
+ - id
+ ErrorObject:
+ type: object
+ properties:
+ error:
+ type: string
+ message:
+ type: string
+
+ responses:
+ TestResponse:
+ description: Successful response
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/TestObject"
+ headers:
+ X-Custom-Header:
+ $ref: "#/components/headers/CustomHeader"
+ links:
+ TestLink:
+ $ref: "#/components/links/TestLink"
+
+ ErrorResponse:
+ description: Error response
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/ErrorObject"
+
+ headers:
+ CustomHeader:
+ description: Custom header
+ schema:
+ type: string
+
+ links:
+ TestLink:
+ operationId: getTest
+ description: Link back to test operation
+
+ callbacks:
+ TestCallback:
+ "{$request.body#/callbackUrl}":
+ post:
+ operationId: callbackOperation
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/TestObject"
+ responses:
+ "200":
+ description: Callback acknowledged
+
+ pathItems:
+ TestWebhook:
+ post:
+ operationId: webhookOperation
+ summary: Webhook operation
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/TestObject"
+ responses:
+ "200":
+ $ref: "#/components/responses/TestResponse"
diff --git a/openapi/testdata/multifile-basic/openapi.yaml b/openapi/testdata/multifile-basic/openapi.yaml
new file mode 100644
index 00000000..bf0b8f14
--- /dev/null
+++ b/openapi/testdata/multifile-basic/openapi.yaml
@@ -0,0 +1,26 @@
+openapi: 3.1.0
+info:
+ title: Multi-file Reference Test
+ version: 1.0.0
+paths:
+ /test:
+ get:
+ operationId: getTest
+ summary: Test operation
+ responses:
+ "200":
+ $ref: "./components.yaml#/components/responses/TestResponse"
+ "400":
+ $ref: "./components.yaml#/components/responses/ErrorResponse"
+ callbacks:
+ testCallback:
+ $ref: "./components.yaml#/components/callbacks/TestCallback"
+webhooks:
+ testWebhook:
+ $ref: "./components.yaml#/components/pathItems/TestWebhook"
+components:
+ securitySchemes:
+ apiKey:
+ type: apiKey
+ in: header
+ name: X-API-Key
diff --git a/openapi/testdata/multifile-simple/components.yaml b/openapi/testdata/multifile-simple/components.yaml
new file mode 100644
index 00000000..bab37a73
--- /dev/null
+++ b/openapi/testdata/multifile-simple/components.yaml
@@ -0,0 +1,14 @@
+components:
+ schemas:
+ TestSchema:
+ type: object
+ properties:
+ id:
+ type: string
+ responses:
+ TestResponse:
+ description: Test response
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/TestSchema"
diff --git a/openapi/testdata/multifile-simple/openapi.yaml b/openapi/testdata/multifile-simple/openapi.yaml
new file mode 100644
index 00000000..cb089558
--- /dev/null
+++ b/openapi/testdata/multifile-simple/openapi.yaml
@@ -0,0 +1,10 @@
+openapi: 3.1.0
+info:
+ title: Simple Test
+ version: 1.0.0
+paths:
+ /test:
+ get:
+ responses:
+ "200":
+ $ref: "./components.yaml#/components/responses/TestResponse"
diff --git a/overlay/README.md b/overlay/README.md
index 44e70e4d..6a005f32 100644
--- a/overlay/README.md
+++ b/overlay/README.md
@@ -3,7 +3,7 @@
OpenAPI Overlay
- An implementation of the OpenAPI Overlay Specification 1.1.0 for applying modifications to OpenAPI documents
+
An implementation of the OpenAPI Overlay Specification for applying modifications to OpenAPI documents
@@ -25,19 +25,16 @@
## Features
-- **OpenAPI Overlay Specification Compliance**: Full implementation of the [OpenAPI Overlay Specification 1.0.0](https://github.com/OAI/Overlay-Specification/blob/main/versions/1.0.0.md) and [1.1.0](https://github.com/OAI/Overlay-Specification/blob/main/versions/1.1.0.md)
+- **OpenAPI Overlay Specification Compliance**: Full implementation of the [OpenAPI Overlay Specification](https://github.com/OAI/Overlay-Specification/blob/3f398c6/versions/1.0.0.md) (2023-10-12) and [version 1.1.0](https://github.com/OAI/Overlay-Specification/blob/e2c3cec/versions/1.1.0-dev.md)
- **JSONPath Target Selection**: Uses JSONPath expressions to select nodes for modification
-- **RFC 9535 JSONPath**: Version 1.1.0 uses RFC 9535-compliant JSONPath by default for improved interoperability
- **Remove, Update, and Copy Actions**: Support for remove actions (pruning nodes), update actions (merging values), and copy actions (duplicating or moving nodes)
-- **Upgrade Support**: Built-in `Upgrade()` function to upgrade overlay documents from 1.0.0 to 1.1.0
-- **Info Description Field**: Version 1.1.0 supports a `description` field in the overlay info section
- **Flexible Input/Output**: Works with both YAML and JSON formats
- **Batch Operations**: Apply multiple modifications to large numbers of nodes in a single operation
- **YAML v1.2 Support**: Uses [gopkg.in/yaml.v3](https://pkg.go.dev/gopkg.in/yaml.v3) for YAML v1.2 parsing (superset of JSON)
## About OpenAPI Overlays
-This specification defines a means of editing an OpenAPI Specification file by applying a list of actions. Each action is either a remove action that prunes nodes or an update that merges a value into nodes. The nodes impacted are selected by a target expression which uses JSONPath. This implementation supports [version 1.1.0](https://github.com/OAI/Overlay-Specification/blob/main/versions/1.1.0.md) which adds a `copy` action for duplicating or moving nodes within the document, RFC 9535 JSONPath as the default, and a description field in the info section.
+This specification defines a means of editing an OpenAPI Specification file by applying a list of actions. Each action is either a remove action that prunes nodes or an update that merges a value into nodes. The nodes impacted are selected by a target expression which uses JSONPath. This implementation also supports [version 1.1.0](https://github.com/OAI/Overlay-Specification/blob/e2c3cec/versions/1.1.0-dev.md) which adds a `copy` action for duplicating or moving nodes within the document.
The specification itself says very little about the input file to be modified or the output file. The presumed intention is that the input and output be an OpenAPI Specification, but that is not required.
diff --git a/overlay/validate.go b/overlay/validate.go
index af1f5d59..15221112 100644
--- a/overlay/validate.go
+++ b/overlay/validate.go
@@ -17,7 +17,7 @@ var (
// Errors
var (
ErrOverlayVersionInvalid = errors.New("overlay version is invalid")
- ErrOverlayVersionNotSupported = fmt.Errorf("overlay version must be one of: %s", strings.Join(sliceutil.Map(SupportedVersions, func(v *version.Version) string { return v.String() }), ", "))
+ ErrOverlayVersionNotSupported = fmt.Errorf("overlay version must be one of: `%s`", strings.Join(sliceutil.Map(SupportedVersions, func(v *version.Version) string { return v.String() }), ", "))
ErrOverlayVersionMustBeDefined = errors.New("overlay version must be defined")
ErrOverlayInfoTitleMustBeDefined = errors.New("overlay info title must be defined")
ErrOverlayInfoVersionMustBeDefined = errors.New("overlay info version must be defined")
diff --git a/overlay/validate_test.go b/overlay/validate_test.go
index c5d95a92..d68dc571 100644
--- a/overlay/validate_test.go
+++ b/overlay/validate_test.go
@@ -67,7 +67,7 @@ func TestOverlay_Validate(t *testing.T) {
},
},
},
- expectedErrors: []string{"overlay version must be one of: 1.0.0, 1.1.0"},
+ expectedErrors: []string{"overlay version must be one of: `1.0.0, 1.1.0`"},
},
{
name: "empty overlay version",
diff --git a/references/resolution.go b/references/resolution.go
index 3906fd10..c310840f 100644
--- a/references/resolution.go
+++ b/references/resolution.go
@@ -23,11 +23,15 @@ type ResolutionTarget interface {
GetCachedReferenceDocument(key string) ([]byte, bool)
StoreReferenceDocumentInCache(key string, doc []byte)
+
+ GetCachedExternalDocument(key string) (any, bool)
+ StoreExternalDocumentInCache(key string, doc any)
}
type Resolvable[T any] interface {
GetReference() Reference
Resolve(ctx context.Context, opts ResolveOptions) ([]error, error)
+ IsResolved() bool
GetResolvedObject() *T
}
@@ -53,8 +57,10 @@ type Unmarshal[T any] func(ctx context.Context, node *yaml.Node, skipValidation
type ResolveResult[T any] struct {
// Object is the resolved object
Object *T
+ // AbsoluteDocumentPath is the absolute reference that was resolved
+ AbsoluteDocumentPath string
// AbsoluteReference is the absolute reference that was resolved
- AbsoluteReference string
+ AbsoluteReference Reference
// ResolvedDocument is the document that was resolved against (for chaining resolutions)
ResolvedDocument any
}
@@ -103,10 +109,10 @@ func Resolve[T any](ctx context.Context, ref Reference, unmarshaler Unmarshal[T]
return nil, nil, err
}
- absRef := result.AbsoluteReference
+ absDocPath := result.AbsoluteReference
finalClassification := result.Classification
- absRefWithJP := utils.BuildAbsoluteReference(absRef, string(jp))
+ absRefWithJP := utils.BuildAbsoluteReference(absDocPath, string(jp))
// Try and get the object from the cache as we should avoid recreating it if possible
var obj *T
@@ -119,9 +125,10 @@ func Resolve[T any](ctx context.Context, ref Reference, unmarshaler Unmarshal[T]
if uri == "" {
if coOK {
return &ResolveResult[T]{
- Object: obj,
- AbsoluteReference: absRef,
- ResolvedDocument: opts.TargetDocument,
+ Object: obj,
+ AbsoluteDocumentPath: absDocPath,
+ AbsoluteReference: Reference(absRefWithJP),
+ ResolvedDocument: opts.TargetDocument,
}, nil, nil
}
@@ -134,41 +141,44 @@ func Resolve[T any](ctx context.Context, ref Reference, unmarshaler Unmarshal[T]
opts.RootDocument.StoreReferencedObjectInCache(absRefWithJP, obj)
return &ResolveResult[T]{
- Object: obj,
- AbsoluteReference: opts.TargetLocation,
- ResolvedDocument: opts.TargetDocument,
+ Object: obj,
+ AbsoluteDocumentPath: opts.TargetLocation,
+ AbsoluteReference: Reference(utils.BuildAbsoluteReference(opts.TargetLocation, string(jp))),
+ ResolvedDocument: opts.TargetDocument,
}, validationErrs, nil
} else if opts.DisableExternalRefs {
return nil, nil, errors.New("external reference not allowed")
}
- cd, cdOK := opts.RootDocument.GetCachedReferenceDocument(absRef)
+ cd, cdOK := opts.RootDocument.GetCachedReferenceDocument(absDocPath)
if coOK && cdOK {
return &ResolveResult[T]{
- Object: obj,
- AbsoluteReference: absRef,
- ResolvedDocument: cd,
+ Object: obj,
+ AbsoluteDocumentPath: absDocPath,
+ AbsoluteReference: Reference(absRefWithJP),
+ ResolvedDocument: cd,
}, nil, nil
}
// If we have a cached document, try and resolve against it
if cdOK {
- obj, resolvedDoc, validationErrs, err := resolveAgainstData(ctx, absRef, bytes.NewReader(cd), jp, unmarshaler, opts)
+ obj, resolvedDoc, validationErrs, err := resolveAgainstData(ctx, absDocPath, bytes.NewReader(cd), jp, unmarshaler, opts)
if err != nil {
return nil, validationErrs, err
}
return &ResolveResult[T]{
- Object: obj,
- AbsoluteReference: absRef,
- ResolvedDocument: resolvedDoc,
+ Object: obj,
+ AbsoluteDocumentPath: absDocPath,
+ AbsoluteReference: Reference(absRefWithJP),
+ ResolvedDocument: resolvedDoc,
}, validationErrs, nil
}
// Otherwise resolve the reference
switch finalClassification.Type {
case utils.ReferenceTypeURL:
- obj, resolvedDoc, validationErrs, err := resolveAgainstURL(ctx, absRef, jp, unmarshaler, opts)
+ obj, resolvedDoc, validationErrs, err := resolveAgainstURL(ctx, absDocPath, jp, unmarshaler, opts)
if err != nil {
return nil, validationErrs, err
}
@@ -177,12 +187,13 @@ func Resolve[T any](ctx context.Context, ref Reference, unmarshaler Unmarshal[T]
opts.RootDocument.StoreReferencedObjectInCache(absRefWithJP, obj)
return &ResolveResult[T]{
- Object: obj,
- AbsoluteReference: absRef,
- ResolvedDocument: resolvedDoc,
+ Object: obj,
+ AbsoluteDocumentPath: absDocPath,
+ AbsoluteReference: Reference(absRefWithJP),
+ ResolvedDocument: resolvedDoc,
}, validationErrs, nil
case utils.ReferenceTypeFilePath:
- obj, resolvedDoc, validationErrs, err := resolveAgainstFilePath(ctx, absRef, jp, unmarshaler, opts)
+ obj, resolvedDoc, validationErrs, err := resolveAgainstFilePath(ctx, absDocPath, jp, unmarshaler, opts)
if err != nil {
return nil, validationErrs, err
}
@@ -191,9 +202,10 @@ func Resolve[T any](ctx context.Context, ref Reference, unmarshaler Unmarshal[T]
opts.RootDocument.StoreReferencedObjectInCache(absRefWithJP, obj)
return &ResolveResult[T]{
- Object: obj,
- AbsoluteReference: absRef,
- ResolvedDocument: resolvedDoc,
+ Object: obj,
+ AbsoluteDocumentPath: absDocPath,
+ AbsoluteReference: Reference(absRefWithJP),
+ ResolvedDocument: resolvedDoc,
}, validationErrs, nil
default:
return nil, nil, fmt.Errorf("unsupported reference type: %d", finalClassification.Type)
@@ -257,19 +269,35 @@ func resolveAgainstData[T any](ctx context.Context, absRef string, reader io.Rea
return nil, nil, nil, err
}
- var node yaml.Node
- if err := yaml.Unmarshal(data, &node); err != nil {
- return nil, nil, nil, err
+ opts.RootDocument.InitCache()
+
+ // Check if we have a cached parsed YAML node for this external document
+ var node *yaml.Node
+ if cachedDoc, ok := opts.RootDocument.GetCachedExternalDocument(absRef); ok {
+ if cachedNode, ok := cachedDoc.(*yaml.Node); ok {
+ node = cachedNode
+ }
+ }
+
+ // If not cached, parse and cache the YAML node
+ if node == nil {
+ var parsedNode yaml.Node
+ if err := yaml.Unmarshal(data, &parsedNode); err != nil {
+ return nil, nil, nil, err
+ }
+ node = &parsedNode
+ // Cache the parsed YAML node so internal references can navigate it
+ opts.RootDocument.StoreExternalDocumentInCache(absRef, node)
}
var target any
// Handle empty JSON pointer case - if jp is empty, target the root node directly
if jp == "" {
- target = &node
+ target = node
} else {
var jpErr error
- target, jpErr = jsonpointer.GetTarget(node, jp)
+ target, jpErr = jsonpointer.GetTarget(*node, jp)
if jpErr != nil {
return nil, nil, nil, jpErr
}
@@ -284,6 +312,12 @@ func resolveAgainstData[T any](ctx context.Context, absRef string, reader io.Rea
return nil, nil, nil, fmt.Errorf("expected *yaml.Node, got %T", target)
}
+ // CRITICAL FIX: Update the TargetDocument to be the parsed YAML node
+ // This allows internal references (like #/components/schemas/...) within
+ // the resolved component to navigate through the external file's structure
+ resolveOptsWithDocument := opts
+ resolveOptsWithDocument.TargetDocument = node
+
resolved, validationErrs, err := unmarshaler(ctx, targetNode, opts.SkipValidation)
if err != nil {
return nil, nil, validationErrs, err
@@ -293,10 +327,9 @@ func resolveAgainstData[T any](ctx context.Context, absRef string, reader io.Rea
return nil, nil, validationErrs, fmt.Errorf("nil %T returned from unmarshaler", target)
}
- opts.RootDocument.InitCache()
opts.RootDocument.StoreReferenceDocumentInCache(absRef, data)
- return resolved, &node, validationErrs, nil
+ return resolved, node, validationErrs, nil
}
func cast[T any](target any) (*T, error) {
diff --git a/references/resolution_test.go b/references/resolution_test.go
index ea4a27be..afa8bd48 100644
--- a/references/resolution_test.go
+++ b/references/resolution_test.go
@@ -21,14 +21,16 @@ import (
// MockResolutionTarget implements ResolutionTarget for testing
type MockResolutionTarget struct {
- objCache map[string]any
- docCache map[string][]byte
+ objCache map[string]any
+ docCache map[string][]byte
+ extDocCache map[string]any
}
func NewMockResolutionTarget() *MockResolutionTarget {
return &MockResolutionTarget{
- objCache: make(map[string]any),
- docCache: make(map[string][]byte),
+ objCache: make(map[string]any),
+ docCache: make(map[string][]byte),
+ extDocCache: make(map[string]any),
}
}
@@ -57,6 +59,18 @@ func (m *MockResolutionTarget) InitCache() {
if m.docCache == nil {
m.docCache = make(map[string][]byte)
}
+ if m.extDocCache == nil {
+ m.extDocCache = make(map[string]any)
+ }
+}
+
+func (m *MockResolutionTarget) GetCachedExternalDocument(key string) (any, bool) {
+ data, exists := m.extDocCache[key]
+ return data, exists
+}
+
+func (m *MockResolutionTarget) StoreExternalDocumentInCache(key string, doc any) {
+ m.extDocCache[key] = doc
}
// MockVirtualFS implements system.VirtualFS for testing
@@ -392,7 +406,7 @@ func TestResolve_Errors(t *testing.T) {
require.NoError(t, err)
assert.Nil(t, validationErrs)
require.NotNil(t, result)
- assert.Equal(t, ".", result.AbsoluteReference)
+ assert.Equal(t, ".", result.AbsoluteDocumentPath)
})
t.Run("missing root document", func(t *testing.T) {
@@ -788,15 +802,15 @@ func TestResolve_AbsoluteVsRelativeReferenceHandling(t *testing.T) {
require.NotNil(t, result.Object)
// Verify the absolute reference is what we expect
- assert.Equal(t, tt.expectedAbsoluteRef, result.AbsoluteReference, tt.description)
+ assert.Equal(t, tt.expectedAbsoluteRef, result.AbsoluteDocumentPath, tt.description)
// Verify the behavior matches our expectation about absolute vs relative
if tt.isAbsolute {
// For absolute references, the result should be exactly the same as the original URI
- assert.Equal(t, tt.referenceURI, result.AbsoluteReference, "Absolute reference should remain unchanged")
+ assert.Equal(t, tt.referenceURI, result.AbsoluteDocumentPath, "Absolute reference should remain unchanged")
} else {
// For relative references, the result should be different from the original URI
- assert.NotEqual(t, tt.referenceURI, result.AbsoluteReference, "Relative reference should be resolved")
+ assert.NotEqual(t, tt.referenceURI, result.AbsoluteDocumentPath, "Relative reference should be resolved")
}
})
}
@@ -838,7 +852,7 @@ func TestResolve_RootDocumentDifferentFromTargetDocument(t *testing.T) {
assert.Nil(t, validationErrs)
require.NotNil(t, result)
require.NotNil(t, result.Object)
- assert.Equal(t, "/project/api/schemas/user.yaml", result.AbsoluteReference)
+ assert.Equal(t, "/project/api/schemas/user.yaml", result.AbsoluteDocumentPath)
// Verify the cache was stored in the ROOT document, not the target document
cachedData, exists := rootDoc.GetCachedReferenceDocument("/project/api/schemas/user.yaml")
@@ -878,7 +892,7 @@ func TestResolve_RootDocumentDifferentFromTargetDocument(t *testing.T) {
assert.Nil(t, validationErrs)
require.NotNil(t, result)
require.NotNil(t, result.Object)
- assert.Equal(t, "https://external.com/schemas/common.yaml", result.AbsoluteReference)
+ assert.Equal(t, "https://external.com/schemas/common.yaml", result.AbsoluteDocumentPath)
// Verify the cache was stored in the ROOT document, not the target document
cachedData, exists := rootDoc.GetCachedReferenceDocument("https://external.com/schemas/common.yaml")
@@ -920,7 +934,7 @@ func TestResolve_RootDocumentDifferentFromTargetDocument(t *testing.T) {
assert.Nil(t, validationErrs)
require.NotNil(t, result)
require.NotNil(t, result.Object)
- assert.Equal(t, "/project/api/schemas/cached.yaml", result.AbsoluteReference)
+ assert.Equal(t, "/project/api/schemas/cached.yaml", result.AbsoluteDocumentPath)
// Verify the cache from root document was used (not the file system)
retrievedCache, exists := rootDoc.GetCachedReferenceDocument("/project/api/schemas/cached.yaml")
@@ -953,7 +967,7 @@ func TestResolve_RootDocumentDifferentFromTargetDocument(t *testing.T) {
require.NotNil(t, result)
require.NotNil(t, result.Object)
assert.Equal(t, "nested-string", result.Object.StringField)
- assert.Equal(t, "/project/external.yaml", result.AbsoluteReference)
+ assert.Equal(t, "/project/external.yaml", result.AbsoluteDocumentPath)
// Verify that the resolved document is the target document
assert.Equal(t, targetDoc, result.ResolvedDocument)
diff --git a/swagger/core/reference.go b/swagger/core/reference.go
index d95f5fbe..32efa31b 100644
--- a/swagger/core/reference.go
+++ b/swagger/core/reference.go
@@ -31,7 +31,7 @@ func (r *Reference[T]) Unmarshal(ctx context.Context, parentName string, node *y
if resolvedNode.Kind != yaml.MappingNode {
r.SetValid(false, false)
- return []error{validation.NewValidationError(validation.NewTypeMismatchError(parentName, "reference expected object, got %s", yml.NodeKindToString(resolvedNode.Kind)), resolvedNode)}, nil
+ return []error{validation.NewValidationError(validation.SeverityError, validation.RuleValidationTypeMismatch, validation.NewTypeMismatchError(parentName, "reference expected `object`, got %s", yml.NodeKindToString(resolvedNode.Kind)), resolvedNode)}, nil
}
if _, _, ok := yml.GetMapElementNodes(ctx, resolvedNode, "$ref"); ok {
diff --git a/swagger/externaldocs.go b/swagger/externaldocs.go
index c85c8be4..e6ab8745 100644
--- a/swagger/externaldocs.go
+++ b/swagger/externaldocs.go
@@ -2,6 +2,8 @@ package swagger
import (
"context"
+ "errors"
+ "fmt"
"net/url"
"github.com/speakeasy-api/openapi/extensions"
@@ -55,12 +57,12 @@ func (e *ExternalDocumentation) Validate(ctx context.Context, opts ...validation
errs := []error{}
if c.URL.Present && e.URL == "" {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("externalDocs.url is required"), c, c.URL))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("`externalDocs.url` is required"), c, c.URL))
}
if c.URL.Present {
if _, err := url.Parse(e.URL); err != nil {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("externalDocs.url is not a valid uri: %s", err), c, c.URL))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationInvalidFormat, fmt.Errorf("externalDocs.url is not a valid uri: %w", err), c, c.URL))
}
}
diff --git a/swagger/info.go b/swagger/info.go
index 80b864ef..8b3913cc 100644
--- a/swagger/info.go
+++ b/swagger/info.go
@@ -2,6 +2,8 @@ package swagger
import (
"context"
+ "errors"
+ "fmt"
"net/mail"
"net/url"
@@ -96,16 +98,16 @@ func (i *Info) Validate(ctx context.Context, opts ...validation.Option) []error
errs := []error{}
if c.Title.Present && i.Title == "" {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("info.title is required"), c, c.Title))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("`info.title` is required"), c, c.Title))
}
if c.Version.Present && i.Version == "" {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("info.version is required"), c, c.Version))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("`info.version` is required"), c, c.Version))
}
if c.TermsOfService.Present {
if _, err := url.Parse(*i.TermsOfService); err != nil {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("info.termsOfService is not a valid uri: %s", err), c, c.TermsOfService))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationInvalidFormat, fmt.Errorf("info.termsOfService is not a valid uri: %w", err), c, c.TermsOfService))
}
}
@@ -177,13 +179,13 @@ func (c *Contact) Validate(ctx context.Context, opts ...validation.Option) []err
if core.URL.Present {
if _, err := url.Parse(*c.URL); err != nil {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("contact.url is not a valid uri: %s", err), core, core.URL))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationInvalidFormat, fmt.Errorf("contact.url is not a valid uri: %w", err), core, core.URL))
}
}
if core.Email.Present {
if _, err := mail.ParseAddress(*c.Email); err != nil {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("contact.email is not a valid email address: %s", err), core, core.Email))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationInvalidFormat, fmt.Errorf("contact.email is not a valid email address: %w", err), core, core.Email))
}
}
@@ -236,12 +238,12 @@ func (l *License) Validate(ctx context.Context, opts ...validation.Option) []err
errs := []error{}
if core.Name.Present && l.Name == "" {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("license.name is required"), core, core.Name))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("`license.name` is required"), core, core.Name))
}
if core.URL.Present {
if _, err := url.Parse(*l.URL); err != nil {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("license.url is not a valid uri: %s", err), core, core.URL))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationInvalidFormat, fmt.Errorf("license.url is not a valid uri: %w", err), core, core.URL))
}
}
diff --git a/swagger/info_validate_test.go b/swagger/info_validate_test.go
index f12c20fe..71c42b00 100644
--- a/swagger/info_validate_test.go
+++ b/swagger/info_validate_test.go
@@ -65,12 +65,12 @@ func TestInfo_Validate_Error(t *testing.T) {
{
name: "missing_title",
yml: `version: 1.0.0`,
- wantErrs: []string{"info.title is missing"},
+ wantErrs: []string{"`info.title` is required"},
},
{
name: "missing_version",
yml: `title: Test API`,
- wantErrs: []string{"info.version is missing"},
+ wantErrs: []string{"`info.version` is required"},
},
{
name: "invalid_contact_email",
@@ -86,7 +86,7 @@ contact:
version: 1.0.0
license:
url: https://example.com/license`,
- wantErrs: []string{"license.name is missing"},
+ wantErrs: []string{"`license.name` is required"},
},
}
@@ -249,7 +249,7 @@ func TestLicense_Validate_Error(t *testing.T) {
{
name: "missing_name",
yml: `url: https://example.com/license`,
- wantErrs: []string{"license.name is missing"},
+ wantErrs: []string{"`license.name` is required"},
},
}
diff --git a/swagger/operation.go b/swagger/operation.go
index 90cb167b..22719261 100644
--- a/swagger/operation.go
+++ b/swagger/operation.go
@@ -2,6 +2,8 @@ package swagger
import (
"context"
+ "errors"
+ "fmt"
"mime"
"github.com/speakeasy-api/openapi/extensions"
@@ -155,7 +157,7 @@ func (o *Operation) Validate(ctx context.Context, opts ...validation.Option) []e
errs := []error{}
if !c.Responses.Present {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("operation.responses is required"), c, c.Responses))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("`operation.responses` is required"), c, c.Responses))
} else if o.Responses != nil {
errs = append(errs, o.Responses.Validate(ctx, opts...)...)
}
@@ -173,7 +175,9 @@ func (o *Operation) Validate(ctx context.Context, opts ...validation.Option) []e
}
if !valid {
errs = append(errs, validation.NewValueError(
- validation.NewValueValidationError("operation.scheme must be one of [http, https, ws, wss], got '%s'", scheme),
+ validation.SeverityError,
+ validation.RuleValidationAllowedValues,
+ fmt.Errorf("operation.scheme must be one of [http, https, ws, wss], got `%s`", scheme),
c, c.Schemes))
}
}
@@ -184,7 +188,9 @@ func (o *Operation) Validate(ctx context.Context, opts ...validation.Option) []e
for _, mimeType := range o.Consumes {
if _, _, err := mime.ParseMediaType(mimeType); err != nil {
errs = append(errs, validation.NewValueError(
- validation.NewValueValidationError("operation.consumes contains invalid MIME type '%s': %s", mimeType, err),
+ validation.SeverityError,
+ validation.RuleValidationInvalidFormat,
+ fmt.Errorf("operation.consumes contains invalid MIME type `%s`: %w", mimeType, err),
c, c.Consumes))
}
}
@@ -195,7 +201,9 @@ func (o *Operation) Validate(ctx context.Context, opts ...validation.Option) []e
for _, mimeType := range o.Produces {
if _, _, err := mime.ParseMediaType(mimeType); err != nil {
errs = append(errs, validation.NewValueError(
- validation.NewValueValidationError("operation.produces contains invalid MIME type '%s': %s", mimeType, err),
+ validation.SeverityError,
+ validation.RuleValidationInvalidFormat,
+ fmt.Errorf("operation.produces contains invalid MIME type `%s`: %w", mimeType, err),
c, c.Produces))
}
}
diff --git a/swagger/operation_validate_test.go b/swagger/operation_validate_test.go
index 899b1eca..1242af13 100644
--- a/swagger/operation_validate_test.go
+++ b/swagger/operation_validate_test.go
@@ -81,7 +81,7 @@ func TestOperation_Validate_Error(t *testing.T) {
{
name: "missing_responses",
yml: `summary: Test operation`,
- wantErrs: []string{"operation.responses is required"},
+ wantErrs: []string{"`operation.responses` is required"},
},
}
diff --git a/swagger/parameter.go b/swagger/parameter.go
index 0dc46007..8f9bd7f7 100644
--- a/swagger/parameter.go
+++ b/swagger/parameter.go
@@ -2,6 +2,8 @@ package swagger
import (
"context"
+ "errors"
+ "fmt"
"strings"
"github.com/speakeasy-api/openapi/extensions"
@@ -168,11 +170,11 @@ func (p *Parameter) Validate(ctx context.Context, opts ...validation.Option) []e
errs := []error{}
if c.Name.Present && p.Name == "" {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("parameter.name is required"), c, c.Name))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("`parameter.name` is required"), c, c.Name))
}
if c.In.Present && p.In == "" {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("parameter.in is required"), c, c.In))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("parameter.in is required"), c, c.In))
} else if c.In.Present {
errs = append(errs, p.validateIn(c)...)
errs = append(errs, p.validateParameterType(ctx, c, opts...)...)
@@ -180,7 +182,7 @@ func (p *Parameter) Validate(ctx context.Context, opts ...validation.Option) []e
// allowEmptyValue only valid for query or formData
if c.AllowEmptyValue.Present && p.In != ParameterInQuery && p.In != ParameterInFormData {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("parameter.allowEmptyValue is only valid for in=query or in=formData"), c, c.AllowEmptyValue))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationAllowedValues, errors.New("parameter.allowEmptyValue is only valid for in=query or in=formData"), c, c.AllowEmptyValue))
}
// Validate items if present
@@ -195,7 +197,9 @@ func (p *Parameter) Validate(ctx context.Context, opts ...validation.Option) []e
opCore := operation.GetCore()
if !opCore.Consumes.Present || len(operation.Consumes) == 0 {
errs = append(errs, validation.NewValueError(
- validation.NewValueValidationError("parameter with type=file requires operation to have consumes defined"),
+ validation.SeverityError,
+ validation.RuleValidationRequiredField,
+ errors.New("parameter with type=file requires operation to have consumes defined"),
c, c.Type))
} else {
hasValidConsumes := false
@@ -207,7 +211,9 @@ func (p *Parameter) Validate(ctx context.Context, opts ...validation.Option) []e
}
if !hasValidConsumes {
errs = append(errs, validation.NewValueError(
- validation.NewValueValidationError("parameter with type=file requires operation consumes to be 'multipart/form-data' or 'application/x-www-form-urlencoded'"),
+ validation.SeverityError,
+ validation.RuleValidationAllowedValues,
+ errors.New("parameter with type=file requires operation consumes to be 'multipart/form-data' or 'application/x-www-form-urlencoded'"),
c, c.Type))
}
}
@@ -231,7 +237,7 @@ func (p *Parameter) validateIn(c *core.Parameter) []error {
}
}
if !valid {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("parameter.in must be one of [%s]", strings.Join([]string{string(ParameterInQuery), string(ParameterInHeader), string(ParameterInPath), string(ParameterInFormData), string(ParameterInBody)}, ", ")), c, c.In))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationAllowedValues, fmt.Errorf("parameter.in must be one of [`%s`]", strings.Join([]string{string(ParameterInQuery), string(ParameterInHeader), string(ParameterInPath), string(ParameterInFormData), string(ParameterInBody)}, ", ")), c, c.In))
}
return errs
@@ -242,13 +248,13 @@ func (p *Parameter) validateParameterType(ctx context.Context, c *core.Parameter
// Path parameters must be required
if p.In == ParameterInPath && (!c.Required.Present || !p.GetRequired()) {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("parameter.in=path requires required=true"), c, c.Required))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("parameter.in=path requires required=true"), c, c.Required))
}
// Body parameters require schema
if p.In == ParameterInBody {
if !c.Schema.Present {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("parameter.schema is required for in=body"), c, c.Schema))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("parameter.schema is required for in=body"), c, c.Schema))
return errs
}
errs = append(errs, p.Schema.Validate(ctx, opts...)...)
@@ -257,12 +263,12 @@ func (p *Parameter) validateParameterType(ctx context.Context, c *core.Parameter
// Non-body parameters require type
if !c.Type.Present {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("parameter.type is required for non-body parameters"), c, c.Type))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("parameter.type is required for non-body parameters"), c, c.Type))
return errs
}
if c.Type.Present && (p.Type == nil || *p.Type == "") {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("parameter.type is required for non-body parameters"), c, c.Type))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("parameter.type is required for non-body parameters"), c, c.Type))
return errs
}
@@ -276,24 +282,26 @@ func (p *Parameter) validateParameterType(ctx context.Context, c *core.Parameter
}
}
if !valid {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("parameter.type must be one of [%s]", strings.Join(validTypes, ", ")), c, c.Type))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationAllowedValues, fmt.Errorf("parameter.type must be one of [`%s`]", strings.Join(validTypes, ", ")), c, c.Type))
}
// File type only allowed for formData
if *p.Type == "file" && p.In != ParameterInFormData {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("parameter.type=file requires in=formData"), c, c.Type))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationAllowedValues, errors.New("parameter.type=file requires in=formData"), c, c.Type))
}
// Array type requires items
if *p.Type == "array" && !c.Items.Present {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("parameter.items is required when type=array"), c, c.Items))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("parameter.items is required when type=array"), c, c.Items))
}
// Validate collectionFormat=multi only for query or formData
if p.CollectionFormat != nil && *p.CollectionFormat == CollectionFormatMulti {
if p.In != ParameterInQuery && p.In != ParameterInFormData {
errs = append(errs, validation.NewValueError(
- validation.NewValueValidationError("collectionFormat='multi' is only valid for in=query or in=formData"),
+ validation.SeverityError,
+ validation.RuleValidationAllowedValues,
+ errors.New("collectionFormat='multi' is only valid for in=query or in=formData"),
c, c.CollectionFormat))
}
}
@@ -369,7 +377,7 @@ func (i *Items) Validate(ctx context.Context, opts ...validation.Option) []error
errs := []error{}
if c.Type.Present && i.Type == "" {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("items.type is required"), c, c.Type))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("`items.type` is required"), c, c.Type))
} else if c.Type.Present {
validTypes := []string{"string", "number", "integer", "boolean", "array"}
valid := false
@@ -380,12 +388,12 @@ func (i *Items) Validate(ctx context.Context, opts ...validation.Option) []error
}
}
if !valid {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("items.type must be one of [%s]", strings.Join(validTypes, ", ")), c, c.Type))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationAllowedValues, fmt.Errorf("items.type must be one of [`%s`]", strings.Join(validTypes, ", ")), c, c.Type))
}
// Array type requires items
if i.Type == "array" && !c.Items.Present {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("items.items is required when type=array"), c, c.Items))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("items.items is required when type=array"), c, c.Items))
}
}
diff --git a/swagger/parameter_test.go b/swagger/parameter_test.go
index ef50b238..4a619cd4 100644
--- a/swagger/parameter_test.go
+++ b/swagger/parameter_test.go
@@ -172,7 +172,7 @@ func TestParameter_Validate_Error(t *testing.T) {
in: query
type: string
`,
- wantErrs: []string{"parameter.name is missing"},
+ wantErrs: []string{"`parameter.name` is required"},
},
{
name: "empty name",
@@ -181,7 +181,7 @@ name: ""
in: query
type: string
`,
- wantErrs: []string{"parameter.name is required"},
+ wantErrs: []string{"`parameter.name` is required"},
},
{
name: "missing in",
@@ -189,7 +189,7 @@ type: string
name: test
type: string
`,
- wantErrs: []string{"parameter.in is missing"},
+ wantErrs: []string{"`parameter.in` is required"},
},
{
name: "path parameter not required",
@@ -270,7 +270,7 @@ in: path
required: false
`,
wantErrs: []string{
- "parameter.name is required",
+ "`parameter.name` is required",
"parameter.in=path requires required=true",
},
},
@@ -372,7 +372,7 @@ func TestItems_Validate_Error(t *testing.T) {
yml: `
format: int32
`,
- wantErrs: []string{"items.type is missing"},
+ wantErrs: []string{"`items.type` is required"},
},
{
name: "array items without nested items",
diff --git a/swagger/paths.go b/swagger/paths.go
index 47e10166..63629b86 100644
--- a/swagger/paths.go
+++ b/swagger/paths.go
@@ -2,6 +2,7 @@ package swagger
import (
"context"
+ "fmt"
"strings"
"github.com/speakeasy-api/openapi/extensions"
@@ -48,7 +49,9 @@ func (p *Paths) Validate(ctx context.Context, opts ...validation.Option) []error
if !strings.HasPrefix(path, "/") {
pathKeyNode := c.GetMapKeyNodeOrRoot(path, c.RootNode)
errs = append(errs, validation.NewValidationError(
- validation.NewValueValidationError("path '%s' must begin with a slash '/'", path),
+ validation.SeverityError,
+ validation.RuleValidationInvalidSyntax,
+ fmt.Errorf("path `%s` must begin with a slash '/'", path),
pathKeyNode))
}
errs = append(errs, pathItem.Validate(ctx, opts...)...)
diff --git a/swagger/response.go b/swagger/response.go
index baea119b..ce835fc7 100644
--- a/swagger/response.go
+++ b/swagger/response.go
@@ -2,6 +2,7 @@ package swagger
import (
"context"
+ "errors"
"github.com/speakeasy-api/openapi/extensions"
"github.com/speakeasy-api/openapi/internal/interfaces"
@@ -58,7 +59,9 @@ func (r *Responses) Validate(ctx context.Context, opts ...validation.Option) []e
hasResponse := (c.Default.Present && r.Default != nil) || (r.Map != nil && r.Len() > 0)
if !hasResponse {
errs = append(errs, validation.NewValueError(
- validation.NewMissingValueError("responses must contain at least one response code or default"),
+ validation.SeverityError,
+ validation.RuleValidationRequiredField,
+ errors.New("responses must contain at least one response code or default"),
c, c.Default))
}
@@ -139,7 +142,7 @@ func (r *Response) Validate(ctx context.Context, opts ...validation.Option) []er
errs := []error{}
if c.Description.Present && r.Description == "" {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("response.description is required"), c, c.Description))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("`response.description` is required"), c, c.Description))
}
for _, header := range r.Headers.All() {
@@ -228,7 +231,7 @@ func (h *Header) Validate(ctx context.Context, opts ...validation.Option) []erro
errs := []error{}
if c.Type.Present && h.Type == "" {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("header.type is required"), c, c.Type))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("`header.type` is required"), c, c.Type))
} else if c.Type.Present {
validTypes := []string{"string", "number", "integer", "boolean", "array"}
valid := false
@@ -239,12 +242,12 @@ func (h *Header) Validate(ctx context.Context, opts ...validation.Option) []erro
}
}
if !valid {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("header.type must be one of [string, number, integer, boolean, array]"), c, c.Type))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationAllowedValues, errors.New("header.type must be one of [string, number, integer, boolean, array]"), c, c.Type))
}
// Array type requires items
if h.Type == "array" && !c.Items.Present {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("header.items is required when type=array"), c, c.Items))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("header.items is required when type=array"), c, c.Items))
}
}
diff --git a/swagger/response_validate_test.go b/swagger/response_validate_test.go
index 4c8292f7..04e4dd5a 100644
--- a/swagger/response_validate_test.go
+++ b/swagger/response_validate_test.go
@@ -77,7 +77,7 @@ func TestResponse_Validate_Error(t *testing.T) {
{
name: "missing_description",
yml: `schema: {type: object}`,
- wantErrs: []string{"response.description is missing"},
+ wantErrs: []string{"`response.description` is required"},
},
}
@@ -164,7 +164,7 @@ func TestHeader_Validate_Error(t *testing.T) {
{
name: "missing_type",
yml: `description: Some header`,
- wantErrs: []string{"header.type is missing"},
+ wantErrs: []string{"`header.type` is required"},
},
{
name: "invalid_type",
diff --git a/swagger/security.go b/swagger/security.go
index 56fa8861..6acae8c7 100644
--- a/swagger/security.go
+++ b/swagger/security.go
@@ -2,6 +2,8 @@ package swagger
import (
"context"
+ "errors"
+ "fmt"
"net/url"
"strings"
@@ -153,7 +155,7 @@ func (s *SecurityScheme) Validate(ctx context.Context, opts ...validation.Option
errs := []error{}
if c.Type.Present && s.Type == "" {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("securityScheme.type is required"), c, c.Type))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("`securityScheme.type` is required"), c, c.Type))
} else {
validTypes := []SecuritySchemeType{SecuritySchemeTypeBasic, SecuritySchemeTypeAPIKey, SecuritySchemeTypeOAuth2}
valid := false
@@ -164,26 +166,26 @@ func (s *SecurityScheme) Validate(ctx context.Context, opts ...validation.Option
}
}
if !valid {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("securityScheme.type must be one of [%s]", strings.Join([]string{string(SecuritySchemeTypeBasic), string(SecuritySchemeTypeAPIKey), string(SecuritySchemeTypeOAuth2)}, ", ")), c, c.Type))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationAllowedValues, fmt.Errorf("securityScheme.type must be one of [`%s`]", strings.Join([]string{string(SecuritySchemeTypeBasic), string(SecuritySchemeTypeAPIKey), string(SecuritySchemeTypeOAuth2)}, ", ")), c, c.Type))
}
}
// Validate apiKey specific fields
if s.Type == SecuritySchemeTypeAPIKey {
if !c.Name.Present || s.Name == nil || *s.Name == "" {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("securityScheme.name is required for type=apiKey"), c, c.Name))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("`securityScheme.name` is required for type=apiKey"), c, c.Name))
}
if !c.In.Present || s.In == nil {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("securityScheme.in is required for type=apiKey"), c, c.In))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("`securityScheme.in` is required for type=apiKey"), c, c.In))
} else if *s.In != SecuritySchemeInQuery && *s.In != SecuritySchemeInHeader {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("securityScheme.in must be one of [%s] for type=apiKey", strings.Join([]string{string(SecuritySchemeInQuery), string(SecuritySchemeInHeader)}, ", ")), c, c.In))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationAllowedValues, fmt.Errorf("securityScheme.in must be one of [`%s`] for type=apiKey", strings.Join([]string{string(SecuritySchemeInQuery), string(SecuritySchemeInHeader)}, ", ")), c, c.In))
}
}
// Validate oauth2 specific fields
if s.Type == SecuritySchemeTypeOAuth2 {
if !c.Flow.Present || s.Flow == nil {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("securityScheme.flow is required for type=oauth2"), c, c.Flow))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("`securityScheme.flow` is required for type=oauth2"), c, c.Flow))
} else {
validFlows := []OAuth2Flow{OAuth2FlowImplicit, OAuth2FlowPassword, OAuth2FlowApplication, OAuth2FlowAccessCode}
valid := false
@@ -194,37 +196,37 @@ func (s *SecurityScheme) Validate(ctx context.Context, opts ...validation.Option
}
}
if !valid {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("securityScheme.flow must be one of [%s] for type=oauth2", strings.Join([]string{string(OAuth2FlowImplicit), string(OAuth2FlowPassword), string(OAuth2FlowApplication), string(OAuth2FlowAccessCode)}, ", ")), c, c.Flow))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationAllowedValues, fmt.Errorf("securityScheme.flow must be one of [`%s`] for type=oauth2", strings.Join([]string{string(OAuth2FlowImplicit), string(OAuth2FlowPassword), string(OAuth2FlowApplication), string(OAuth2FlowAccessCode)}, ", ")), c, c.Flow))
}
if s.Flow != nil {
// authorizationUrl required for implicit and accessCode flows
if (*s.Flow == OAuth2FlowImplicit || *s.Flow == OAuth2FlowAccessCode) && (!c.AuthorizationURL.Present || s.AuthorizationURL == nil || *s.AuthorizationURL == "") {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("securityScheme.authorizationUrl is required for flow=%s", *s.Flow), c, c.AuthorizationURL))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, fmt.Errorf("securityScheme.authorizationUrl is required for flow=%s", *s.Flow), c, c.AuthorizationURL))
}
// tokenUrl required for password, application and accessCode flows
if (*s.Flow == OAuth2FlowPassword || *s.Flow == OAuth2FlowApplication || *s.Flow == OAuth2FlowAccessCode) && (!c.TokenURL.Present || s.TokenURL == nil || *s.TokenURL == "") {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("securityScheme.tokenUrl is required for flow=%s", *s.Flow), c, c.TokenURL))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, fmt.Errorf("securityScheme.tokenUrl is required for flow=%s", *s.Flow), c, c.TokenURL))
}
}
}
if !c.Scopes.Present {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("securityScheme.scopes is required for type=oauth2"), c, c.Scopes))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("`securityScheme.scopes` is required for type=oauth2"), c, c.Scopes))
}
}
// Validate URLs
if c.AuthorizationURL.Present && s.AuthorizationURL != nil && *s.AuthorizationURL != "" {
if _, err := url.Parse(*s.AuthorizationURL); err != nil {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("securityScheme.authorizationUrl is not a valid uri: %s", err), c, c.AuthorizationURL))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationInvalidFormat, fmt.Errorf("securityScheme.authorizationUrl is not a valid uri: %w", err), c, c.AuthorizationURL))
}
}
if c.TokenURL.Present && s.TokenURL != nil && *s.TokenURL != "" {
if _, err := url.Parse(*s.TokenURL); err != nil {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("securityScheme.tokenUrl is not a valid uri: %s", err), c, c.TokenURL))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationInvalidFormat, fmt.Errorf("securityScheme.tokenUrl is not a valid uri: %w", err), c, c.TokenURL))
}
}
@@ -272,7 +274,9 @@ func (s *SecurityRequirement) Validate(ctx context.Context, opts ...validation.O
secScheme, exists := swagger.SecurityDefinitions.Get(name)
if !exists {
errs = append(errs, validation.NewValidationError(
- validation.NewValueValidationError("security requirement '%s' does not match any security scheme in securityDefinitions", name),
+ validation.SeverityError,
+ validation.RuleValidationSchemeNotFound,
+ fmt.Errorf("security requirement `%s` does not match any security scheme in securityDefinitions", name),
c.RootNode))
continue
}
@@ -281,7 +285,9 @@ func (s *SecurityRequirement) Validate(ctx context.Context, opts ...validation.O
if secScheme.Type != SecuritySchemeTypeOAuth2 {
if len(scopes) > 0 {
errs = append(errs, validation.NewValidationError(
- validation.NewValueValidationError("security requirement '%s' must have empty scopes array for non-oauth2 security scheme (type=%s)", name, secScheme.Type),
+ validation.SeverityError,
+ validation.RuleValidationAllowedValues,
+ fmt.Errorf("security requirement `%s` must have empty scopes array for non-oauth2 security scheme (type=`%s`)", name, secScheme.Type),
c.RootNode))
}
}
diff --git a/swagger/security_validate_test.go b/swagger/security_validate_test.go
index 4da59fda..b53170f7 100644
--- a/swagger/security_validate_test.go
+++ b/swagger/security_validate_test.go
@@ -99,7 +99,7 @@ func TestSecurityScheme_Validate_Error(t *testing.T) {
{
name: "missing_type",
yml: `description: Some security scheme`,
- wantErrs: []string{"securityScheme.type is missing"},
+ wantErrs: []string{"`securityScheme.type` is required"},
},
{
name: "invalid_type",
@@ -111,13 +111,13 @@ description: Test`,
name: "apiKey_missing_name",
yml: `type: apiKey
in: header`,
- wantErrs: []string{"securityScheme.name is required for type=apiKey"},
+ wantErrs: []string{"`securityScheme.name` is required for type=apiKey"},
},
{
name: "apiKey_missing_in",
yml: `type: apiKey
name: X-API-Key`,
- wantErrs: []string{"securityScheme.in is required for type=apiKey"},
+ wantErrs: []string{"`securityScheme.in` is required for type=apiKey"},
},
{
name: "apiKey_invalid_in",
@@ -131,7 +131,7 @@ in: invalid`,
yml: `type: oauth2
scopes:
read: Read access`,
- wantErrs: []string{"securityScheme.flow is required for type=oauth2"},
+ wantErrs: []string{"`securityScheme.flow` is required for type=oauth2"},
},
{
name: "oauth2_invalid_flow",
@@ -180,7 +180,7 @@ scopes:
yml: `type: oauth2
flow: password
tokenUrl: https://example.com/token`,
- wantErrs: []string{"securityScheme.scopes is required for type=oauth2"},
+ wantErrs: []string{"`securityScheme.scopes` is required for type=oauth2"},
},
}
diff --git a/swagger/swagger.go b/swagger/swagger.go
index 9e1f86d7..13984732 100644
--- a/swagger/swagger.go
+++ b/swagger/swagger.go
@@ -2,6 +2,8 @@ package swagger
import (
"context"
+ "errors"
+ "fmt"
"mime"
"strings"
@@ -191,9 +193,9 @@ func (s *Swagger) Validate(ctx context.Context, opts ...validation.Option) []err
errs := []error{}
if c.Swagger.Present && s.Swagger == "" {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("swagger is required"), c, c.Swagger))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("`swagger` is required"), c, c.Swagger))
} else if c.Swagger.Present && s.Swagger != "2.0" {
- errs = append(errs, validation.NewValueError(validation.NewValueValidationError("swagger must be '2.0'"), c, c.Swagger))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationSupportedVersion, errors.New("swagger must be '2.0'"), c, c.Swagger))
}
if c.Info.Present {
@@ -204,7 +206,9 @@ func (s *Swagger) Validate(ctx context.Context, opts ...validation.Option) []err
if c.BasePath.Present && s.BasePath != nil && *s.BasePath != "" {
if !strings.HasPrefix(*s.BasePath, "/") {
errs = append(errs, validation.NewValueError(
- validation.NewValueValidationError("basePath must start with a leading slash '/'"),
+ validation.SeverityError,
+ validation.RuleValidationInvalidSyntax,
+ errors.New("basePath must start with a leading slash '/'"),
c, c.BasePath))
}
}
@@ -222,7 +226,9 @@ func (s *Swagger) Validate(ctx context.Context, opts ...validation.Option) []err
}
if !valid {
errs = append(errs, validation.NewValueError(
- validation.NewValueValidationError("scheme must be one of [http, https, ws, wss], got '%s'", scheme),
+ validation.SeverityError,
+ validation.RuleValidationAllowedValues,
+ fmt.Errorf("scheme must be one of [http, https, ws, wss], got `%s`", scheme),
c, c.Schemes))
}
}
@@ -233,7 +239,9 @@ func (s *Swagger) Validate(ctx context.Context, opts ...validation.Option) []err
for _, mimeType := range s.Consumes {
if _, _, err := mime.ParseMediaType(mimeType); err != nil {
errs = append(errs, validation.NewValueError(
- validation.NewValueValidationError("consumes contains invalid MIME type '%s': %s", mimeType, err),
+ validation.SeverityError,
+ validation.RuleValidationInvalidFormat,
+ fmt.Errorf("consumes contains invalid MIME type `%s`: %w", mimeType, err),
c, c.Consumes))
}
}
@@ -244,7 +252,9 @@ func (s *Swagger) Validate(ctx context.Context, opts ...validation.Option) []err
for _, mimeType := range s.Produces {
if _, _, err := mime.ParseMediaType(mimeType); err != nil {
errs = append(errs, validation.NewValueError(
- validation.NewValueValidationError("produces contains invalid MIME type '%s': %s", mimeType, err),
+ validation.SeverityError,
+ validation.RuleValidationInvalidFormat,
+ fmt.Errorf("produces contains invalid MIME type `%s`: %w", mimeType, err),
c, c.Produces))
}
}
@@ -261,7 +271,9 @@ func (s *Swagger) Validate(ctx context.Context, opts ...validation.Option) []err
if tag != nil && tag.Name != "" {
if tagNames[tag.Name] {
errs = append(errs, validation.NewValueError(
- validation.NewValueValidationError("tag name '%s' must be unique", tag.Name),
+ validation.SeverityError,
+ validation.RuleValidationDuplicateKey,
+ fmt.Errorf("tag name `%s` must be unique", tag.Name),
c, c.Tags))
}
tagNames[tag.Name] = true
@@ -320,7 +332,9 @@ func (s *Swagger) validateOperationIDUniqueness(c *core.Swagger) []error {
opID := *operation.OperationID
if operationIDs[opID] {
errs = append(errs, validation.NewValueError(
- validation.NewValueValidationError("operationId '%s' must be unique among all operations", opID),
+ validation.SeverityError,
+ validation.RuleValidationDuplicateKey,
+ fmt.Errorf("operationId `%s` must be unique among all operations", opID),
c, c.Paths))
}
operationIDs[opID] = true
diff --git a/swagger/swagger_test.go b/swagger/swagger_test.go
index e63c8d3b..29ab4d52 100644
--- a/swagger/swagger_test.go
+++ b/swagger/swagger_test.go
@@ -79,13 +79,13 @@ func TestUnmarshal_ValidationErrors(t *testing.T) {
title: Test API
version: 1.0.0
paths: {}`,
- expectedError: "swagger is missing",
+ expectedError: "`swagger.swagger` is required",
},
{
name: "missing info field",
yaml: `swagger: "2.0"
paths: {}`,
- expectedError: "info is missing",
+ expectedError: "`swagger.info` is required",
},
{
name: "missing paths field",
@@ -93,7 +93,7 @@ paths: {}`,
info:
title: Test API
version: 1.0.0`,
- expectedError: "paths is missing",
+ expectedError: "`swagger.paths` is required",
},
{
name: "missing info.title",
@@ -101,7 +101,7 @@ info:
info:
version: 1.0.0
paths: {}`,
- expectedError: "info.title is missing",
+ expectedError: "`info.title` is required",
},
{
name: "missing info.version",
@@ -109,7 +109,7 @@ paths: {}`,
info:
title: Test API
paths: {}`,
- expectedError: "info.version is missing",
+ expectedError: "`info.version` is required",
},
{
name: "invalid swagger version",
diff --git a/swagger/swagger_validate_test.go b/swagger/swagger_validate_test.go
index 7a4b0f85..c611ddb4 100644
--- a/swagger/swagger_validate_test.go
+++ b/swagger/swagger_validate_test.go
@@ -584,7 +584,7 @@ tags:
- name: users
description: Duplicate tag
paths: {}`,
- wantErrs: []string{"tag name 'users' must be unique"},
+ wantErrs: []string{"tag name `users` must be unique"},
},
}
@@ -690,7 +690,7 @@ paths:
responses:
200:
description: Success`,
- wantErrs: []string{"operationId 'getItems' must be unique"},
+ wantErrs: []string{"operationId `getItems` must be unique"},
},
}
@@ -1101,17 +1101,17 @@ func TestSecurityRequirement_Validate_Error(t *testing.T) {
{
name: "undefined_security_scheme",
yml: `undefined: []`,
- wantErrs: []string{"security requirement 'undefined' does not match any security scheme"},
+ wantErrs: []string{"security requirement `undefined` does not match any security scheme"},
},
{
name: "apiKey_with_non_empty_scopes",
yml: `apiKey: ["some_scope"]`,
- wantErrs: []string{"security requirement 'apiKey' must have empty scopes array for non-oauth2"},
+ wantErrs: []string{"security requirement `apiKey` must have empty scopes array for non-oauth2"},
},
{
name: "basic_with_non_empty_scopes",
yml: `basic: ["some_scope"]`,
- wantErrs: []string{"security requirement 'basic' must have empty scopes array for non-oauth2"},
+ wantErrs: []string{"security requirement `basic` must have empty scopes array for non-oauth2"},
},
}
diff --git a/swagger/tag.go b/swagger/tag.go
index 60b6aba0..e294744f 100644
--- a/swagger/tag.go
+++ b/swagger/tag.go
@@ -2,6 +2,7 @@ package swagger
import (
"context"
+ "errors"
"github.com/speakeasy-api/openapi/extensions"
"github.com/speakeasy-api/openapi/internal/interfaces"
@@ -64,7 +65,7 @@ func (t *Tag) Validate(ctx context.Context, opts ...validation.Option) []error {
errs := []error{}
if c.Name.Present && t.Name == "" {
- errs = append(errs, validation.NewValueError(validation.NewMissingValueError("tag.name is required"), c, c.Name))
+ errs = append(errs, validation.NewValueError(validation.SeverityError, validation.RuleValidationRequiredField, errors.New("`tag.name` is required"), c, c.Name))
}
if c.ExternalDocs.Present {
diff --git a/swagger/tag_validate_test.go b/swagger/tag_validate_test.go
index e3bf4a79..ab755e87 100644
--- a/swagger/tag_validate_test.go
+++ b/swagger/tag_validate_test.go
@@ -63,7 +63,7 @@ func TestTag_Validate_Error(t *testing.T) {
{
name: "missing_name",
yml: `description: Some description`,
- wantErrs: []string{"tag.name is missing"},
+ wantErrs: []string{"`tag.name` is required"},
},
}
@@ -142,7 +142,7 @@ func TestExternalDocumentation_Validate_Error(t *testing.T) {
{
name: "missing_url",
yml: `description: Some description`,
- wantErrs: []string{"externalDocumentation.url is missing"},
+ wantErrs: []string{"`externalDocumentation.url` is required"},
},
}
diff --git a/validation/errors.go b/validation/errors.go
index 447757f8..d3ff660c 100644
--- a/validation/errors.go
+++ b/validation/errors.go
@@ -6,23 +6,72 @@ import (
"gopkg.in/yaml.v3"
)
+type Severity string
+
+const (
+ SeverityError Severity = "error"
+ SeverityWarning Severity = "warning"
+ SeverityHint Severity = "hint"
+)
+
+func (s Severity) String() string {
+ return string(s)
+}
+
+// Rank returns a numeric rank for severity comparison.
+// Higher rank means worse severity.
+// SeverityError = 2, SeverityWarning = 1, SeverityHint = 0.
+// Unknown severities are treated as SeverityError.
+func (s Severity) Rank() int {
+ switch s {
+ case SeverityError:
+ return 2
+ case SeverityWarning:
+ return 1
+ case SeverityHint:
+ return 0
+ default:
+ return 2 // Treat unknown as error
+ }
+}
+
// Error represents a validation error and the line and column where it occurred
// TODO allow getting the JSON path for line/column for validation errors
type Error struct {
UnderlyingError error
Node *yaml.Node
+ Severity Severity
+ Rule string
+ Fix Fix
+ // DocumentLocation is the absolute location (URL or file path) of the document
+ // where the error originated. Empty means the main document.
+ DocumentLocation string
+}
+
+// Fix represents a suggested fix for a error finding
+type Fix interface {
+ Apply(doc any) error
+ FixDescription() string
}
var _ error = (*Error)(nil)
func (e Error) Error() string {
- return fmt.Sprintf("[%d:%d] %s", e.GetLineNumber(), e.GetColumnNumber(), e.UnderlyingError.Error())
+ msg := fmt.Sprintf("[%d:%d] %s %s %s", e.GetLineNumber(), e.GetColumnNumber(), e.Severity, e.Rule, e.UnderlyingError.Error())
+ if e.DocumentLocation != "" {
+ msg = fmt.Sprintf("%s (document: %s)", msg, e.DocumentLocation)
+ }
+ return msg
}
func (e Error) Unwrap() error {
return e.UnderlyingError
}
+func (e Error) GetNode() *yaml.Node {
+ return e.Node
+}
+
func (e Error) GetLineNumber() int {
if e.Node == nil {
return -1
@@ -37,6 +86,15 @@ func (e Error) GetColumnNumber() int {
return e.Node.Column
}
+func (e Error) GetSeverity() Severity {
+ return e.Severity
+}
+
+// GetDocumentLocation returns the document location where the error originated.
+func (e Error) GetDocumentLocation() string {
+ return e.DocumentLocation
+}
+
// ValueNodeGetter provides access to value nodes for error reporting.
type ValueNodeGetter interface {
GetValueNodeOrRoot(root *yaml.Node) *yaml.Node
@@ -57,10 +115,23 @@ type MapValueNodeGetter interface {
GetMapValueNodeOrRoot(key string, root *yaml.Node) *yaml.Node
}
-func NewValidationError(err error, node *yaml.Node) error {
+func NewValidationError(severity Severity, rule string, err error, node *yaml.Node) error {
return &Error{
UnderlyingError: err,
Node: node,
+ Severity: severity,
+ Rule: rule,
+ }
+}
+
+// NewValidationErrorWithDocumentLocation creates a validation error with document location metadata.
+func NewValidationErrorWithDocumentLocation(severity Severity, rule string, err error, node *yaml.Node, documentLocation string) error {
+ return &Error{
+ UnderlyingError: err,
+ Node: node,
+ Severity: severity,
+ Rule: rule,
+ DocumentLocation: documentLocation,
}
}
@@ -68,7 +139,7 @@ type CoreModeler interface {
GetRootNode() *yaml.Node
}
-func NewValueError(err error, core CoreModeler, node ValueNodeGetter) error {
+func NewValueError(severity Severity, rule string, err error, core CoreModeler, node ValueNodeGetter) error {
rootNode := core.GetRootNode()
if rootNode == nil {
@@ -76,6 +147,8 @@ func NewValueError(err error, core CoreModeler, node ValueNodeGetter) error {
return &Error{
UnderlyingError: err,
// Default to line 0, column 0 if we can't get location info
+ Severity: severity,
+ Rule: rule,
}
}
valueNode := node.GetValueNodeOrRoot(rootNode)
@@ -83,10 +156,12 @@ func NewValueError(err error, core CoreModeler, node ValueNodeGetter) error {
return &Error{
UnderlyingError: err,
Node: valueNode,
+ Severity: severity,
+ Rule: rule,
}
}
-func NewSliceError(err error, core CoreModeler, node SliceNodeGetter, index int) error {
+func NewSliceError(severity Severity, rule string, err error, core CoreModeler, node SliceNodeGetter, index int) error {
rootNode := core.GetRootNode()
if rootNode == nil {
@@ -94,6 +169,8 @@ func NewSliceError(err error, core CoreModeler, node SliceNodeGetter, index int)
return &Error{
UnderlyingError: err,
// Default to line 0, column 0 if we can't get location info
+ Severity: severity,
+ Rule: rule,
}
}
valueNode := node.GetSliceValueNodeOrRoot(index, rootNode)
@@ -101,10 +178,12 @@ func NewSliceError(err error, core CoreModeler, node SliceNodeGetter, index int)
return &Error{
UnderlyingError: err,
Node: valueNode,
+ Severity: severity,
+ Rule: rule,
}
}
-func NewMapKeyError(err error, core CoreModeler, node MapKeyNodeGetter, key string) error {
+func NewMapKeyError(severity Severity, rule string, err error, core CoreModeler, node MapKeyNodeGetter, key string) error {
rootNode := core.GetRootNode()
if rootNode == nil {
@@ -112,6 +191,8 @@ func NewMapKeyError(err error, core CoreModeler, node MapKeyNodeGetter, key stri
return &Error{
UnderlyingError: err,
// Default to line 0, column 0 if we can't get location info
+ Severity: severity,
+ Rule: rule,
}
}
valueNode := node.GetMapKeyNodeOrRoot(key, rootNode)
@@ -119,10 +200,12 @@ func NewMapKeyError(err error, core CoreModeler, node MapKeyNodeGetter, key stri
return &Error{
UnderlyingError: err,
Node: valueNode,
+ Severity: severity,
+ Rule: rule,
}
}
-func NewMapValueError(err error, core CoreModeler, node MapValueNodeGetter, key string) error {
+func NewMapValueError(severity Severity, rule string, err error, core CoreModeler, node MapValueNodeGetter, key string) error {
rootNode := core.GetRootNode()
if rootNode == nil {
@@ -130,6 +213,8 @@ func NewMapValueError(err error, core CoreModeler, node MapValueNodeGetter, key
return &Error{
UnderlyingError: err,
// Default to line 0, column 0 if we can't get location info
+ Severity: severity,
+ Rule: rule,
}
}
valueNode := node.GetMapValueNodeOrRoot(key, rootNode)
@@ -137,6 +222,8 @@ func NewMapValueError(err error, core CoreModeler, node MapValueNodeGetter, key
return &Error{
UnderlyingError: err,
Node: valueNode,
+ Severity: severity,
+ Rule: rule,
}
}
@@ -166,55 +253,3 @@ func (e TypeMismatchError) Error() string {
return fmt.Sprintf("%s%s", name, e.Msg)
}
-
-type MissingFieldError struct {
- Msg string
-}
-
-var _ error = (*MissingFieldError)(nil)
-
-func NewMissingFieldError(msg string, args ...any) *MissingFieldError {
- return &MissingFieldError{
- Msg: fmt.Sprintf(msg, args...),
- }
-}
-
-func (e MissingFieldError) Error() string {
- return e.Msg
-}
-
-type MissingValueError struct {
- Msg string
-}
-
-var _ error = (*MissingValueError)(nil)
-
-func NewMissingValueError(msg string, args ...any) *MissingValueError {
- return &MissingValueError{
- Msg: fmt.Sprintf(msg, args...),
- }
-}
-
-func (e MissingValueError) Error() string {
- return e.Msg
-}
-
-type ValueValidationError struct {
- Msg string
-}
-
-var _ error = (*ValueValidationError)(nil)
-
-func NewValueValidationError(msg string, args ...any) *ValueValidationError {
- if len(args) > 0 {
- msg = fmt.Sprintf(msg, args...)
- }
-
- return &ValueValidationError{
- Msg: msg,
- }
-}
-
-func (e ValueValidationError) Error() string {
- return e.Msg
-}
diff --git a/validation/rules.go b/validation/rules.go
new file mode 100644
index 00000000..49412c1f
--- /dev/null
+++ b/validation/rules.go
@@ -0,0 +1,139 @@
+package validation
+
+const (
+ // Spec Validation Rules
+ RuleValidationRequiredField = "validation-required-field"
+ RuleValidationTypeMismatch = "validation-type-mismatch"
+ RuleValidationDuplicateKey = "validation-duplicate-key"
+ RuleValidationInvalidFormat = "validation-invalid-format"
+ RuleValidationEmptyValue = "validation-empty-value"
+ RuleValidationInvalidReference = "validation-invalid-reference"
+ RuleValidationInvalidSyntax = "validation-invalid-syntax"
+ RuleValidationInvalidSchema = "validation-invalid-schema"
+ RuleValidationInvalidTarget = "validation-invalid-target"
+ RuleValidationAllowedValues = "validation-allowed-values"
+ RuleValidationMutuallyExclusiveFields = "validation-mutually-exclusive-fields"
+ RuleValidationOperationNotFound = "validation-operation-not-found"
+ RuleValidationOperationIdUnique = "validation-operation-id-unique"
+ RuleValidationOperationParameters = "validation-operation-parameters"
+ RuleValidationSchemeNotFound = "validation-scheme-not-found"
+ RuleValidationTagNotFound = "validation-tag-not-found"
+ RuleValidationSupportedVersion = "validation-supported-version"
+ RuleValidationCircularReference = "validation-circular-reference"
+)
+
+type RuleInfo struct {
+ Summary string
+ Description string
+ HowToFix string
+}
+
+var ruleInfoByID = map[string]RuleInfo{
+ RuleValidationRequiredField: {
+ Summary: "Missing required field.",
+ Description: "Required fields must be present in the document. Missing required fields cause validation to fail.",
+ HowToFix: "Provide the required field in the document.",
+ },
+ RuleValidationTypeMismatch: {
+ Summary: "Type mismatch.",
+ Description: "Values must match the schema types defined in the specification. Mismatched types can break tooling and validation.",
+ HowToFix: "Update the value to match the schema type or adjust the schema.",
+ },
+ RuleValidationDuplicateKey: {
+ Summary: "Duplicate key.",
+ Description: "Duplicate keys are not allowed in objects. Remove duplicates to avoid parsing ambiguity.",
+ HowToFix: "Remove or rename the duplicate key.",
+ },
+ RuleValidationInvalidFormat: {
+ Summary: "Invalid format.",
+ Description: "Values must match the specified format. Invalid formats can lead to runtime or interoperability issues.",
+ HowToFix: "Use a value that conforms to the required format.",
+ },
+ RuleValidationEmptyValue: {
+ Summary: "Empty value.",
+ Description: "Values must not be empty when the field requires content. Empty values typically indicate missing data.",
+ HowToFix: "Provide a non-empty value.",
+ },
+ RuleValidationInvalidReference: {
+ Summary: "Invalid reference.",
+ Description: "References must resolve to existing components or locations. Broken references prevent correct validation and resolution.",
+ HowToFix: "Fix the $ref target or define the referenced component.",
+ },
+ RuleValidationInvalidSyntax: {
+ Summary: "Invalid syntax.",
+ Description: "Documents must be valid YAML or JSON. Syntax errors prevent parsing.",
+ HowToFix: "Correct the syntax errors in the document.",
+ },
+ RuleValidationInvalidSchema: {
+ Summary: "Invalid schema.",
+ Description: "Schemas must be valid according to the OpenAPI/JSON Schema rules. Invalid schemas can make the document unusable for tooling.",
+ HowToFix: "Correct schema keywords and values to match the specification.",
+ },
+ RuleValidationInvalidTarget: {
+ Summary: "Invalid target.",
+ Description: "Validation targets must exist and be valid for the context. Invalid targets typically indicate a bad reference path.",
+ HowToFix: "Point to a valid target or adjust the reference context.",
+ },
+ RuleValidationAllowedValues: {
+ Summary: "Value not allowed.",
+ Description: "Values must be one of the allowed values. Using disallowed values violates the specification.",
+ HowToFix: "Use a value from the allowed set.",
+ },
+ RuleValidationMutuallyExclusiveFields: {
+ Summary: "Mutually exclusive fields.",
+ Description: "Mutually exclusive fields cannot be used together. Choose one of the conflicting fields.",
+ HowToFix: "Remove one of the conflicting fields.",
+ },
+ RuleValidationOperationNotFound: {
+ Summary: "Operation not found.",
+ Description: "Referenced operations must exist in the specification. Missing operations indicate a broken link.",
+ HowToFix: "Add the operation or fix the reference.",
+ },
+ RuleValidationOperationIdUnique: {
+ Summary: "Duplicate operationId.",
+ Description: "Operation IDs must be unique across the specification. Duplicate IDs cause conflicts in tooling.",
+ HowToFix: "Assign unique operationId values.",
+ },
+ RuleValidationOperationParameters: {
+ Summary: "Invalid operation parameters.",
+ Description: "Operation parameters must be valid and correctly defined. Invalid parameters can break request handling.",
+ HowToFix: "Fix parameter definitions and resolve invalid references.",
+ },
+ RuleValidationSchemeNotFound: {
+ Summary: "Security scheme not found.",
+ Description: "Referenced security schemes must be defined. Missing schemes make security requirements invalid.",
+ HowToFix: "Define the security scheme or fix the scheme reference.",
+ },
+ RuleValidationTagNotFound: {
+ Summary: "Tag not found.",
+ Description: "Operation tags should be defined in the top-level tags array. Undefined tags make documentation inconsistent.",
+ HowToFix: "Add the tag to the top-level tags array or fix the tag name.",
+ },
+ RuleValidationSupportedVersion: {
+ Summary: "Unsupported OpenAPI version.",
+ Description: "The document must use a supported OpenAPI version. Unsupported versions may not be parsed correctly.",
+ HowToFix: "Update the document to a supported OpenAPI version.",
+ },
+ RuleValidationCircularReference: {
+ Summary: "Circular reference.",
+ Description: "Schemas must not contain circular references that cannot be resolved. Unresolvable cycles can break validation and tooling.",
+ HowToFix: "Refactor schemas to break the reference cycle.",
+ },
+}
+
+func RuleInfoForID(ruleID string) (RuleInfo, bool) {
+ info, ok := ruleInfoByID[ruleID]
+ return info, ok
+}
+
+func RuleSummary(ruleID string) string {
+ return ruleInfoByID[ruleID].Summary
+}
+
+func RuleDescription(ruleID string) string {
+ return ruleInfoByID[ruleID].Description
+}
+
+func RuleHowToFix(ruleID string) string {
+ return ruleInfoByID[ruleID].HowToFix
+}
diff --git a/validation/rules_test.go b/validation/rules_test.go
new file mode 100644
index 00000000..eb0ac09c
--- /dev/null
+++ b/validation/rules_test.go
@@ -0,0 +1,145 @@
+package validation
+
+import (
+ "testing"
+
+ "github.com/stretchr/testify/assert"
+)
+
+func TestRuleInfoForID_Success(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ ruleID string
+ expectOK bool
+ expectInfo RuleInfo
+ }{
+ {
+ name: "known rule returns info",
+ ruleID: RuleValidationRequiredField,
+ expectOK: true,
+ expectInfo: RuleInfo{
+ Summary: "Missing required field.",
+ Description: "Required fields must be present in the document. Missing required fields cause validation to fail.",
+ HowToFix: "Provide the required field in the document.",
+ },
+ },
+ {
+ name: "another known rule returns info",
+ ruleID: RuleValidationCircularReference,
+ expectOK: true,
+ expectInfo: RuleInfo{
+ Summary: "Circular reference.",
+ Description: "Schemas must not contain circular references that cannot be resolved. Unresolvable cycles can break validation and tooling.",
+ HowToFix: "Refactor schemas to break the reference cycle.",
+ },
+ },
+ {
+ name: "unknown rule returns empty info",
+ ruleID: "unknown-rule-id",
+ expectOK: false,
+ expectInfo: RuleInfo{},
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+
+ info, ok := RuleInfoForID(tt.ruleID)
+ assert.Equal(t, tt.expectOK, ok, "ok should match expected")
+ assert.Equal(t, tt.expectInfo, info, "info should match expected")
+ })
+ }
+}
+
+func TestRuleSummary_Success(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ ruleID string
+ expected string
+ }{
+ {
+ name: "known rule returns summary",
+ ruleID: RuleValidationTypeMismatch,
+ expected: "Type mismatch.",
+ },
+ {
+ name: "unknown rule returns empty string",
+ ruleID: "unknown-rule",
+ expected: "",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+
+ result := RuleSummary(tt.ruleID)
+ assert.Equal(t, tt.expected, result, "summary should match expected")
+ })
+ }
+}
+
+func TestRuleDescription_Success(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ ruleID string
+ expected string
+ }{
+ {
+ name: "known rule returns description",
+ ruleID: RuleValidationDuplicateKey,
+ expected: "Duplicate keys are not allowed in objects. Remove duplicates to avoid parsing ambiguity.",
+ },
+ {
+ name: "unknown rule returns empty string",
+ ruleID: "unknown-rule",
+ expected: "",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+
+ result := RuleDescription(tt.ruleID)
+ assert.Equal(t, tt.expected, result, "description should match expected")
+ })
+ }
+}
+
+func TestRuleHowToFix_Success(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ ruleID string
+ expected string
+ }{
+ {
+ name: "known rule returns how to fix",
+ ruleID: RuleValidationInvalidReference,
+ expected: "Fix the $ref target or define the referenced component.",
+ },
+ {
+ name: "unknown rule returns empty string",
+ ruleID: "unknown-rule",
+ expected: "",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+
+ result := RuleHowToFix(tt.ruleID)
+ assert.Equal(t, tt.expected, result, "how to fix should match expected")
+ })
+ }
+}
diff --git a/validation/utils_test.go b/validation/utils_test.go
index 7b42dee6..9e9c2a30 100644
--- a/validation/utils_test.go
+++ b/validation/utils_test.go
@@ -1,7 +1,7 @@
package validation
import (
- stderrors "errors"
+ "errors"
"testing"
"github.com/stretchr/testify/assert"
@@ -27,13 +27,13 @@ func TestSortValidationErrors_Success(t *testing.T) {
name: "single validation error",
errors: []error{
&Error{
- UnderlyingError: stderrors.New("error1"),
+ UnderlyingError: errors.New("error1"),
Node: &yaml.Node{Line: 5, Column: 10},
},
},
expected: []error{
&Error{
- UnderlyingError: stderrors.New("error1"),
+ UnderlyingError: errors.New("error1"),
Node: &yaml.Node{Line: 5, Column: 10},
},
},
@@ -42,29 +42,29 @@ func TestSortValidationErrors_Success(t *testing.T) {
name: "multiple validation errors sorted by line",
errors: []error{
&Error{
- UnderlyingError: stderrors.New("error3"),
+ UnderlyingError: errors.New("error3"),
Node: &yaml.Node{Line: 10, Column: 5},
},
&Error{
- UnderlyingError: stderrors.New("error1"),
+ UnderlyingError: errors.New("error1"),
Node: &yaml.Node{Line: 2, Column: 3},
},
&Error{
- UnderlyingError: stderrors.New("error2"),
+ UnderlyingError: errors.New("error2"),
Node: &yaml.Node{Line: 5, Column: 8},
},
},
expected: []error{
&Error{
- UnderlyingError: stderrors.New("error1"),
+ UnderlyingError: errors.New("error1"),
Node: &yaml.Node{Line: 2, Column: 3},
},
&Error{
- UnderlyingError: stderrors.New("error2"),
+ UnderlyingError: errors.New("error2"),
Node: &yaml.Node{Line: 5, Column: 8},
},
&Error{
- UnderlyingError: stderrors.New("error3"),
+ UnderlyingError: errors.New("error3"),
Node: &yaml.Node{Line: 10, Column: 5},
},
},
@@ -73,29 +73,29 @@ func TestSortValidationErrors_Success(t *testing.T) {
name: "validation errors with same line sorted by column",
errors: []error{
&Error{
- UnderlyingError: stderrors.New("error2"),
+ UnderlyingError: errors.New("error2"),
Node: &yaml.Node{Line: 5, Column: 15},
},
&Error{
- UnderlyingError: stderrors.New("error1"),
+ UnderlyingError: errors.New("error1"),
Node: &yaml.Node{Line: 5, Column: 3},
},
&Error{
- UnderlyingError: stderrors.New("error3"),
+ UnderlyingError: errors.New("error3"),
Node: &yaml.Node{Line: 5, Column: 20},
},
},
expected: []error{
&Error{
- UnderlyingError: stderrors.New("error1"),
+ UnderlyingError: errors.New("error1"),
Node: &yaml.Node{Line: 5, Column: 3},
},
&Error{
- UnderlyingError: stderrors.New("error2"),
+ UnderlyingError: errors.New("error2"),
Node: &yaml.Node{Line: 5, Column: 15},
},
&Error{
- UnderlyingError: stderrors.New("error3"),
+ UnderlyingError: errors.New("error3"),
Node: &yaml.Node{Line: 5, Column: 20},
},
},
@@ -103,54 +103,54 @@ func TestSortValidationErrors_Success(t *testing.T) {
{
name: "mix of validation errors and regular errors",
errors: []error{
- stderrors.New("regular error 2"),
+ errors.New("regular error 2"),
&Error{
- UnderlyingError: stderrors.New("validation error"),
+ UnderlyingError: errors.New("validation error"),
Node: &yaml.Node{Line: 5, Column: 10},
},
- stderrors.New("regular error 1"),
+ errors.New("regular error 1"),
},
expected: []error{
&Error{
- UnderlyingError: stderrors.New("validation error"),
+ UnderlyingError: errors.New("validation error"),
Node: &yaml.Node{Line: 5, Column: 10},
},
- stderrors.New("regular error 2"),
- stderrors.New("regular error 1"),
+ errors.New("regular error 2"),
+ errors.New("regular error 1"),
},
},
{
name: "only regular errors",
errors: []error{
- stderrors.New("error C"),
- stderrors.New("error A"),
- stderrors.New("error B"),
+ errors.New("error C"),
+ errors.New("error A"),
+ errors.New("error B"),
},
expected: []error{
- stderrors.New("error C"),
- stderrors.New("error A"),
- stderrors.New("error B"),
+ errors.New("error C"),
+ errors.New("error A"),
+ errors.New("error B"),
},
},
{
name: "validation errors with nil nodes",
errors: []error{
&Error{
- UnderlyingError: stderrors.New("error with nil node"),
+ UnderlyingError: errors.New("error with nil node"),
Node: nil,
},
&Error{
- UnderlyingError: stderrors.New("error with node"),
+ UnderlyingError: errors.New("error with node"),
Node: &yaml.Node{Line: 5, Column: 10},
},
},
expected: []error{
&Error{
- UnderlyingError: stderrors.New("error with nil node"),
+ UnderlyingError: errors.New("error with nil node"),
Node: nil,
},
&Error{
- UnderlyingError: stderrors.New("error with node"),
+ UnderlyingError: errors.New("error with node"),
Node: &yaml.Node{Line: 5, Column: 10},
},
},
@@ -158,65 +158,65 @@ func TestSortValidationErrors_Success(t *testing.T) {
{
name: "complex mixed scenario",
errors: []error{
- stderrors.New("regular error"),
+ errors.New("regular error"),
&Error{
- UnderlyingError: stderrors.New("validation error line 10"),
+ UnderlyingError: errors.New("validation error line 10"),
Node: &yaml.Node{Line: 10, Column: 5},
},
&Error{
- UnderlyingError: stderrors.New("validation error line 2 col 15"),
+ UnderlyingError: errors.New("validation error line 2 col 15"),
Node: &yaml.Node{Line: 2, Column: 15},
},
&Error{
- UnderlyingError: stderrors.New("validation error line 2 col 3"),
+ UnderlyingError: errors.New("validation error line 2 col 3"),
Node: &yaml.Node{Line: 2, Column: 3},
},
- stderrors.New("another regular error"),
+ errors.New("another regular error"),
},
expected: []error{
&Error{
- UnderlyingError: stderrors.New("validation error line 2 col 3"),
+ UnderlyingError: errors.New("validation error line 2 col 3"),
Node: &yaml.Node{Line: 2, Column: 3},
},
&Error{
- UnderlyingError: stderrors.New("validation error line 2 col 15"),
+ UnderlyingError: errors.New("validation error line 2 col 15"),
Node: &yaml.Node{Line: 2, Column: 15},
},
&Error{
- UnderlyingError: stderrors.New("validation error line 10"),
+ UnderlyingError: errors.New("validation error line 10"),
Node: &yaml.Node{Line: 10, Column: 5},
},
- stderrors.New("regular error"),
- stderrors.New("another regular error"),
+ errors.New("regular error"),
+ errors.New("another regular error"),
},
},
{
name: "validation errors with zero line/column",
errors: []error{
&Error{
- UnderlyingError: stderrors.New("error at 0,0"),
+ UnderlyingError: errors.New("error at 0,0"),
Node: &yaml.Node{Line: 0, Column: 0},
},
&Error{
- UnderlyingError: stderrors.New("error at 1,1"),
+ UnderlyingError: errors.New("error at 1,1"),
Node: &yaml.Node{Line: 1, Column: 1},
},
&Error{
- UnderlyingError: stderrors.New("error at 0,5"),
+ UnderlyingError: errors.New("error at 0,5"),
Node: &yaml.Node{Line: 0, Column: 5},
},
},
expected: []error{
&Error{
- UnderlyingError: stderrors.New("error at 0,0"),
+ UnderlyingError: errors.New("error at 0,0"),
Node: &yaml.Node{Line: 0, Column: 0},
},
&Error{
- UnderlyingError: stderrors.New("error at 0,5"),
+ UnderlyingError: errors.New("error at 0,5"),
Node: &yaml.Node{Line: 0, Column: 5},
},
&Error{
- UnderlyingError: stderrors.New("error at 1,1"),
+ UnderlyingError: errors.New("error at 1,1"),
Node: &yaml.Node{Line: 1, Column: 1},
},
},
@@ -245,8 +245,8 @@ func TestSortValidationErrors_Success(t *testing.T) {
// Check if both are validation errors
var expectedValidationErr, actualValidationErr *Error
- expectedIsValidation := stderrors.As(expectedErr, &expectedValidationErr)
- actualIsValidation := stderrors.As(actualErr, &actualValidationErr)
+ expectedIsValidation := errors.As(expectedErr, &expectedValidationErr)
+ actualIsValidation := errors.As(actualErr, &actualValidationErr)
switch {
case expectedIsValidation && actualIsValidation:
@@ -290,7 +290,7 @@ func TestSortValidationErrors_EdgeCases_Success(t *testing.T) {
errors := []error{
nil,
&Error{
- UnderlyingError: stderrors.New("valid error"),
+ UnderlyingError: errors.New("valid error"),
Node: &yaml.Node{Line: 1, Column: 1},
},
nil,
@@ -313,15 +313,15 @@ func TestSortValidationErrors_EdgeCases_Success(t *testing.T) {
errors := []error{
&Error{
- UnderlyingError: stderrors.New("error with negative line"),
+ UnderlyingError: errors.New("error with negative line"),
Node: &yaml.Node{Line: -1, Column: 5},
},
&Error{
- UnderlyingError: stderrors.New("error with positive line"),
+ UnderlyingError: errors.New("error with positive line"),
Node: &yaml.Node{Line: 1, Column: 5},
},
&Error{
- UnderlyingError: stderrors.New("error with negative column"),
+ UnderlyingError: errors.New("error with negative column"),
Node: &yaml.Node{Line: 1, Column: -1},
},
}
@@ -337,4 +337,137 @@ func TestSortValidationErrors_EdgeCases_Success(t *testing.T) {
assert.Equal(t, "error with negative column", err1.UnderlyingError.Error())
assert.Equal(t, "error with positive line", err2.UnderlyingError.Error())
})
+
+ t.Run("same line and column sorted by error message", func(t *testing.T) {
+ t.Parallel()
+
+ errors := []error{
+ &Error{
+ UnderlyingError: errors.New("zzz error"),
+ Node: &yaml.Node{Line: 5, Column: 10},
+ },
+ &Error{
+ UnderlyingError: errors.New("aaa error"),
+ Node: &yaml.Node{Line: 5, Column: 10},
+ },
+ &Error{
+ UnderlyingError: errors.New("mmm error"),
+ Node: &yaml.Node{Line: 5, Column: 10},
+ },
+ }
+
+ SortValidationErrors(errors)
+
+ var err0, err1, err2 *Error
+ require.ErrorAs(t, errors[0], &err0)
+ require.ErrorAs(t, errors[1], &err1)
+ require.ErrorAs(t, errors[2], &err2)
+ assert.Equal(t, "aaa error", err0.UnderlyingError.Error())
+ assert.Equal(t, "mmm error", err1.UnderlyingError.Error())
+ assert.Equal(t, "zzz error", err2.UnderlyingError.Error())
+ })
+
+ t.Run("same line column and identical error message", func(t *testing.T) {
+ t.Parallel()
+
+ errors := []error{
+ &Error{
+ UnderlyingError: errors.New("same error"),
+ Node: &yaml.Node{Line: 5, Column: 10},
+ Severity: SeverityError,
+ },
+ &Error{
+ UnderlyingError: errors.New("same error"),
+ Node: &yaml.Node{Line: 5, Column: 10},
+ Severity: SeverityWarning,
+ },
+ }
+
+ SortValidationErrors(errors)
+
+ // Both have same message so order should remain stable
+ var err0, err1 *Error
+ require.ErrorAs(t, errors[0], &err0)
+ require.ErrorAs(t, errors[1], &err1)
+ // Both should have the same message
+ assert.Equal(t, "same error", err0.UnderlyingError.Error())
+ assert.Equal(t, "same error", err1.UnderlyingError.Error())
+ // Stable sort means first stays first
+ assert.Equal(t, SeverityError, err0.Severity)
+ assert.Equal(t, SeverityWarning, err1.Severity)
+ })
+
+ t.Run("interleaved regular and validation errors forces all comparison branches", func(t *testing.T) {
+ t.Parallel()
+
+ // Interleave regular and validation errors to force the sorting algorithm
+ // to compare them in both directions (a=regular/b=validation AND a=validation/b=regular)
+ errors := []error{
+ errors.New("regular error 1"),
+ &Error{
+ UnderlyingError: errors.New("validation error 1"),
+ Node: &yaml.Node{Line: 10, Column: 5},
+ },
+ errors.New("regular error 2"),
+ &Error{
+ UnderlyingError: errors.New("validation error 2"),
+ Node: &yaml.Node{Line: 5, Column: 3},
+ },
+ errors.New("regular error 3"),
+ &Error{
+ UnderlyingError: errors.New("validation error 3"),
+ Node: &yaml.Node{Line: 15, Column: 7},
+ },
+ errors.New("regular error 4"),
+ }
+
+ SortValidationErrors(errors)
+
+ // Validation errors should come first, sorted by line number
+ var validationErr0, validationErr1, validationErr2 *Error
+ require.ErrorAs(t, errors[0], &validationErr0)
+ require.ErrorAs(t, errors[1], &validationErr1)
+ require.ErrorAs(t, errors[2], &validationErr2)
+ assert.Equal(t, 5, validationErr0.Node.Line, "first validation error should be line 5")
+ assert.Equal(t, 10, validationErr1.Node.Line, "second validation error should be line 10")
+ assert.Equal(t, 15, validationErr2.Node.Line, "third validation error should be line 15")
+
+ // Regular errors should follow, preserving stable order
+ var notValidation *Error
+ assert.NotErrorAs(t, errors[3], ¬Validation, "index 3 should be regular error")
+ assert.NotErrorAs(t, errors[4], ¬Validation, "index 4 should be regular error")
+ assert.NotErrorAs(t, errors[5], ¬Validation, "index 5 should be regular error")
+ assert.NotErrorAs(t, errors[6], ¬Validation, "index 6 should be regular error")
+ })
+
+ t.Run("validation errors first then regular errors forces bIsValidationErr", func(t *testing.T) {
+ t.Parallel()
+
+ // Start with validation errors, then regular errors
+ // The merge sort should compare elements in the opposite direction during some phase
+ errors := []error{
+ &Error{
+ UnderlyingError: errors.New("validation error 1"),
+ Node: &yaml.Node{Line: 20, Column: 10},
+ },
+ &Error{
+ UnderlyingError: errors.New("validation error 2"),
+ Node: &yaml.Node{Line: 10, Column: 5},
+ },
+ errors.New("regular error 1"),
+ errors.New("regular error 2"),
+ }
+
+ SortValidationErrors(errors)
+
+ // Validation errors should come first, sorted by line
+ var validationErr0, validationErr1 *Error
+ require.ErrorAs(t, errors[0], &validationErr0)
+ require.ErrorAs(t, errors[1], &validationErr1)
+ assert.Equal(t, 10, validationErr0.Node.Line)
+ assert.Equal(t, 20, validationErr1.Node.Line)
+ // Regular errors follow
+ assert.Equal(t, "regular error 1", errors[2].Error())
+ assert.Equal(t, "regular error 2", errors[3].Error())
+ })
}
diff --git a/validation/validation_test.go b/validation/validation_test.go
index ce7cf5b9..d53c2ed9 100644
--- a/validation/validation_test.go
+++ b/validation/validation_test.go
@@ -22,31 +22,37 @@ func TestError_Error_Success(t *testing.T) {
name: "error with valid node",
err: &Error{
UnderlyingError: errors.New("test error"),
+ Severity: SeverityError,
+ Rule: RuleValidationTypeMismatch,
Node: &yaml.Node{
Line: 10,
Column: 5,
},
},
- expected: "[10:5] test error",
+ expected: "[10:5] error validation-type-mismatch test error",
},
{
name: "error with nil node",
err: &Error{
UnderlyingError: errors.New("test error"),
+ Severity: SeverityWarning,
+ Rule: RuleValidationInvalidFormat,
Node: nil,
},
- expected: "[-1:-1] test error",
+ expected: "[-1:-1] warning validation-invalid-format test error",
},
{
name: "error with zero line/column",
err: &Error{
UnderlyingError: errors.New("test error"),
+ Severity: SeverityError,
+ Rule: RuleValidationRequiredField,
Node: &yaml.Node{
Line: 0,
Column: 0,
},
},
- expected: "[0:0] test error",
+ expected: "[0:0] error validation-required-field test error",
},
}
@@ -162,12 +168,14 @@ func TestNewValidationError_Success(t *testing.T) {
underlyingErr := errors.New("test error")
node := &yaml.Node{Line: 5, Column: 10}
- result := NewValidationError(underlyingErr, node)
+ result := NewValidationError(SeverityError, RuleValidationTypeMismatch, underlyingErr, node)
var validationErr *Error
require.ErrorAs(t, result, &validationErr, "should return *Error type")
assert.Equal(t, underlyingErr, validationErr.UnderlyingError)
assert.Equal(t, node, validationErr.Node)
+ assert.Equal(t, SeverityError, validationErr.Severity)
+ assert.Equal(t, RuleValidationTypeMismatch, validationErr.Rule)
}
// Mock types for testing the error creation functions
@@ -270,12 +278,14 @@ func TestNewValueError_Success(t *testing.T) {
t.Parallel()
underlyingErr := errors.New("test error")
- result := NewValueError(underlyingErr, tt.core, tt.nodeGetter)
+ result := NewValueError(SeverityError, RuleValidationTypeMismatch, underlyingErr, tt.core, tt.nodeGetter)
var validationErr *Error
require.ErrorAs(t, result, &validationErr, "should return *Error type")
assert.Equal(t, underlyingErr, validationErr.UnderlyingError)
assert.Equal(t, tt.expectedNode, validationErr.Node)
+ assert.Equal(t, SeverityError, validationErr.Severity)
+ assert.Equal(t, RuleValidationTypeMismatch, validationErr.Rule)
})
}
}
@@ -320,12 +330,14 @@ func TestNewSliceError_Success(t *testing.T) {
t.Parallel()
underlyingErr := errors.New("slice error")
- result := NewSliceError(underlyingErr, tt.core, tt.nodeGetter, tt.index)
+ result := NewSliceError(SeverityError, RuleValidationTypeMismatch, underlyingErr, tt.core, tt.nodeGetter, tt.index)
var validationErr *Error
require.ErrorAs(t, result, &validationErr, "should return *Error type")
assert.Equal(t, underlyingErr, validationErr.UnderlyingError)
assert.Equal(t, tt.expectedNode, validationErr.Node)
+ assert.Equal(t, SeverityError, validationErr.Severity)
+ assert.Equal(t, RuleValidationTypeMismatch, validationErr.Rule)
})
}
}
@@ -370,12 +382,14 @@ func TestNewMapKeyError_Success(t *testing.T) {
t.Parallel()
underlyingErr := errors.New("map key error")
- result := NewMapKeyError(underlyingErr, tt.core, tt.nodeGetter, tt.key)
+ result := NewMapKeyError(SeverityError, RuleValidationTypeMismatch, underlyingErr, tt.core, tt.nodeGetter, tt.key)
var validationErr *Error
require.ErrorAs(t, result, &validationErr, "should return *Error type")
assert.Equal(t, underlyingErr, validationErr.UnderlyingError)
assert.Equal(t, tt.expectedNode, validationErr.Node)
+ assert.Equal(t, SeverityError, validationErr.Severity)
+ assert.Equal(t, RuleValidationTypeMismatch, validationErr.Rule)
})
}
}
@@ -420,7 +434,7 @@ func TestNewMapValueError_Success(t *testing.T) {
t.Parallel()
underlyingErr := errors.New("map value error")
- result := NewMapValueError(underlyingErr, tt.core, tt.nodeGetter, tt.key)
+ result := NewMapValueError(SeverityError, RuleValidationTypeMismatch, underlyingErr, tt.core, tt.nodeGetter, tt.key)
var validationErr *Error
require.ErrorAs(t, result, &validationErr, "should return *Error type")
@@ -471,27 +485,29 @@ func TestTypeMismatchError_Success(t *testing.T) {
}
}
-// Test MissingFieldError
-func TestMissingFieldError_Success(t *testing.T) {
+// Test Severity.String() method
+func TestSeverity_String_Success(t *testing.T) {
t.Parallel()
tests := []struct {
name string
- msg string
- args []any
+ severity Severity
expected string
}{
{
- name: "simple missing field message",
- msg: "required field missing",
- args: nil,
- expected: "required field missing",
+ name: "error severity",
+ severity: SeverityError,
+ expected: "error",
+ },
+ {
+ name: "warning severity",
+ severity: SeverityWarning,
+ expected: "warning",
},
{
- name: "missing field with field name",
- msg: "required field '%s' is missing",
- args: []any{"name"},
- expected: "required field 'name' is missing",
+ name: "hint severity",
+ severity: SeverityHint,
+ expected: "hint",
},
}
@@ -499,34 +515,45 @@ func TestMissingFieldError_Success(t *testing.T) {
t.Run(tt.name, func(t *testing.T) {
t.Parallel()
- err := NewMissingFieldError(tt.msg, tt.args...)
- assert.Equal(t, tt.expected, err.Error())
- assert.Equal(t, tt.expected, err.Msg)
+ result := tt.severity.String()
+ assert.Equal(t, tt.expected, result, "severity string should match")
})
}
}
-// Test MissingValueError
-func TestMissingValueError_Success(t *testing.T) {
+// Test Severity.Rank() method
+func TestSeverity_Rank_Success(t *testing.T) {
t.Parallel()
tests := []struct {
name string
- msg string
- args []any
- expected string
+ severity Severity
+ expected int
}{
{
- name: "simple missing value message",
- msg: "value is required",
- args: nil,
- expected: "value is required",
+ name: "error severity has rank 2",
+ severity: SeverityError,
+ expected: 2,
+ },
+ {
+ name: "warning severity has rank 1",
+ severity: SeverityWarning,
+ expected: 1,
+ },
+ {
+ name: "hint severity has rank 0",
+ severity: SeverityHint,
+ expected: 0,
+ },
+ {
+ name: "unknown severity treated as error",
+ severity: Severity("unknown"),
+ expected: 2,
},
{
- name: "missing value with context",
- msg: "value for field '%s' is required",
- args: []any{"description"},
- expected: "value for field 'description' is required",
+ name: "empty severity treated as error",
+ severity: Severity(""),
+ expected: 2,
},
}
@@ -534,40 +561,201 @@ func TestMissingValueError_Success(t *testing.T) {
t.Run(tt.name, func(t *testing.T) {
t.Parallel()
- err := NewMissingValueError(tt.msg, tt.args...)
- assert.Equal(t, tt.expected, err.Error())
- assert.Equal(t, tt.expected, err.Msg)
+ result := tt.severity.Rank()
+ assert.Equal(t, tt.expected, result, "severity rank should match")
})
}
}
-// Test ValueValidationError
-func TestValueValidationError_Success(t *testing.T) {
+// Test Severity.Rank() ordering for comparison
+func TestSeverity_Rank_Ordering(t *testing.T) {
+ t.Parallel()
+
+ // Verify that error > warning > hint in terms of rank (worse severity = higher rank)
+ assert.Greater(t, SeverityError.Rank(), SeverityWarning.Rank(), "error should have higher rank than warning")
+ assert.Greater(t, SeverityWarning.Rank(), SeverityHint.Rank(), "warning should have higher rank than hint")
+ assert.Greater(t, SeverityError.Rank(), SeverityHint.Rank(), "error should have higher rank than hint")
+}
+
+// Test Error.GetSeverity() method
+func TestError_GetSeverity_Success(t *testing.T) {
t.Parallel()
tests := []struct {
name string
- msg string
- args []any
+ err *Error
+ expected Severity
+ }{
+ {
+ name: "error severity",
+ err: &Error{
+ UnderlyingError: errors.New("test error"),
+ Severity: SeverityError,
+ },
+ expected: SeverityError,
+ },
+ {
+ name: "warning severity",
+ err: &Error{
+ UnderlyingError: errors.New("test warning"),
+ Severity: SeverityWarning,
+ },
+ expected: SeverityWarning,
+ },
+ {
+ name: "hint severity",
+ err: &Error{
+ UnderlyingError: errors.New("test hint"),
+ Severity: SeverityHint,
+ },
+ expected: SeverityHint,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+
+ result := tt.err.GetSeverity()
+ assert.Equal(t, tt.expected, result, "severity should match")
+ })
+ }
+}
+
+// Test Error.Error() with DocumentLocation
+func TestError_Error_WithDocumentLocation(t *testing.T) {
+ t.Parallel()
+
+ err := &Error{
+ UnderlyingError: errors.New("test error"),
+ Severity: SeverityError,
+ Rule: RuleValidationInvalidReference,
+ Node: &yaml.Node{Line: 5, Column: 3},
+ DocumentLocation: "https://example.com/spec.yaml",
+ }
+
+ result := err.Error()
+ assert.Equal(t, "[5:3] error validation-invalid-reference test error (document: https://example.com/spec.yaml)", result)
+}
+
+// Test Error.GetNode() method
+func TestError_GetNode_Success(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ err *Error
+ expected *yaml.Node
+ }{
+ {
+ name: "returns node when set",
+ err: &Error{
+ Node: &yaml.Node{Line: 10, Column: 5},
+ },
+ expected: &yaml.Node{Line: 10, Column: 5},
+ },
+ {
+ name: "returns nil when node is nil",
+ err: &Error{
+ Node: nil,
+ },
+ expected: nil,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+
+ result := tt.err.GetNode()
+ assert.Equal(t, tt.expected, result, "node should match expected")
+ })
+ }
+}
+
+// Test Error.GetDocumentLocation() method
+func TestError_GetDocumentLocation_Success(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ err *Error
expected string
}{
{
- name: "simple validation error",
- msg: "invalid value",
- args: nil,
- expected: "invalid value",
+ name: "returns document location when set",
+ err: &Error{
+ DocumentLocation: "https://example.com/spec.yaml",
+ },
+ expected: "https://example.com/spec.yaml",
+ },
+ {
+ name: "returns empty string when not set",
+ err: &Error{},
+ expected: "",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+
+ result := tt.err.GetDocumentLocation()
+ assert.Equal(t, tt.expected, result, "document location should match expected")
+ })
+ }
+}
+
+// Test NewValidationErrorWithDocumentLocation function
+func TestNewValidationErrorWithDocumentLocation_Success(t *testing.T) {
+ t.Parallel()
+
+ underlyingErr := errors.New("remote error")
+ node := &yaml.Node{Line: 15, Column: 8}
+ docLocation := "https://example.com/components.yaml"
+
+ result := NewValidationErrorWithDocumentLocation(SeverityWarning, RuleValidationInvalidReference, underlyingErr, node, docLocation)
+
+ var validationErr *Error
+ require.ErrorAs(t, result, &validationErr, "should return *Error type")
+ assert.Equal(t, underlyingErr, validationErr.UnderlyingError, "underlying error should match")
+ assert.Equal(t, node, validationErr.Node, "node should match")
+ assert.Equal(t, SeverityWarning, validationErr.Severity, "severity should match")
+ assert.Equal(t, RuleValidationInvalidReference, validationErr.Rule, "rule should match")
+ assert.Equal(t, docLocation, validationErr.DocumentLocation, "document location should match")
+}
+
+// Test TypeMismatchError with ParentName
+func TestTypeMismatchError_WithParentName_Success(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ parentName string
+ msg string
+ args []any
+ expected string
+ }{
+ {
+ name: "with parent name",
+ parentName: "Response",
+ msg: "type mismatch",
+ args: nil,
+ expected: "Response type mismatch",
},
{
- name: "validation error with formatting",
- msg: "value '%s' is not valid for field '%s'",
- args: []any{"invalid", "status"},
- expected: "value 'invalid' is not valid for field 'status'",
+ name: "with parent name and formatting",
+ parentName: "Schema",
+ msg: "expected %s, got %s",
+ args: []any{"string", "int"},
+ expected: "Schema expected string, got int",
},
{
- name: "validation error with no args but formatting placeholders",
- msg: "value %s is invalid",
- args: []any{},
- expected: "value %s is invalid",
+ name: "empty parent name",
+ parentName: "",
+ msg: "standalone error",
+ args: nil,
+ expected: "standalone error",
},
}
@@ -575,9 +763,8 @@ func TestValueValidationError_Success(t *testing.T) {
t.Run(tt.name, func(t *testing.T) {
t.Parallel()
- err := NewValueValidationError(tt.msg, tt.args...)
- assert.Equal(t, tt.expected, err.Error())
- assert.Equal(t, tt.expected, err.Msg)
+ err := NewTypeMismatchError(tt.parentName, tt.msg, tt.args...)
+ assert.Equal(t, tt.expected, err.Error(), "error message should match")
})
}
}
diff --git a/values/core/eithervalue.go b/values/core/eithervalue.go
index e55a87d6..b280f0e7 100644
--- a/values/core/eithervalue.go
+++ b/values/core/eithervalue.go
@@ -75,11 +75,14 @@ func (v *EitherValue[L, R]) Unmarshal(ctx context.Context, parentName string, no
name += " "
}
- validationError = validation.NewValueValidationError(fmt.Sprintf("%s%s", name, msg))
+ validationError = fmt.Errorf("%s%s", name, msg)
}
+ // Get severity and rule from the worst error
+ severity, rule := getWorstSeverityAndRule(allParentErrs)
+
// Return the validation error along with all child errors separately
- result := []error{validation.NewValidationError(validationError, node)}
+ result := []error{validation.NewValidationError(severity, rule, validationError, node)}
result = append(result, leftChildErrs...)
result = append(result, rightChildErrs...)
@@ -155,7 +158,7 @@ func (v *EitherValue[L, R]) SyncChanges(ctx context.Context, model any, valueNod
}
if mv.Kind() != reflect.Struct {
- return nil, fmt.Errorf("expected struct, got %s", mv.Kind())
+ return nil, fmt.Errorf("expected `struct`, got `%s`", mv.Kind())
}
lf := mv.FieldByName("Left")
@@ -252,3 +255,34 @@ func typeToName[T any]() string {
return name
}
+
+// getWorstSeverityAndRule finds the worst severity and its first rule from a list of errors.
+// Severity order (worst to best): error > warning > hint
+// Returns the severity and rule of the first error with the worst severity.
+// If no validation errors are found, returns SeverityError and RuleValidationTypeMismatch as defaults.
+func getWorstSeverityAndRule(errs []error) (validation.Severity, string) {
+ var worstSeverity validation.Severity
+ var worstRule string
+ worstSeverityRank := -1 // -1 means no validation error found yet
+
+ for _, err := range errs {
+ var validationErr *validation.Error
+ if !errors.As(err, &validationErr) {
+ continue
+ }
+
+ rank := validationErr.Severity.Rank()
+ if rank > worstSeverityRank {
+ worstSeverityRank = rank
+ worstSeverity = validationErr.Severity
+ worstRule = validationErr.Rule
+ }
+ }
+
+ // Default to error severity and type mismatch rule if no validation errors found
+ if worstSeverityRank == -1 {
+ return validation.SeverityError, validation.RuleValidationTypeMismatch
+ }
+
+ return worstSeverity, worstRule
+}
diff --git a/values/core/eithervalue_test.go b/values/core/eithervalue_test.go
index b4fb7511..6270c21d 100644
--- a/values/core/eithervalue_test.go
+++ b/values/core/eithervalue_test.go
@@ -105,9 +105,9 @@ func TestEitherValue_BothTypesFailValidation(t *testing.T) {
foundTypeMismatchError := false
for _, validationErr := range validationErrs {
errStr := validationErr.Error()
- // Check for type mismatch patterns like "expected X, got Y"
- if (strings.Contains(errStr, "expected string") || strings.Contains(errStr, "expected bool")) &&
- strings.Contains(errStr, "got sequence") {
+ // Check for type mismatch patterns like "expected `X`, got `Y`"
+ if (strings.Contains(errStr, "expected `string`") || strings.Contains(errStr, "expected `bool`")) &&
+ strings.Contains(errStr, "got `sequence`") {
foundTypeMismatchError = true
break
}
@@ -222,7 +222,7 @@ func TestEitherValue_SyncChanges_Error(t *testing.T) {
name: "non-struct model",
model: "not a struct",
expectError: true,
- errorMsg: "expected struct, got string",
+ errorMsg: "expected `struct`, got `string`",
},
{
name: "both left and right nil",
@@ -349,22 +349,22 @@ func TestHasTypeMismatchErrors_Success(t *testing.T) {
{
name: "contains type mismatch error",
errors: []error{
- validation.NewValidationError(validation.NewTypeMismatchError("", "expected string but got number"), nil),
+ validation.NewTypeMismatchError("", "expected string but got number"),
},
expected: true,
},
{
name: "contains type mismatch error with parent name",
errors: []error{
- validation.NewValidationError(validation.NewTypeMismatchError("", "expected object but received array"), nil),
+ validation.NewTypeMismatchError("", "expected object but received array"),
},
expected: true,
},
{
name: "no type mismatch errors",
errors: []error{
- validation.NewValidationError(validation.NewValueValidationError("some other validation error"), nil),
- validation.NewValidationError(validation.NewMissingFieldError("missing required field"), nil),
+ errors.New("some other validation error"),
+ errors.New("missing required field"),
},
expected: false,
},
diff --git a/walk/locations.go b/walk/locations.go
index 9f9df2cc..43be5de0 100644
--- a/walk/locations.go
+++ b/walk/locations.go
@@ -50,3 +50,34 @@ func (l Locations[T]) ToJSONPointer() jsonpointer.JSONPointer {
return jsonpointer.JSONPointer(sb.String())
}
+
+// IsParent checks if the immediate parent field matches the given field name.
+// It handles both direct struct fields and map/slice items.
+func (l Locations[T]) IsParent(field string) bool {
+ if len(l) == 0 {
+ return false
+ }
+
+ last := l[len(l)-1]
+ if last.ParentKey != nil || last.ParentIndex != nil {
+ if len(l) < 2 {
+ return false
+ }
+ return l[len(l)-2].ParentField == field
+ }
+
+ return last.ParentField == field
+}
+
+// ParentKey returns the key of the current item if it is in a map.
+// Returns empty string if not in a map or key is nil.
+func (l Locations[T]) ParentKey() string {
+ if len(l) == 0 {
+ return ""
+ }
+ last := l[len(l)-1]
+ if last.ParentKey != nil {
+ return *last.ParentKey
+ }
+ return ""
+}
diff --git a/walk/locations_test.go b/walk/locations_test.go
new file mode 100644
index 00000000..6fa289a0
--- /dev/null
+++ b/walk/locations_test.go
@@ -0,0 +1,164 @@
+package walk_test
+
+import (
+ "testing"
+
+ "github.com/speakeasy-api/openapi/pointer"
+ "github.com/speakeasy-api/openapi/walk"
+ "github.com/stretchr/testify/assert"
+)
+
+func TestLocations_IsParent_Success(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ locations walk.Locations[string]
+ field string
+ expected bool
+ }{
+ {
+ name: "empty locations returns false",
+ locations: walk.Locations[string]{},
+ field: "anything",
+ expected: false,
+ },
+ {
+ name: "last entry matches field directly",
+ locations: walk.Locations[string]{
+ {ParentField: "paths"},
+ {ParentField: "responses"},
+ },
+ field: "responses",
+ expected: true,
+ },
+ {
+ name: "last entry does not match field",
+ locations: walk.Locations[string]{
+ {ParentField: "paths"},
+ {ParentField: "responses"},
+ },
+ field: "schemas",
+ expected: false,
+ },
+ {
+ name: "last entry has parent key so checks second to last",
+ locations: walk.Locations[string]{
+ {ParentField: "paths"},
+ {ParentField: "responses"},
+ {ParentKey: pointer.From("200")},
+ },
+ field: "responses",
+ expected: true,
+ },
+ {
+ name: "last entry has parent index so checks second to last",
+ locations: walk.Locations[string]{
+ {ParentField: "paths"},
+ {ParentField: "tags"},
+ {ParentIndex: pointer.From(0)},
+ },
+ field: "tags",
+ expected: true,
+ },
+ {
+ name: "last entry has parent key but second to last does not match",
+ locations: walk.Locations[string]{
+ {ParentField: "paths"},
+ {ParentField: "responses"},
+ {ParentKey: pointer.From("200")},
+ },
+ field: "schemas",
+ expected: false,
+ },
+ {
+ name: "single entry with parent key returns false (no second to last)",
+ locations: walk.Locations[string]{
+ {ParentKey: pointer.From("key")},
+ },
+ field: "anything",
+ expected: false,
+ },
+ {
+ name: "single entry with parent index returns false (no second to last)",
+ locations: walk.Locations[string]{
+ {ParentIndex: pointer.From(0)},
+ },
+ field: "anything",
+ expected: false,
+ },
+ {
+ name: "single entry matches field directly",
+ locations: walk.Locations[string]{
+ {ParentField: "paths"},
+ },
+ field: "paths",
+ expected: true,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+
+ result := tt.locations.IsParent(tt.field)
+ assert.Equal(t, tt.expected, result, "IsParent result should match expected")
+ })
+ }
+}
+
+func TestLocations_ParentKey_Success(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ locations walk.Locations[string]
+ expected string
+ }{
+ {
+ name: "empty locations returns empty string",
+ locations: walk.Locations[string]{},
+ expected: "",
+ },
+ {
+ name: "last entry has parent key",
+ locations: walk.Locations[string]{
+ {ParentField: "paths"},
+ {ParentKey: pointer.From("/users")},
+ },
+ expected: "/users",
+ },
+ {
+ name: "last entry has no parent key",
+ locations: walk.Locations[string]{
+ {ParentField: "paths"},
+ {ParentField: "responses"},
+ },
+ expected: "",
+ },
+ {
+ name: "single entry with parent key",
+ locations: walk.Locations[string]{
+ {ParentKey: pointer.From("myKey")},
+ },
+ expected: "myKey",
+ },
+ {
+ name: "last entry has parent index but no key",
+ locations: walk.Locations[string]{
+ {ParentField: "tags"},
+ {ParentIndex: pointer.From(3)},
+ },
+ expected: "",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+
+ result := tt.locations.ParentKey()
+ assert.Equal(t, tt.expected, result, "ParentKey result should match expected")
+ })
+ }
+}