Enable instance annotations for null value nested resource or without value nested resource (#3461)

* Fixes #3440: Enable instance annotations for null value nested resource

* Fiexes the failing test

Author: xuzhg

src/Microsoft.OData.Core/Json/ODataJsonPropertyAndValueDeserializer.cs

@@ -524,11 +524,13 @@ protected ODataJsonReaderNestedResourceInfo InnerReadUndeclaredProperty(IODataJs
                 ValidateExpandedNestedResourceInfoPropertyValue(this.JsonReader, isCollection, propertyName, payloadTypeReference);
                 if (isCollection)
                 {
+                    // Sam: Unclear that since it's an undeclared property, why call 'ReadExpandedResourceSetNestedResourceInfo' to tread it as navigation property, not call 'ReadNonExpandedResourceSetNestedResourceInfo'?
                     readerNestedResourceInfo =
-                        ReadExpandedResourceSetNestedResourceInfo(resourceState, null, payloadTypeReference.ToStructuredType(), propertyName, /*isDeltaResourceSet*/ false);
+                        ReadExpandedResourceSetNestedResourceInfo(resourceState, null, payloadTypeReference.ToStructuredType(), propertyName, isDeltaResourceSet: false, this.MessageReaderSettings);
                 }
                 else
                 {
+                    // Sam: Unclear that since it's an undeclared property, why call 'ReadExpandedResourceNestedResourceInfo' to tread it as navigation property, not call 'ReadNonExpandedResourceNestedResourceInfo'?
                     readerNestedResourceInfo = ReadExpandedResourceNestedResourceInfo(resourceState, null, propertyName, payloadTypeReference.ToStructuredType(), this.MessageReaderSettings);
                 }
 
@@ -606,7 +608,7 @@ protected static void ValidateExpandedNestedResourceInfoPropertyValue(
         }
 
         /// <summary>
-        /// Reads non-expanded nested resource set.
+        /// Reads non-expanded (complex) nested resource set.
         /// </summary>
         /// <param name="resourceState">The state of the reader for resource to read.</param>
         /// <param name="collectionProperty">The collection of complex property for which to read the nested resource info. null for undeclared property.</param>
@@ -629,6 +631,8 @@ protected static ODataJsonReaderNestedResourceInfo ReadNonExpandedResourceSetNes
                 IsComplex = true
             };
 
+            AttachPropertyAnnotationsToNestedResourceInfo(resourceState, nestedResourceInfo);
+
             ODataResourceSet expandedResourceSet = CreateCollectionResourceSet(resourceState, propertyName);
             return ODataJsonReaderNestedResourceInfo.CreateResourceSetReaderNestedResourceInfo(nestedResourceInfo, collectionProperty, nestedResourceType, expandedResourceSet);
         }
@@ -656,13 +660,36 @@ protected static ODataJsonReaderNestedResourceInfo ReadNonExpandedResourceNested
                 IsComplex = true
             };
 
