Allow optional (non-required) field additions without unhandled error

[camilamacedo86]

Summary

Optional field additions = Safe, backward compatible, should be allowed

The current "unhandled" error is overly conservative - it blocks safe changes that don't break compatibility.

Example: Why Optional Field Additions Are Backward Compatible

Scenario: Example Operator Upgrade 1.6.3 → 1.7.0

What Changed

CRD: applications.example.com

Version 1.6.3:

spec:
  config:
    secrets:
      items:
        properties:
          key:
            type: string
            description: "Key in the object"
          name:
            type: string
            description: "Name of the object\nWe support only ConfigMaps and Secrets."

Version 1.7.0 (added optional field):

spec:
  config:
    secrets:
      items:
        properties:
          key:
            type: string
            description: "Key in the object"
          mountPath:  # ← NEW OPTIONAL FIELD
            type: string
            description: "Path to mount the Object. If not specified default-path/Name will be used"
          name:
            type: string
            description: "Name of the object\nSupported ConfigMaps and Secrets."  # ← Description updated

Why This Is Backward Compatible

1. Optional Fields Don't Break Existing Resources

Existing resource (from 1.6.3):

apiVersion: example.com/v1alpha1
kind: Application
spec:
  config:
    secrets:
      - key: "my-key"
        name: "my-secret"

Still valid in 1.7.0:

# Same resource works perfectly - mountPath is optional
apiVersion: example.com/v1alpha1
kind: Application
spec:
  config:
    secrets:
      - key: "my-key"
        name: "my-secret"
        # mountPath not required - defaults to default-path/Name

2. Kubernetes Schema Validation

• Optional fields = Not in required array
• Existing resources = Don't need to provide optional fields
• New resources = Can optionally use the new field

Current Problem

Error triggered:

unhandled: unhandled changes found :
  &v1.JSONSchemaProps{
    Properties: map[string]v1.JSONSchemaProps{
      "mountPath": {  # ← This is safe!
        Type: "string",
        Description: "Path to mount..."
      }
    }
  }

Why it's wrong:

• mountPath is not required (not in required array)
• Adding it doesn't break existing resources
• It's a safe, additive change

Expected Behavior

Should NOT error because:

1. ✅ Field is optional (not required)
2. ✅ Existing resources remain valid
3. ✅ New resources can optionally use it
4. ✅ No breaking changes

Should error only if:

• ❌ Field is added to required array (breaking)
• ❌ Field type changes (breaking)
• ❌ Existing fields removed (breaking)

[everettraven]

If this is happening on the latest version of crdify this definitely seems like a bug. IIRC we shouldn't be flagging new optional properties.

We even have an explicit test for this:

crdify/test/validchanges/b.yaml

Lines 60 to 84 in d37b2a3

	# New optional field with no restrictions
	animal:
	description: animal is the type of animal this instance represents
	type: string
	# New optional field with restrictions
	region:
	description: region in which this instance should be deployed
	type: string
	enum:
	- East
	- West
	# New optional field with required fields
	config:
	description: config is the custom configuration for this instance
	type: object
	properties:
	name:
	description: name is the name of the configmap holding the configuration
	type: string
	namespace:
	description: namespace is the namespace of the configmap holding the configuration
	type: string
	required:
	- name
	- namespace