issues

type Issue struct {
	// Path is the JSON path to the problematic field (e.g., "paths./pets.get.responses")
	Path string
	// Message is a human-readable description of the issue
	Message string
	// Severity indicates the severity level of the issue
	Severity severity.Severity
	// Field is the specific field name that has the issue
	Field string
	// Value is the problematic value (optional)
	Value any
	// SpecRef is the URL to the relevant section of the OAS specification (optional, validation use)
	SpecRef string
	// Context provides additional information about the issue (optional, conversion use)
	Context string
	// Line is the 1-based line number in the source file (0 if unknown)
	Line int
	// Column is the 1-based column number in the source file (0 if unknown)
	Column int
	// File is the source file path (empty for main document)
	File string
	// OperationContext provides API operation context when the issue relates to
	// an operation or a component referenced by operations. Nil when not applicable.
	OperationContext *OperationContext
}

type OperationContext struct {
	// Method is the HTTP method (GET, POST, etc.) - empty for path-level issues
	Method string
	// Path is the API path pattern (e.g., "/users/{id}") or webhook name
	Path string
	// OperationID is the operationId if defined (may be empty)
	OperationID string
	// IsReusableComponent is true when the issue is in components/definitions
	IsReusableComponent bool
	// IsWebhook is true when the issue is in a webhook operation
	IsWebhook bool
	// AdditionalRefs is the count of other operations referencing this component.
	// Only relevant when IsReusableComponent is true.
	// -1 indicates the component is unused (not referenced by any operation).
	AdditionalRefs int
}