-            // Check the odata.type annotation for the complex property, it should show inside the complex object.
-            if (ValidateDataPropertyTypeNameAnnotation(resourceState.PropertyAndAnnotationCollector, nestedResourceInfo.Name) != null)
+            // Here's old logic: If a complex nested resource has `odata.type` property annotation, then throw exception, it says the annotation should be inside complex object.
+            // It doesn't make sense now since the complex nested resoruce value could be null , in that case the `odata.type` annotation has to be outside the complex object.
+            AttachPropertyAnnotationsToNestedResourceInfo(resourceState, nestedResourceInfo);
+
+            return ODataJsonReaderNestedResourceInfo.CreateResourceReaderNestedResourceInfo(nestedResourceInfo, complexProperty, nestedResourceType);
+        }
+
+        protected static void AttachPropertyAnnotationsToNestedResourceInfo(IODataJsonReaderResourceState resourceState, ODataNestedResourceInfo nestedResourceInfo)
+        {
+            Debug.Assert(resourceState != null, "resourceState != null");
+            Debug.Assert(nestedResourceInfo != null, "nestedResourceInfo != null");
+
+            foreach (KeyValuePair<string, object> odataAnnotation
+                    in resourceState.PropertyAndAnnotationCollector.GetODataPropertyAnnotations(nestedResourceInfo.Name))
             {
-                throw new ODataException(Error.Format(SRResources.ODataJsonPropertyAndValueDeserializer_ComplexValueWithPropertyTypeAnnotation, ODataAnnotationNames.ODataType));
+                if (string.Equals(odataAnnotation.Key, "odata.type", StringComparison.Ordinal)
+                    || string.Equals(odataAnnotation.Key, "type", StringComparison.Ordinal))
+                {
+                    nestedResourceInfo.TypeAnnotation = new ODataTypeAnnotation((string)odataAnnotation.Value);
+                }
+                else
+                {
+                    nestedResourceInfo.InstanceAnnotations.Add(new ODataInstanceAnnotation(odataAnnotation.Key, odataAnnotation.Value.ToODataValue(), true));
+                }
             }
 
-            return ODataJsonReaderNestedResourceInfo.CreateResourceReaderNestedResourceInfo(nestedResourceInfo, complexProperty, nestedResourceType);
+            foreach (KeyValuePair<string, object> instanceAnnotation in resourceState.PropertyAndAnnotationCollector.GetCustomPropertyAnnotations(nestedResourceInfo.Name))
+            {
+                nestedResourceInfo.InstanceAnnotations.Add(new ODataInstanceAnnotation(instanceAnnotation.Key, instanceAnnotation.Value.ToODataValue()));
+            }
         }
 
         /// <summary>
@@ -714,15 +741,27 @@ in resourceState.PropertyAndAnnotationCollector.GetODataPropertyAnnotations(nest
                         break;
 
                     default:
-                        if (messageReaderSettings.ThrowOnUndeclaredPropertyForNonOpenType)
+                        if (messageReaderSettings.ThrowOnUnexpectedODataPropertyAnnotationOnNavigationProperty)
                         {
                             throw new ODataException(Error.Format(SRResources.ODataJsonResourceDeserializer_UnexpectedExpandedSingletonNavigationLinkPropertyAnnotation, nestedResourceInfo.Name, propertyAnnotation.Key));
                         }
 
+                        // Let's save the property annotations into the nested resource info, therefore we can support the 'null' value nested resource as:
+                        // {
+                        //     "[email protected]" : "anyvalue",
+                        //     "NestedResource": null
+                        // }
+                        nestedResourceInfo.InstanceAnnotations.Add(new ODataInstanceAnnotation(propertyAnnotation.Key, propertyAnnotation.Value.ToODataValue(), true));
+
                         break;
                 }
             }
 
+            foreach (KeyValuePair<string, object> instanceAnnotation in resourceState.PropertyAndAnnotationCollector.GetCustomPropertyAnnotations(nestedResourceInfo.Name))
+            {
+                nestedResourceInfo.InstanceAnnotations.Add(new ODataInstanceAnnotation(instanceAnnotation.Key, instanceAnnotation.Value.ToODataValue()));
+            }
+
             return ODataJsonReaderNestedResourceInfo.CreateResourceReaderNestedResourceInfo(nestedResourceInfo, navigationProperty, propertyType);
         }
 
