v0.16.2

README.md

@@ -90,6 +90,16 @@ like our _very kind_ sponsors:
 
 [scalar](https://scalar.com)
 
+<a href="https://apideck.com">
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset=".github/sponsors/apideck-dark.png">
+  <img alt="apideck'" src=".github/sponsors/apideck-light.png">
+</picture>
+</a>
+
+[apideck](https://apideck.com)
+
+
 ---
 
 ## Come chat with us

cmd/bundle.go

@@ -41,6 +41,7 @@ func GetBundleCommand() *cobra.Command {
 			noStyleFlag, _ := cmd.Flags().GetBool("no-style")
 			baseFlag, _ := cmd.Flags().GetString("base")
 			remoteFlag, _ := cmd.Flags().GetBool("remote")
+			extensionRefsFlag, _ := cmd.Flags().GetBool("ext-refs")
 
 			// disable color and styling, for CI/CD use.
 			// https://github.com/daveshanley/vacuum/issues/234
@@ -115,6 +116,7 @@ func GetBundleCommand() *cobra.Command {
 				ExtractRefsSequentially: true,
 				Logger:                  logger,
 				AllowRemoteReferences:   remoteFlag,
+				ExcludeExtensionRefs:    extensionRefsFlag,
 			}
 
 			bundled, err := bundler.BundleBytes(specBytes, docConfig)

cmd/dashboard.go

@@ -45,6 +45,7 @@ func GetDashboardCommand() *cobra.Command {
 			timeoutFlag, _ := cmd.Flags().GetInt("timeout")
 			hardModeFlag, _ := cmd.Flags().GetBool("hard-mode")
 			silent, _ := cmd.Flags().GetBool("silent")
+			extensionRefsFlag, _ := cmd.Flags().GetBool("ext-refs")
 
 			var err error
 			vacuumReport, specBytes, _ := vacuum_report.BuildVacuumReportFromFile(args[0])
@@ -102,6 +103,10 @@ func GetDashboardCommand() *cobra.Command {
 					config.AllowRemoteLookup = true
 				}
 
+				if extensionRefsFlag {
+					config.ExcludeExtensionRefs = true
+				}
+
 				specIndex = index.NewSpecIndexWithConfig(&rootNode, config)
 
 				specInfo = vacuumReport.SpecInfo

cmd/language_server.go

@@ -41,6 +41,7 @@ IDE and start linting your OpenAPI documents in real-time.`,
 			hardModeFlag, _ := cmd.Flags().GetBool("hard-mode")
 			ignoreArrayCircleRef, _ := cmd.Flags().GetBool("ignore-array-circle-ref")
 			ignorePolymorphCircleRef, _ := cmd.Flags().GetBool("ignore-array-circle-ref")
+			extensionRefsFlag, _ := cmd.Flags().GetBool("ext-refs")
 
 			defaultRuleSets := rulesets.BuildDefaultRuleSetsWithLogger(logger)
 			selectedRS := defaultRuleSets.GenerateOpenAPIRecommendedRuleSet()
@@ -81,6 +82,7 @@ IDE and start linting your OpenAPI documents in real-time.`,
 				IgnoreArrayCircleRef:     ignoreArrayCircleRef,
 				IgnorePolymorphCircleRef: ignorePolymorphCircleRef,
 				Logger:                   logger,
+				ExtensionRefs:            extensionRefsFlag,
 			}
 
 			return languageserver.NewServer(Version, &lfr).Run()

cmd/lint.go

@@ -61,6 +61,7 @@ func GetLintCommand() *cobra.Command {
 			timeoutFlag, _ := cmd.Flags().GetInt("timeout")
 			hardModeFlag, _ := cmd.Flags().GetBool("hard-mode")
 			noClipFlag, _ := cmd.Flags().GetBool("no-clip")
+			extensionRefsFlag, _ := cmd.Flags().GetBool("ext-refs")
 			ignoreArrayCircleRef, _ := cmd.Flags().GetBool("ignore-array-circle-ref")
 			ignorePolymorphCircleRef, _ := cmd.Flags().GetBool("ignore-polymorph-circle-ref")
 			ignoreFile, _ := cmd.Flags().GetString("ignore-file")
@@ -238,6 +239,7 @@ func GetLintCommand() *cobra.Command {
 						IgnoreArrayCircleRef:     ignoreArrayCircleRef,
 						IgnorePolymorphCircleRef: ignorePolymorphCircleRef,
 						IgnoredResults:           ignoredItems,
+						ExtensionRefs:            extensionRefsFlag,
 					}
 					fs, fp, err := lintFile(lfr)
 
@@ -338,18 +340,19 @@ func lintFile(req utils.LintFileRequest) (int64, int, error) {
 	}
 
 	result := motor.ApplyRulesToRuleSet(&motor.RuleSetExecution{
-		RuleSet:                      req.SelectedRS,
-		Spec:                         specBytes,
-		SpecFileName:                 req.FileName,
-		CustomFunctions:              req.Functions,
-		Base:                         req.BaseFlag,
-		AllowLookup:                  req.Remote,
-		SkipDocumentCheck:            req.SkipCheckFlag,
-		Logger:                       req.Logger,
-		BuildDeepGraph:               deepGraph,
-		Timeout:                      time.Duration(req.TimeoutFlag) * time.Second,
-		IgnoreCircularArrayRef:       req.IgnoreArrayCircleRef,
-		IgnoreCircularPolymorphicRef: req.IgnorePolymorphCircleRef,
+		RuleSet:                         req.SelectedRS,
+		Spec:                            specBytes,
+		SpecFileName:                    req.FileName,
+		CustomFunctions:                 req.Functions,
+		Base:                            req.BaseFlag,
+		AllowLookup:                     req.Remote,
+		SkipDocumentCheck:               req.SkipCheckFlag,
+		Logger:                          req.Logger,
+		BuildDeepGraph:                  deepGraph,
+		Timeout:                         time.Duration(req.TimeoutFlag) * time.Second,
+		IgnoreCircularArrayRef:          req.IgnoreArrayCircleRef,
+		IgnoreCircularPolymorphicRef:    req.IgnorePolymorphCircleRef,
+		ExtractReferencesFromExtensions: req.ExtensionRefs,
 	})
 
 	result.Results = filterIgnoredResults(result.Results, req.IgnoredResults)

cmd/root.go

@@ -64,6 +64,7 @@ func GetRootCommand() *cobra.Command {
 	rootCmd.PersistentFlags().BoolP("debug", "w", false, "Turn on debug logging")
 	rootCmd.PersistentFlags().IntP("timeout", "g", 5, "Rule timeout in seconds, default is 5 seconds")
 	rootCmd.PersistentFlags().BoolP("hard-mode", "z", false, "Enable all the built-in rules, even the OWASP ones. This is the level to beat!")
+	rootCmd.PersistentFlags().BoolP("ext-refs", "", false, "Turn on $ref lookups and resolving for extensions (x-) objects")
 
 	if regErr := rootCmd.RegisterFlagCompletionFunc("functions", cobra.FixedCompletions(
 		[]string{"so"}, cobra.ShellCompDirectiveFilterFileExt,

cmd/spectral_report.go

@@ -46,6 +46,7 @@ func GetSpectralReportCommand() *cobra.Command {
 			skipCheckFlag, _ := cmd.Flags().GetBool("skip-check")
 			timeoutFlag, _ := cmd.Flags().GetInt("timeout")
 			hardModeFlag, _ := cmd.Flags().GetBool("hard-mode")
+			extensionRefsFlag, _ := cmd.Flags().GetBool("ext-refs")
 
 			// disable color and styling, for CI/CD use.
 			// https://github.com/daveshanley/vacuum/issues/234
@@ -151,13 +152,14 @@ func GetSpectralReportCommand() *cobra.Command {
 			}
 
 			ruleset := motor.ApplyRulesToRuleSet(&motor.RuleSetExecution{
-				RuleSet:           selectedRS,
-				Spec:              specBytes,
-				CustomFunctions:   customFunctions,
-				SilenceLogs:       true,
-				Base:              baseFlag,
-				SkipDocumentCheck: skipCheckFlag,
-				Timeout:           time.Duration(timeoutFlag) * time.Second,
+				RuleSet:                         selectedRS,
+				Spec:                            specBytes,
+				CustomFunctions:                 customFunctions,
+				SilenceLogs:                     true,
+				Base:                            baseFlag,
+				SkipDocumentCheck:               skipCheckFlag,
+				Timeout:                         time.Duration(timeoutFlag) * time.Second,
+				ExtractReferencesFromExtensions: extensionRefsFlag,
 			})
 
 			resultSet := model.NewRuleResultSet(ruleset.Results)

cmd/vacuum_report.go

@@ -48,6 +48,7 @@ func GetVacuumReportCommand() *cobra.Command {
 			timeoutFlag, _ := cmd.Flags().GetInt("timeout")
 			hardModeFlag, _ := cmd.Flags().GetBool("hard-mode")
 			ignoreFile, _ := cmd.Flags().GetString("ignore-file")
+			extensionRefsFlag, _ := cmd.Flags().GetBool("ext-refs")
 
 			// disable color and styling, for CI/CD use.
 			// https://github.com/daveshanley/vacuum/issues/234
@@ -172,14 +173,15 @@ func GetVacuumReportCommand() *cobra.Command {
 			}
 
 			ruleset := motor.ApplyRulesToRuleSet(&motor.RuleSetExecution{
-				RuleSet:           selectedRS,
-				Spec:              specBytes,
-				CustomFunctions:   customFunctions,
-				SilenceLogs:       true,
-				Base:              baseFlag,
-				SkipDocumentCheck: skipCheckFlag,
-				BuildDeepGraph:    deepGraph,
-				Timeout:           time.Duration(timeoutFlag) * time.Second,
+				RuleSet:                         selectedRS,
+				Spec:                            specBytes,
+				CustomFunctions:                 customFunctions,
+				SilenceLogs:                     true,
+				Base:                            baseFlag,
+				SkipDocumentCheck:               skipCheckFlag,
+				BuildDeepGraph:                  deepGraph,
+				Timeout:                         time.Duration(timeoutFlag) * time.Second,
+				ExtractReferencesFromExtensions: extensionRefsFlag,
 			})
 
 			resultSet := model.NewRuleResultSet(ruleset.Results)

functions/openapi/examples_missing.go

@@ -89,6 +89,11 @@ func (em ExamplesMissing) RunRule(_ []*yaml.Node, context model.RuleFunctionCont
 				continue
 			}
 
+			if (p.SchemaProxy != nil && p.SchemaProxy.Schema != nil && p.SchemaProxy.Schema.Value != nil) &&
+				(p.SchemaProxy.Schema.Value.Const != nil || p.SchemaProxy.Schema.Value.Default != nil) {
+				continue
+			}
+
 			if p.SchemaProxy != nil {
 				if len(p.SchemaProxy.Schema.Value.Type) <= 0 {
 					continue
@@ -159,6 +164,11 @@ func (em ExamplesMissing) RunRule(_ []*yaml.Node, context model.RuleFunctionCont
 				continue
 			}
 
+			if (h.Schema != nil && h.Schema.Schema != nil && h.Schema.Schema.Value != nil) &&
+				(h.Schema.Schema.Value.Const != nil || h.Schema.Schema.Value.Default != nil) {
+				continue
+			}
+
 			if h.Schema != nil {
 				if len(h.Schema.Schema.Value.Type) <= 0 {
 					continue
@@ -212,7 +222,43 @@ func (em ExamplesMissing) RunRule(_ []*yaml.Node, context model.RuleFunctionCont
 				continue
 			}
 
-			if mt.Value.Examples.Len() <= 0 && isExampleNodeNull([]*yaml.Node{mt.Value.Example}) {
+			if (mt.SchemaProxy != nil && mt.SchemaProxy.Schema != nil && mt.SchemaProxy.Schema.Value != nil) &&
+				(mt.SchemaProxy.Schema.Value.Const != nil || mt.SchemaProxy.Schema.Value.Default != nil) {
+				continue
+			}
+
+			propErr := false
+			hasProps := false
+			if mt.SchemaProxy != nil && mt.SchemaProxy.Schema.Properties != nil && mt.SchemaProxy.Schema.Properties.Len() > 0 {
+				hasProps = true
+				var prop *base.Schema
+				var propName string
+				for k, v := range mt.SchemaProxy.Schema.Properties.FromOldest() {
+					if !checkProps(v.Schema) {
+						propErr = true
+						prop = v.Schema
+						propName = k
+						break
+					}
+				}
+				if propErr {
+					path := prop.GenerateJSONPath()
+					results = append(results,
+						buildResult(vacuumUtils.SuppliedOrDefault(context.Rule.Message,
+							fmt.Sprintf("media type schema property `%s` is missing `examples` or `example`", propName)),
+							path,
+							prop.KeyNode, mt.ValueNode, mt))
+				}
+			}
+
+			buf.WriteString(fmt.Sprintf("%s:%d:%d", mt.Value.GoLow().GetIndex().GetSpecAbsolutePath(),
+				mt.Value.GoLow().KeyNode.Line, mt.Value.GoLow().KeyNode.Column))
+			if _, ok := seen[buf.String()]; !ok {
+				seen[buf.String()] = true
+			}
+			buf.Reset()
+
+			if hasProps && propErr && mt.Value.Examples.Len() <= 0 && isExampleNodeNull([]*yaml.Node{mt.Value.Example}) {
 
 				n := mt.Value.GoLow().RootNode
 				if mt.Value.GoLow().KeyNode != nil {
@@ -225,13 +271,23 @@ func (em ExamplesMissing) RunRule(_ []*yaml.Node, context model.RuleFunctionCont
 					buildResult(vacuumUtils.SuppliedOrDefault(context.Rule.Message, "media type is missing `examples` or `example`"),
 						path,
 						n, mt.ValueNode, mt))
-			} else {
-				buf.WriteString(fmt.Sprintf("%s:%d:%d", mt.Value.GoLow().GetIndex().GetSpecAbsolutePath(),
-					mt.Value.GoLow().KeyNode.Line, mt.Value.GoLow().KeyNode.Column))
-				if _, ok := seen[buf.String()]; !ok {
-					seen[buf.String()] = true
+				continue
+			}
+
+			if !hasProps && mt.Value.Examples.Len() <= 0 && isExampleNodeNull([]*yaml.Node{mt.Value.Example}) {
+
+				n := mt.Value.GoLow().RootNode
+				if mt.Value.GoLow().KeyNode != nil {
+					if mt.Value.GoLow().KeyNode.Line == n.Line-1 {
+						n = mt.Value.GoLow().KeyNode
+					}
 				}
-				buf.Reset()
+				path := mt.GenerateJSONPath()
+				results = append(results,
+					buildResult(vacuumUtils.SuppliedOrDefault(context.Rule.Message, "media type is missing `examples` or `example`"),
+						path,
+						n, mt.ValueNode, mt))
+				continue
 			}
 		}
 	}
@@ -243,12 +299,17 @@ func (em ExamplesMissing) RunRule(_ []*yaml.Node, context model.RuleFunctionCont
 				continue
 			}
 
+			if (s.Value != nil) &&
+				(s.Value.Const != nil || s.Value.Default != nil) {
+				continue
+			}
+
 			if len(s.Value.Type) <= 0 {
 				continue
 			}
 
 			if s.Value.Items != nil && s.Value.Items.IsA() && s.Value.Items.A != nil {
-				if len(s.Value.Items.A.Schema().Enum) > 0 {
+				if s.Value.Items.A.Schema() != nil && len(s.Value.Items.A.Schema().Enum) > 0 {
 					continue
 				}
 			}
@@ -267,12 +328,42 @@ func (em ExamplesMissing) RunRule(_ []*yaml.Node, context model.RuleFunctionCont
 				}
 			}
 
-			if isExampleNodeNull(s.Value.Examples) && isExampleNodeNull([]*yaml.Node{s.Value.Example}) {
+			propErr := false
+			hasProps := false
+			if s.Properties != nil && s.Properties.Len() > 0 {
+				hasProps = true
+				var prop *base.Schema
+				var propName string
+				for k, v := range s.Properties.FromOldest() {
+					if !checkProps(v.Schema) {
+						propErr = true
+						prop = v.Schema
+						propName = k
+						break
+					}
+				}
+				if propErr {
+					path := prop.GenerateJSONPath()
+					results = append(results,
+						buildResult(vacuumUtils.SuppliedOrDefault(context.Rule.Message,
+							fmt.Sprintf("schema property `%s` is missing `examples` or `example`", propName)),
+							path,
+							prop.KeyNode, s.ValueNode, s))
+				}
+			}
+
+			if hasProps && propErr && isExampleNodeNull(s.Value.Examples) && isExampleNodeNull([]*yaml.Node{s.Value.Example}) {
 				results = append(results,
 					buildResult(vacuumUtils.SuppliedOrDefault(context.Rule.Message, "schema is missing `examples` or `example`"),
 						s.GenerateJSONPath(),
 						s.Value.ParentProxy.GetSchemaKeyNode(), s.Value.ParentProxy.GetValueNode(), s))
+			}
 
+			if !hasProps && isExampleNodeNull(s.Value.Examples) && isExampleNodeNull([]*yaml.Node{s.Value.Example}) {
+				results = append(results,
+					buildResult(vacuumUtils.SuppliedOrDefault(context.Rule.Message, "schema is missing `examples` or `example`"),
+						s.GenerateJSONPath(),
+						s.Value.ParentProxy.GetSchemaKeyNode(), s.Value.ParentProxy.GetValueNode(), s))
 			}
 		}
 	}
@@ -281,6 +372,20 @@ func (em ExamplesMissing) RunRule(_ []*yaml.Node, context model.RuleFunctionCont
 	return results
 }
 
+func checkProps(s *base.Schema) bool {
+	if len(s.Value.Examples) > 0 {
+		return true
+	}
+	if s.Value.Example != nil {
+		return true
+	}
+	if s.Value.Properties != nil && s.Value.Properties.Len() > 0 {
+		for _, p := range s.Properties.FromOldest() {
+			return checkProps(p.Schema)
+		}
+	}
+	return false
+}
 func checkParent(s any, depth int) bool {
 	if depth > 10 {
 		return false

functions/openapi/examples_missing_test.go

@@ -56,7 +56,7 @@ paths:
 	def := ExamplesMissing{}
 	res := def.RunRule(nil, ctx)
 
-	assert.Len(t, res, 2)
+	assert.Len(t, res, 1)
 	assert.Equal(t, "media type is missing `examples` or `example`", res[0].Message)
 	assert.Contains(t, res[0].Path, "$.paths['/pizza'].get.requestBody.content['application/json']")
 }
@@ -178,8 +178,8 @@ components:
 	def := ExamplesMissing{}
 	res := def.RunRule(nil, ctx)
 
-	assert.Len(t, res, 1)
-	assert.Equal(t, "schema is missing `examples` or `example`", res[0].Message)
+	assert.Len(t, res, 2)
+	assert.Equal(t, "schema property `id` is missing `examples` or `example`", res[0].Message)
 	assert.Contains(t, res[0].Path, "$.components.schemas['Pizza']")
 }