@JsonIgnoreProperties has 0% compliance despite rule existing — needs cross-rule reinforcement + global fallback

[jaydestro]

Summary

The model-json-serialization rule (Rule 5) instructs agents to add @JsonIgnoreProperties(ignoreUnknown = true) on all entity classes to prevent UnrecognizedPropertyException when Cosmos DB system properties (_rid, _self, _etag, _ts, _attachments) appear in deserialized documents. Despite this rule being filed as #28 and fixed via PR #45 before Version B, zero out of 34 code-producing runs across all three evaluation versions follow it.

The root cause is not a missing rule — the rule exists. The problem is that agents read sdk-spring-data-annotations when generating entity classes (100% read rate for AK profiles) but do not cross-reference model-json-serialization for deserialization safety. The annotation must appear in the code examples agents actually copy.

Evidence

Current Rule Location (not read during entity generation)

The @JsonIgnoreProperties guidance lives in model-json-serialization Rule 5. Agents read this rule 0% of the time when generating entity classes — they read sdk-spring-data-annotations instead.

What Agents Generate (100% of runs)

@Container(containerName = "players")
public class PlayerProfile {
    @Id
    private String id;

    @PartitionKey
    private String playerId;

    private String displayName;
    private long bestScore;
    private int totalGamesPlayed;
    private double averageScore;
    // ... no @JsonIgnoreProperties
}

What Should Be Generated

import com.fasterxml.jackson.annotation.JsonIgnoreProperties;

@JsonIgnoreProperties(ignoreUnknown = true)  // ← Prevents failure on _rid, _self, _etag, _ts
@Container(containerName = "players")
public class PlayerProfile {
    @Id
    private String id;

    @PartitionKey
    private String playerId;

    private String displayName;
    private long bestScore;
    private int totalGamesPlayed;
    private double averageScore;
}

Compliance Across Versions

Version	Runs Analyzed	Runs with @JsonIgnoreProperties	Compliance
V-A	34	0	0%
V-B	34	0	0%
V-C	34	0	0%
Total	102	0	0%

This is the single most persistent anti-pattern in the entire SCOPE Java Gaming Leaderboard evaluation.

Root Cause Analysis

1. Rule isolation: model-json-serialization is in the "Data Modeling" category (category 1). Entity annotation guidance (@Container, @PartitionKey, @Id) is in sdk-spring-data-annotations (category 4). Agents read category 4 when writing entities but don't cross-reference category 1 for serialization safety.

2. Code example gap: The sdk-spring-data-annotations rule shows correct usage of @Container, @PartitionKey, @Id, and @GeneratedValue — but none of its code examples include @JsonIgnoreProperties. Since agents pattern-match against code examples, they produce exactly what the examples show.

3. No global fallback: Spring Boot can disable unknown-property failures globally via application.yml, but neither sdk-java-cosmos-config nor sdk-local-dev-config mention this.

Recommended Fix

Fix 1: Add @JsonIgnoreProperties to sdk-spring-data-annotations code examples

Every entity code example in this rule should include the annotation. This is where agents look when writing entities — if the annotation is in the template they copy, they'll include it.

Current incorrect example in rule:

@Container(containerName = "orders")
public class Order {
    @Id
    @GeneratedValue
    private String id;

    @PartitionKey
    private String customerId;
    // ...
}

Proposed corrected example:

@JsonIgnoreProperties(ignoreUnknown = true)
@Container(containerName = "orders")
public class Order {
    @Id
    @GeneratedValue
    private String id;

    @PartitionKey
    private String customerId;
    // ...
}

Fix 2: Add global Jackson fallback to sdk-java-cosmos-config

Add a section to sdk-java-cosmos-config (or sdk-local-dev-config) recommending the global Spring Boot property as defense-in-depth:

spring:
  jackson:
    deserialization:
      fail-on-unknown-properties: false

This single line covers all entities without requiring per-class annotations. Even if agents forget @JsonIgnoreProperties on individual classes, the application won't fail when Cosmos DB documents contain system properties.

Why Both Fixes

• Fix 1 addresses the root cause (agents copy from the wrong rule's examples)
• Fix 2 provides a safety net (global config catches any entity that slips through)
• Together they make the anti-pattern impossible — the annotation appears naturally in generated code AND the app is configured to tolerate unknown properties globally

Impact

• Without Fix 1: Agents will continue to produce entities without @JsonIgnoreProperties (100% failure rate proven across 102 runs)
• Without Fix 2: Even with Fix 1, any entity the agent generates without reading the rule (e.g., DTOs, inner classes) will still be vulnerable
• With both: The anti-pattern is eliminated at both the entity level and the application level

Cross-Reference

• Original issue: Java Gaming Leaderboard — Missing @JsonIgnoreProperties(ignoreUnknown = true) — Change Feed fails on system metadata in 94% of runs (all profiles) #28 — filed the model-json-serialization rule enhancement
• Original fix: PR Add Rule 5: handle Cosmos DB system metadata fields in Java deserialization #45 — added Rule 5 to model-json-serialization
• This issue: Addresses WHY the fix had 0% effect — the rule is in the wrong place for agent code generation workflows

References

• Jackson @JsonIgnoreProperties Javadoc: https://fasterxml.github.io/jackson-annotations/javadoc/2.13/com/fasterxml/jackson/annotation/JsonIgnoreProperties.html
• Spring Boot Jackson configuration: https://docs.spring.io/spring-boot/docs/current/reference/html/application-properties.html#application-properties.json.spring.jackson.deserialization
• Spring Data Cosmos entity requirements: https://learn.microsoft.com/java/api/overview/azure/spring-data-cosmos-readme

[sajeetharan]

Thanks for the detailed report, this is valid and now fixed. We reinforced @JsonIgnoreProperties(ignoreUnknown = true) directly in sdk-spring-data-annotations code examples (where entity templates are typically generated), and added a global Spring Boot Jackson fallback (spring.jackson.deserialization.fail-on-unknown-properties=false) to sdk-java-cosmos-config as defense in depth