@@ -734,11 +773,13 @@ in resourceState.PropertyAndAnnotationCollector.GetODataPropertyAnnotations(nest
         /// <param name="propertyType">The type of the collection.</param>
         /// <param name="propertyName">The property name.</param>
         /// <param name="isDeltaResourceSet">The property being read represents a nested delta resource set.</param>
+        /// <param name="messageReaderSettings">The ODataMessageReaderSettings.</param>
         /// <returns>The nested resource info for the expanded link read.</returns>
         /// <remarks>
         /// This method doesn't move the reader.
         /// </remarks>
-        protected static ODataJsonReaderNestedResourceInfo ReadExpandedResourceSetNestedResourceInfo(IODataJsonReaderResourceState resourceState, IEdmNavigationProperty navigationProperty, IEdmStructuredType propertyType, string propertyName, bool isDeltaResourceSet)
+        protected static ODataJsonReaderNestedResourceInfo ReadExpandedResourceSetNestedResourceInfo(IODataJsonReaderResourceState resourceState, 
+            IEdmNavigationProperty navigationProperty, IEdmStructuredType propertyType, string propertyName, bool isDeltaResourceSet, ODataMessageReaderSettings messageReaderSettings)
         {
             Debug.Assert(resourceState != null, "resourceState != null");
             Debug.Assert(navigationProperty != null || propertyName != null, "navigationProperty != null || propertyName != null");
@@ -796,10 +837,21 @@ in resourceState.PropertyAndAnnotationCollector.GetODataPropertyAnnotations(nest
 
                     case ODataAnnotationNames.ODataDeltaLink:   // Delta links are not supported on expanded resource sets.
                     default:
-                        throw new ODataException(Error.Format(SRResources.ODataJsonResourceDeserializer_UnexpectedExpandedCollectionNavigationLinkPropertyAnnotation, nestedResourceInfo.Name, propertyAnnotation.Key));
+                        if (messageReaderSettings.ThrowOnUnexpectedODataPropertyAnnotationOnNavigationProperty)
+                        {
+                            throw new ODataException(Error.Format(SRResources.ODataJsonResourceDeserializer_UnexpectedExpandedCollectionNavigationLinkPropertyAnnotation, nestedResourceInfo.Name, propertyAnnotation.Key));
+                        }
+
+                        nestedResourceInfo.InstanceAnnotations.Add(new ODataInstanceAnnotation(propertyAnnotation.Key, propertyAnnotation.Value.ToODataValue(), true));
+                        break;
                 }
             }
 
+            foreach (KeyValuePair<string, object> instanceAnnotation in resourceState.PropertyAndAnnotationCollector.GetCustomPropertyAnnotations(nestedResourceInfo.Name))
+            {
+                nestedResourceInfo.InstanceAnnotations.Add(new ODataInstanceAnnotation(instanceAnnotation.Key, instanceAnnotation.Value.ToODataValue()));
+            }
+
             return ODataJsonReaderNestedResourceInfo.CreateResourceSetReaderNestedResourceInfo(nestedResourceInfo, navigationProperty, propertyType, expandedResourceSet);
         }
 
