` 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 0000000..53cc49e
--- /dev/null
+++ b/openapi/linter/rules/operation_singular_tag.go
@@ -0,0 +1,72 @@
+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) 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 0000000..9e720dd
--- /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 0000000..ef38e9c
--- /dev/null
+++ b/openapi/linter/rules/operation_success_response.go
@@ -0,0 +1,163 @@
+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) 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.GetCore().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.GetCore().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 0000000..81bedda
--- /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 0000000..6d5077b
--- /dev/null
+++ b/openapi/linter/rules/operation_tag_defined.go
@@ -0,0 +1,81 @@
+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) 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 0000000..afe71b1
--- /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 0000000..42d47f9
--- /dev/null
+++ b/openapi/linter/rules/operation_tags.go
@@ -0,0 +1,75 @@
+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) 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.GetCore().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 0000000..801fc7b
--- /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 0000000..0759e10
--- /dev/null
+++ b/openapi/linter/rules/owasp_additional_properties_constrained.go
@@ -0,0 +1,104 @@
+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) 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 0000000..b14c7b5
--- /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 0000000..67948e5
--- /dev/null
+++ b/openapi/linter/rules/owasp_array_limit.go
@@ -0,0 +1,79 @@
+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) 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 0000000..e2df7d6
--- /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 0000000..d583b0d
--- /dev/null
+++ b/openapi/linter/rules/owasp_auth_insecure_schemes.go
@@ -0,0 +1,91 @@
+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) 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 0000000..da282b7
--- /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 0000000..9c8f017
--- /dev/null
+++ b/openapi/linter/rules/owasp_define_error_responses_401.go
@@ -0,0 +1,118 @@
+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) 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 0000000..5e8ab6b
--- /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 0000000..20a430c
--- /dev/null
+++ b/openapi/linter/rules/owasp_define_error_responses_429.go
@@ -0,0 +1,118 @@
+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) 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 0000000..6e538c9
--- /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 0000000..e35563a
--- /dev/null
+++ b/openapi/linter/rules/owasp_define_error_responses_500.go
@@ -0,0 +1,118 @@
+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) 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 0000000..4955609
--- /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 0000000..b7cde85
--- /dev/null
+++ b/openapi/linter/rules/owasp_define_error_validation.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"
+)
+
+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) 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 0000000..8ab4243
--- /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 0000000..2e67b5d
--- /dev/null
+++ b/openapi/linter/rules/owasp_integer_format.go
@@ -0,0 +1,79 @@
+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) 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 0000000..f8fd501
--- /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 0000000..902c0b9
--- /dev/null
+++ b/openapi/linter/rules/owasp_integer_limit.go
@@ -0,0 +1,92 @@
+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) 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 0000000..8291dcb
--- /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 0000000..bbf1869
--- /dev/null
+++ b/openapi/linter/rules/owasp_jwt_best_practices.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"
+ "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) 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 0000000..3bc7b56
--- /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 0000000..b71f133
--- /dev/null
+++ b/openapi/linter/rules/owasp_no_additional_properties.go
@@ -0,0 +1,101 @@
+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) 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 0000000..651ec77
--- /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 0000000..fb8c927
--- /dev/null
+++ b/openapi/linter/rules/owasp_no_api_keys_in_url.go
@@ -0,0 +1,90 @@
+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) 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 0000000..ffcc8b8
--- /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 0000000..2751a0a
--- /dev/null
+++ b/openapi/linter/rules/owasp_no_credentials_in_url.go
@@ -0,0 +1,92 @@
+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) 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 both inline and component parameters
+ for _, paramNode := range docInfo.Index.InlineParameters {
+ checkParameter(paramNode)
+ }
+ for _, paramNode := range docInfo.Index.ComponentParameters {
+ 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 0000000..4251a14
--- /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 0000000..708aa39
--- /dev/null
+++ b/openapi/linter/rules/owasp_no_http_basic.go
@@ -0,0 +1,91 @@
+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) 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 0000000..fbfa8d7
--- /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 0000000..aae23cc
--- /dev/null
+++ b/openapi/linter/rules/owasp_no_numeric_ids.go
@@ -0,0 +1,151 @@
+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) 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 inline parameters
+ for _, paramNode := range docInfo.Index.InlineParameters {
+ 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
+ }
+ }
+ }
+
+ // Check component parameters
+ for _, paramNode := range docInfo.Index.ComponentParameters {
+ 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 0000000..efb8a7a
--- /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 0000000..776a9c2
--- /dev/null
+++ b/openapi/linter/rules/owasp_protection_global_safe.go
@@ -0,0 +1,109 @@
+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) 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 0000000..2f3186f
--- /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 0000000..311898d
--- /dev/null
+++ b/openapi/linter/rules/owasp_protection_global_unsafe.go
@@ -0,0 +1,109 @@
+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) 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 0000000..713ffa6
--- /dev/null
+++ b/openapi/linter/rules/owasp_protection_global_unsafe_strict.go
@@ -0,0 +1,95 @@
+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) 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 0000000..8661553
--- /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 0000000..5e19f5d
--- /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 0000000..d73ce96
--- /dev/null
+++ b/openapi/linter/rules/owasp_rate_limit.go
@@ -0,0 +1,131 @@
+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) 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 0000000..50fda25
--- /dev/null
+++ b/openapi/linter/rules/owasp_rate_limit_retry_after.go
@@ -0,0 +1,116 @@
+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) 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 0000000..50526e5
--- /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 0000000..b18eaa6
--- /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 0000000..6558607
--- /dev/null
+++ b/openapi/linter/rules/owasp_security_hosts_https_oas3.go
@@ -0,0 +1,79 @@
+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) 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 0000000..66a7370
--- /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 0000000..c43471d
--- /dev/null
+++ b/openapi/linter/rules/owasp_string_limit.go
@@ -0,0 +1,83 @@
+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) 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 0000000..1deaaba
--- /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 0000000..5fe9cfe
--- /dev/null
+++ b/openapi/linter/rules/owasp_string_restricted.go
@@ -0,0 +1,84 @@
+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) 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 0000000..8daf932
--- /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 0000000..acbf21b
--- /dev/null
+++ b/openapi/linter/rules/parameter_description.go
@@ -0,0 +1,101 @@
+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) 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.GetCore().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 0000000..f118d6d
--- /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 0000000..98eb164
--- /dev/null
+++ b/openapi/linter/rules/path_declarations.go
@@ -0,0 +1,52 @@
+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) 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 0000000..b8a663e
--- /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 0000000..c9962c7
--- /dev/null
+++ b/openapi/linter/rules/path_params.go
@@ -0,0 +1,180 @@
+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) 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.GetCore().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 %q is declared as path parameter but not used in path template %q", paramName, path),
+ op.GetCore().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.GetCore().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 0000000..b934f31
--- /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 0000000..f097afa
--- /dev/null
+++ b/openapi/linter/rules/path_query.go
@@ -0,0 +1,52 @@
+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) 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 0000000..252b24e
--- /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 0000000..9965ff8
--- /dev/null
+++ b/openapi/linter/rules/path_trailing_slash.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 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) 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 0000000..dd93c0a
--- /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 0000000..f553067
--- /dev/null
+++ b/openapi/linter/rules/paths_kebab_case.go
@@ -0,0 +1,99 @@
+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) 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 0000000..7c65125
--- /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/tag_description.go b/openapi/linter/rules/tag_description.go
new file mode 100644
index 0000000..13fb590
--- /dev/null
+++ b/openapi/linter/rules/tag_description.go
@@ -0,0 +1,72 @@
+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) 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.GetCore().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 0000000..353e1b5
--- /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 0000000..289346d
--- /dev/null
+++ b/openapi/linter/rules/tags_alphabetical.go
@@ -0,0 +1,86 @@
+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) 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.GetCore().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 0000000..b8941a5
--- /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 0000000..7a5e937
--- /dev/null
+++ b/openapi/linter/rules/typed_enum.go
@@ -0,0 +1,116 @@
+package rules
+
+import (
+ "context"
+ "fmt"
+
+ "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) 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
+
+ // 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) {
+ errs = append(errs, validation.NewSliceError(
+ config.GetSeverity(r.DefaultSeverity()),
+ RuleSemanticTypedEnum,
+ fmt.Errorf("enum value at index %d does not match schema type %v", i, schemaTypes),
+ schema.GetCore(),
+ schema.GetCore().Enum,
+ i,
+ ))
+ }
+ }
+ }
+
+ return errs
+}
+
+// isNodeMatchingType checks if a yaml.Node value matches the schema type
+func isNodeMatchingType(node *yaml.Node, schemaTypes []oas3.SchemaType) bool {
+ if node == nil || node.Kind == yaml.AliasNode {
+ // nil or alias nodes - check for null type
+ return containsType(schemaTypes, oas3.SchemaTypeNull)
+ }
+
+ // 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)
+ 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 0000000..fa6a193
--- /dev/null
+++ b/openapi/linter/rules/typed_enum_test.go
@@ -0,0 +1,278 @@
+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
+`,
+ },
+ }
+
+ 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]",
+ },
+ }
+
+ 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 0000000..9390359
--- /dev/null
+++ b/openapi/linter/rules/unused_components.go
@@ -0,0 +1,395 @@
+package rules
+
+import (
+ "context"
+ "fmt"
+ "strings"
+
+ "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) 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 {
+ 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 {
+ 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 {
+ 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 {
+ 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 {
+ 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 {
+ 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 {
+ 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 {
+ 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 {
+ 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 {
+ 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
+ }
+}
+
+// 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 0000000..f922555
--- /dev/null
+++ b/openapi/linter/rules/unused_components_test.go
@@ -0,0 +1,272 @@
+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_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 82e00f7..facc988 100644
--- a/openapi/localize.go
+++ b/openapi/localize.go
@@ -241,7 +241,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 +266,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 +320,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 +337,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,
}
diff --git a/openapi/mediatype.go b/openapi/mediatype.go
index 6cc46c9..c401849 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 03a66e3..0e796ce 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 eace23f..baded79 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/openapi.go b/openapi/openapi.go
index 0cb42c1..ff94289 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,145 @@ 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.GetCore().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
+}
+
+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{
+ Operation: func(op *Operation) error {
+ method, path := ExtractMethodAndPath(item.Location)
+ if method == "" || path == "" {
+ return nil
+ }
+
+ seen := make(map[string]bool)
+ parameters := op.GetParameters()
+ if len(parameters) == 0 {
+ return nil
+ }
+
+ for index, 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 = op.GetCore().GetRootNode()
+ }
+
+ err := validation.NewValidationError(
+ validation.SeverityError,
+ validation.RuleValidationOperationParameters,
+ fmt.Errorf("the `%s` operation parameter at path `%s`, index %d has a duplicate name `%s` and `in` type", strings.ToUpper(method), path, index, paramName),
+ errNode,
+ )
+ errs = append(errs, err)
+ }
+ seen[key] = true
+ }
+
+ 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 01565b0..f1a959e 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 b3ed5de..36a1628 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 f7bd670..dfc7538 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,57 @@ 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 the `GET` operation parameter at path `/users/{id}`, index 1 has a duplicate name `id` and `in` type"},
},
}
diff --git a/openapi/operation_validate_test.go b/openapi/operation_validate_test.go
index 92c878d..a5a3ebc 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 68304dc..73c76e9 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 84a1776..835c13f 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 1b59778..571f86b 100644
--- a/openapi/paths.go
+++ b/openapi/paths.go
@@ -2,6 +2,7 @@ package openapi
import (
"context"
+ "fmt"
"slices"
"strings"
@@ -102,6 +103,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 +321,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 30461c2..37cbab5 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 c4b4c64..ec5d7c2 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 4468ff5..87e74cb 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 0756000..0981296 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 0a57163..9d220a1 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 0071462..b2065bd 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 2a44a5f..0c8b7f0 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/security.go b/openapi/security.go
index 82d7715..6a8c472 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,47 @@ 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))
}
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))
}
}
}
@@ -302,7 +303,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 +499,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 306ae1f..c25868c 100644
--- a/openapi/security_validate_test.go
+++ b/openapi/security_validate_test.go
@@ -160,7 +160,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",
diff --git a/openapi/server.go b/openapi/server.go
index 83789bd..cf802ec 100644
--- a/openapi/server.go
+++ b/openapi/server.go
@@ -87,16 +87,16 @@ 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))
+ 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 +157,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.Enum))
}
}
diff --git a/openapi/server_validate_test.go b/openapi/server_validate_test.go
index 6ed7267..e9d27ea 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{"[7:7] error validation-allowed-values serverVariable.default must be one of [staging, development]"},
},
{
name: "multiple validation errors",
@@ -164,8 +164,8 @@ 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",
},
},
}
@@ -280,7 +280,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 +288,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 +299,7 @@ enum:
- valid2
description: Variable with invalid default
`,
- wantErrs: []string{"[4:3] serverVariable.default must be one of [valid1, valid2]"},
+ wantErrs: []string{"[4:3] error validation-allowed-values serverVariable.default must be one of [valid1, valid2]"},
},
}
diff --git a/openapi/tag.go b/openapi/tag.go
index bba656f..5621c87 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 95a5a22..7071486 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",
},
},
}
diff --git a/openapi/testdata/bundle/issue50/expected.yaml b/openapi/testdata/bundle/issue50/expected.yaml
index 1ed2658..e3dc9d5 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 cf9b92a..35a7c43 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 f5e7615..2824f37 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/overlay/README.md b/overlay/README.md
index 44e70e4..6a005f3 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/references/resolution.go b/references/resolution.go
index 3906fd1..ab8f458 100644
--- a/references/resolution.go
+++ b/references/resolution.go
@@ -53,8 +53,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 +105,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 +121,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 +137,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 +183,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 +198,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)
diff --git a/references/resolution_test.go b/references/resolution_test.go
index ea4a27b..8a128cf 100644
--- a/references/resolution_test.go
+++ b/references/resolution_test.go
@@ -392,7 +392,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 +788,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 +838,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 +878,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 +920,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 +953,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 d95f5fb..434fb88 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 c85c8be..f3d1884 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 80b864e..e22f58e 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 f12c20f..9176a10 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 90cb167..869a42d 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/parameter.go b/swagger/parameter.go
index 0dc4600..428978f 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 ef50b23..5f67539 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",
@@ -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",
@@ -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 47e1016..32dc497 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 baea119..81e27ee 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 4c8292f..da25baf 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 56fa886..2c949b1 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 4da59fd..e6be544 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",
diff --git a/swagger/swagger.go b/swagger/swagger.go
index 9e1f86d..d7d3eb0 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 e63c8d3..72879a8 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 is required",
},
{
name: "missing info field",
yaml: `swagger: "2.0"
paths: {}`,
- expectedError: "info is missing",
+ expectedError: "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: "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/tag.go b/swagger/tag.go
index 60b6aba..07012ad 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 e3bf4a7..e7e4010 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 447757f..d3ff660 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 0000000..2a05175
--- /dev/null
+++ b/validation/rules.go
@@ -0,0 +1,23 @@
+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"
+)
diff --git a/validation/utils_test.go b/validation/utils_test.go
index 7b42dee..9e9c2a3 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 ce7cf5b..4f3df6c 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,54 @@ 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
- expected string
+ err *Error
+ expected Severity
}{
{
- name: "simple validation error",
- msg: "invalid value",
- args: nil,
- expected: "invalid value",
+ name: "error severity",
+ err: &Error{
+ UnderlyingError: errors.New("test error"),
+ Severity: SeverityError,
+ },
+ expected: SeverityError,
},
{
- 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: "warning severity",
+ err: &Error{
+ UnderlyingError: errors.New("test warning"),
+ Severity: SeverityWarning,
+ },
+ expected: SeverityWarning,
},
{
- name: "validation error with no args but formatting placeholders",
- msg: "value %s is invalid",
- args: []any{},
- expected: "value %s is invalid",
+ name: "hint severity",
+ err: &Error{
+ UnderlyingError: errors.New("test hint"),
+ Severity: SeverityHint,
+ },
+ expected: SeverityHint,
},
}
@@ -575,9 +616,52 @@ 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)
+ result := tt.err.GetSeverity()
+ assert.Equal(t, tt.expected, result, "severity 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: "with parent name and formatting",
+ parentName: "Schema",
+ msg: "expected %s, got %s",
+ args: []any{"string", "int"},
+ expected: "Schema expected string, got int",
+ },
+ {
+ name: "empty parent name",
+ parentName: "",
+ msg: "standalone error",
+ args: nil,
+ expected: "standalone error",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+
+ 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 e55a87d..90e1c29 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...)
@@ -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 b4fb751..65afd6e 100644
--- a/values/core/eithervalue_test.go
+++ b/values/core/eithervalue_test.go
@@ -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 9f9df2c..43be5de 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 ""
+}