@@ -2338,7 +2390,7 @@ await ValidateExpandedNestedResourceInfoPropertyValueAsync(
                 if (isCollection)
                 {
                     readerNestedResourceInfo =
-                        ReadExpandedResourceSetNestedResourceInfo(resourceState, null, payloadTypeReference.ToStructuredType(), propertyName, isDeltaResourceSet: false);
+                        ReadExpandedResourceSetNestedResourceInfo(resourceState, null, payloadTypeReference.ToStructuredType(), propertyName, isDeltaResourceSet: false, this.MessageReaderSettings);
                 }
                 else
                 {

src/Microsoft.OData.Core/Json/ODataJsonReader.cs

@@ -1826,16 +1826,30 @@ private void ReadExpandedNestedResourceInfoStart(ODataNestedResourceInfo nestedR
 
                 // Expanded null resource
                 // The expected type and expected navigation source for an expanded resource are the same as for the nested resource info around it.
-                this.EnterScope(new JsonResourceScope(ODataReaderState.ResourceStart, /*resource*/ null,
-                    this.CurrentNavigationSource, this.CurrentResourceTypeReference, /*propertyAndAnnotationCollector*/null,
-                    /*projectedProperties*/null, this.CurrentScope.ODataUri));
+                this.EnterScope(new JsonResourceScope(ODataReaderState.ResourceStart, resource: null,
+                    navigationSource: this.CurrentNavigationSource, expectedResourceTypeReference: this.CurrentResourceTypeReference, propertyAndAnnotationCollector: null,
+                    selectedProperties: null, odataUri: this.CurrentScope.ODataUri));
             }
             else
             {
-                // Expanded resource
+                // Expanded resource, a JSON object
                 // The expected type for an expanded resource is the same as for the nested resource info around it.
                 JsonResourceBaseScope parentScope = (JsonResourceBaseScope)this.ParentScope;
                 SelectedPropertiesNode parentSelectedProperties = parentScope.SelectedProperties;
+
+                // OData spec says: When annotating a name/value pair for which the value is represented as a JSON object, each annotation is placed within the object and represented as a single name/value pair.
+                // So, do we need to verify that the property annotation should be specified as an instance annotation in the nested resource value?
+                // Or, just let it go and let the upper reader to handle it?
+                // Sam descided to comment out the verification for now. 12/2025, reasons:
+                // 1) This would be a breaking change for existing clients.
+                // 2) The upper reader will handle invalid annotations anyway.
+
+                //if (parentScope.PropertyAndAnnotationCollector.GetCustomPropertyAnnotations(nestedResourceInfo.Name).Any() ||
+                //    parentScope.PropertyAndAnnotationCollector.GetODataPropertyAnnotations(nestedResourceInfo.Name).Count > 0)
+                //{
+                //    throw new ODataException(Error.Format(SRResources.ODataJsonPropertyAndValueDeserializer_NestedResourceValueWithPropertyTypeAnnotation, nestedResourceInfo.Name));
+                //}
+
                 Debug.Assert(parentSelectedProperties != null, "parentProjectedProperties != null");
                 this.ReadResourceSetItemStart(/*propertyAndAnnotationCollector*/ null, parentSelectedProperties.GetSelectedPropertiesForNavigationProperty(parentScope.ResourceType, nestedResourceInfo.Name));
             }

src/Microsoft.OData.Core/Json/ODataJsonResourceDeserializer.cs

@@ -989,7 +989,7 @@ internal ODataJsonReaderNestedInfo ReadPropertyWithoutValue(IODataJsonReaderReso
             if (edmProperty == null || edmProperty.Type.IsUntyped())
             {
                 // Undeclared property - we need to run detection algorithm here.
-                readerNestedInfo = this.ReadUndeclaredProperty(resourceState, propertyName, propertyWithValue: false);
+                 readerNestedInfo = this.ReadUndeclaredProperty(resourceState, propertyName, propertyWithValue: false);
 
                 this.AssertJsonCondition(JsonNodeType.Property, JsonNodeType.EndObject);
                 return readerNestedInfo;
@@ -1274,7 +1274,7 @@ private ODataJsonReaderNestedInfo ReadPropertyWithValue(IODataJsonReaderResource
                     if (isCollection)
                     {
                         readerNestedResourceInfo = this.ReadingResponse || isDeltaResourceSet
-                            ? ReadExpandedResourceSetNestedResourceInfo(resourceState, navigationProperty, navigationProperty.Type.ToStructuredType(), propertyName, /*isDeltaResourceSet*/ isDeltaResourceSet)
+                            ? ReadExpandedResourceSetNestedResourceInfo(resourceState, navigationProperty, navigationProperty.Type.ToStructuredType(), propertyName, isDeltaResourceSet: isDeltaResourceSet, this.MessageReaderSettings)
                             : ReadEntityReferenceLinksForCollectionNavigationLinkInRequest(resourceState, navigationProperty, propertyName, /*isExpanded*/ true);
                     }
                     else
@@ -3502,7 +3502,7 @@ await ValidateExpandedNestedResourceInfoPropertyValueAsync(
                     if (isCollection)
                     {
                         readerNestedResourceInfo = this.ReadingResponse || isDeltaResourceSet
-                            ? ReadExpandedResourceSetNestedResourceInfo(resourceState, navigationProperty, navigationProperty.Type.ToStructuredType(), propertyName, isDeltaResourceSet: isDeltaResourceSet)
+                            ? ReadExpandedResourceSetNestedResourceInfo(resourceState, navigationProperty, navigationProperty.Type.ToStructuredType(), propertyName, isDeltaResourceSet: isDeltaResourceSet, this.MessageReaderSettings)
                             : ReadEntityReferenceLinksForCollectionNavigationLinkInRequest(resourceState, navigationProperty, propertyName, isExpanded: true);
                     }
                     else

src/Microsoft.OData.Core/Json/ODataJsonWriter.cs

@@ -364,22 +364,22 @@ protected override void EndProperty(ODataPropertyInfo property)
         /// <param name="resource">The resource to write.</param>
         protected override void StartResource(ODataResource resource)
         {
-            ODataNestedResourceInfo parentNavLink = this.ParentNestedResourceInfo;
-            if (parentNavLink != null)
+            ODataNestedResourceInfo nestedResourceInfo = this.ParentNestedResourceInfo;
+            if (nestedResourceInfo != null)
             {
                 // For a null value, write the type as a property annotation
                 if (resource == null)
                 {
-                    if (parentNavLink.TypeAnnotation != null && parentNavLink.TypeAnnotation.TypeName != null)
+                    if (nestedResourceInfo.TypeAnnotation != null && nestedResourceInfo.TypeAnnotation.TypeName != null)
                     {
-                        this.odataAnnotationWriter.WriteODataTypePropertyAnnotation(parentNavLink.Name, parentNavLink.TypeAnnotation.TypeName);
+                        this.odataAnnotationWriter.WriteODataTypePropertyAnnotation(nestedResourceInfo.Name, nestedResourceInfo.TypeAnnotation.TypeName);
                     }
 
-                    this.instanceAnnotationWriter.WriteInstanceAnnotations(parentNavLink.GetInstanceAnnotations(), parentNavLink.Name);
+                    this.instanceAnnotationWriter.WriteInstanceAnnotations(nestedResourceInfo.GetInstanceAnnotations(), nestedResourceInfo.Name);
                 }
 
                 // Write the property name of an expanded navigation property to start the value.
-                this.jsonWriter.WriteName(parentNavLink.Name);
+                this.jsonWriter.WriteName(nestedResourceInfo.Name);
             }
 
             if (resource == null)

src/Microsoft.OData.Core/ODataMessageReaderSettings.cs

@@ -94,6 +94,7 @@ public ValidationKinds Validations
                 ThrowOnDuplicatePropertyNames = (validations & ValidationKinds.ThrowOnDuplicatePropertyNames) != 0;
                 ThrowIfTypeConflictsWithMetadata = (validations & ValidationKinds.ThrowIfTypeConflictsWithMetadata) != 0;
                 ThrowOnUndeclaredPropertyForNonOpenType = (validations & ValidationKinds.ThrowOnUndeclaredPropertyForNonOpenType) != 0;
+                ThrowOnUnexpectedODataPropertyAnnotationOnNavigationProperty = (validations & ValidationKinds.ThrowOnUnexpectedODataPropertyAnnotationOnNavigationProperty) != 0;
             }
         }
 
@@ -224,6 +225,11 @@ public ODataMessageQuotas MessageQuotas
         /// </summary>
         internal bool ThrowOnUndeclaredPropertyForNonOpenType { get; private set; }
 
+        /// <summary>
+        /// Returns whether ThwoOnUnexpectedODataPropertyAnnotationsOnNavigationProperty validation setting is enabled.
+        /// </summary>
+        internal bool ThrowOnUnexpectedODataPropertyAnnotationOnNavigationProperty { get; private set; }
+
         /// <summary>
         /// Gets or sets a value that indicates whether the reader should put key values in their own URI segment when automatically building URIs.
         /// If this value is false, automatically-generated URLs will take the form "../EntitySet('KeyValue')/..".
@@ -299,6 +305,7 @@ private void CopyFrom(ODataMessageReaderSettings other)
             this.ThrowOnDuplicatePropertyNames = other.ThrowOnDuplicatePropertyNames;
             this.ThrowIfTypeConflictsWithMetadata = other.ThrowIfTypeConflictsWithMetadata;
             this.ThrowOnUndeclaredPropertyForNonOpenType = other.ThrowOnUndeclaredPropertyForNonOpenType;
+            this.ThrowOnUnexpectedODataPropertyAnnotationOnNavigationProperty = other.ThrowOnUnexpectedODataPropertyAnnotationOnNavigationProperty;
             this.LibraryCompatibility = other.LibraryCompatibility;
             this.Version = other.Version;
             this.ReadAsStreamFunc = other.ReadAsStreamFunc;