Changes to include Structure Definition version in canonical URL (#5280)

* CHanges to include Structure Definition version in canonical URL, as well as unit test.

* Rolled back so only one (latest) structure definition is returned in capability statement.

* Modified Unit test to check for single version returned.

* updated E2E tests to include version for structured definitions

Author: paorodma-ms

docs/rest/VersionedUpdateExample.http

@@ -228,4 +228,28 @@ If-Match: W/"2"
       }
     ]
   }
+}
+
+###
+# Post a us-core-patient profile
+# This will be returned in capability statement.
+# @name patient
+POST https://{{hostname}}/StructureDefinition
+Content-Type: application/json
+Authorization: Bearer {{bearer.response.body.access_token}}
+
+{
+  "resourceType": "StructureDefinition",
+  "id": "us-core-patient",
+  "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient",
+  "version": "6.1.0",
+  "name": "USCorePatientProfile",
+  "title": "US Core Patient Profile",
+  "status": "active",
+  "experimental": false,
+  "date": "2025-12-15",
+  "publisher": "HL7 US Realm Steering Committee",
+  "type": "Patient",
+  "kind": "resource",
+  "abstract": false,
 }

src/Microsoft.Health.Fhir.R4.Core.UnitTests/Features/Validation/ServerProvideProfileValidationTests.cs

@@ -250,6 +250,23 @@ public async Task GivenCaseInsensitiveResourceType_WhenGettingSupportedProfiles_
             Assert.Contains("http://example.org/fhir/StructureDefinition/custom-patient", profiles);
         }
 
+        [Fact]
+        public async Task GivenMultipleVersionsOfSameProfile_WhenGettingSupportedProfiles_ThenAllVersionsAreReturned()
+        {
+            // Arrange
+            var patientProfileV1 = CreateStructureDefinition("http://example.org/fhir/StructureDefinition/custom-patient", "Patient", "1.0.0");
+            var patientProfileV2 = CreateStructureDefinition("http://example.org/fhir/StructureDefinition/custom-patient", "Patient", "2.0.0");
+            SetupSearchServiceWithResults("StructureDefinition", patientProfileV1, patientProfileV2);
+
+            // Act
+            var profiles = await _serverProvideProfileValidation.GetSupportedProfilesAsync("Patient", CancellationToken.None);
+
+            // Assert
+            Assert.NotNull(profiles);
+            Assert.Single(profiles);
+            Assert.Contains("http://example.org/fhir/StructureDefinition/custom-patient|2.0.0", profiles);
+        }
+
         [Fact]
         public async Task GivenDisableCacheRefresh_WhenGettingSupportedProfiles_ThenCacheIsNotRefreshed()
         {
@@ -276,9 +293,9 @@ public void Dispose()
             _serverProvideProfileValidation?.Dispose();
         }
 
-        private static StructureDefinition CreateStructureDefinition(string url, string type)
+        private static StructureDefinition CreateStructureDefinition(string url, string type, string version = null)
         {
-            return new StructureDefinition
+            var structureDefinition = new StructureDefinition
             {
                 Id = Guid.NewGuid().ToString("N").Substring(0, 16), // Generate valid FHIR ID
                 Url = url,
@@ -290,6 +307,13 @@ private static StructureDefinition CreateStructureDefinition(string url, string
                 BaseDefinition = $"http://hl7.org/fhir/StructureDefinition/{type}",
                 Derivation = StructureDefinition.TypeDerivationRule.Constraint,
             };
+
+            if (!string.IsNullOrEmpty(version))
+            {
+                structureDefinition.Version = version;
+            }
+
+            return structureDefinition;
         }
 
         private void SetupSearchServiceWithNoResults()

src/Microsoft.Health.Fhir.Shared.Core/Features/Validation/ServerProvideProfileValidation.cs

@@ -15,6 +15,7 @@
 using Hl7.Fhir.ElementModel;
 using Hl7.Fhir.Model;
 using Hl7.Fhir.Serialization;
+using Hl7.Fhir.Specification;
 using Hl7.Fhir.Specification.Source;
 using Hl7.Fhir.Specification.Summary;
 using MediatR;
@@ -37,6 +38,7 @@ namespace Microsoft.Health.Fhir.Core.Features.Validation
     public sealed class ServerProvideProfileValidation : IProvideProfilesForValidation, IDisposable
     {
         private static HashSet<string> _supportedTypes = new HashSet<string>() { "ValueSet", "StructureDefinition", "CodeSystem" };
+        private static string _structureDefinitionVersionKey = "Conformance.version";
 
         private readonly SemaphoreSlim _cacheSemaphore = new SemaphoreSlim(1, 1);
         private readonly Func<IScoped<ISearchService>> _searchServiceFactory;
@@ -227,7 +229,18 @@ public async Task<IEnumerable<string>> GetSupportedProfilesAsync(string resource
 
                         return string.Equals((string)type, resourceType, StringComparison.OrdinalIgnoreCase);
                     })
-                .Select(x => x.ResourceUri).ToList();
+                .Select(x => GetCanonicalUrl(x)).ToList();
+        }
+
+        private static string GetCanonicalUrl(ArtifactSummary artifact)
+        {
+            var url = artifact.ResourceUri;
+            if (artifact.TryGetValue(_structureDefinitionVersionKey, out object version) && version != null && !string.IsNullOrEmpty(version.ToString()))
+            {
+                return $"{url}|{version}";
+            }
+
+            return url;
         }
 
         private static string GetHashForSupportedProfiles(IReadOnlyCollection<ArtifactSummary> summaries)
@@ -240,7 +253,7 @@ private static string GetHashForSupportedProfiles(IReadOnlyCollection<ArtifactSu
             var sb = new StringBuilder();
             summaries.Where(x => x.ResourceTypeName == KnownResourceTypes.StructureDefinition)
                .Where(x => x.TryGetValue(StructureDefinitionSummaryProperties.TypeKey, out object type))
-               .Select(x => x.ResourceUri).ToList().ForEach(url => sb.Append(url));
+               .Select(x => GetCanonicalUrl(x)).ToList().ForEach(url => sb.Append(url));
 
             return sb.ToString().ComputeHash();
         }

test/Microsoft.Health.Fhir.Shared.Tests.E2E/Rest/ValidateTests.cs

@@ -221,22 +221,43 @@ public async Task GivenInvalidProfile_WhenValidateCalled_ThenBadRequestReturned(
         [Fact]
         public async Task GivenPostedProfiles_WhenCallingForMetadata_ThenMetadataHasSupportedProfiles()
         {
+            // Give the server time to refresh its profile cache
+            await Task.Delay(TimeSpan.FromSeconds(2));
+
             using FhirResponse<CapabilityStatement> response = await _client.ReadAsync<CapabilityStatement>("metadata");
 #if !Stu3
             var supportedProfiles = response.Resource.Rest.Where(r => r.Mode.ToString().Equals("server", StringComparison.OrdinalIgnoreCase)).
                 SelectMany(x => x.Resource.Where(x => x.SupportedProfile.Any()).Select(x => x.SupportedProfile)).
                 SelectMany(x => x).OrderBy(x => x).ToList();
+
+            var expectedProfiles = new[]
+            {
+                "http://hl7.org/fhir/us/core/StructureDefinition/us-core-careplan|3.0.0",
+                "http://hl7.org/fhir/us/core/StructureDefinition/us-core-organization|3.0.0",
+                "http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient|3.0.0",
+            };
 #else
             var supportedProfiles = response.Resource.Profile.Select(x => x.Url.ToString()).OrderBy(x => x).ToList();
+
+            var expectedProfiles = new[]
+            {
+                "http://hl7.org/fhir/us/core/StructureDefinition/us-core-careplan|2.0.0",
+                "http://hl7.org/fhir/us/core/StructureDefinition/us-core-organization|2.0.0",
+                "http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient|2.0.0",
+            };
 #endif
-            Assert.All(
-                new[]
-                {
-                    "http://hl7.org/fhir/us/core/StructureDefinition/us-core-careplan",
-                    "http://hl7.org/fhir/us/core/StructureDefinition/us-core-organization",
-                    "http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient",
-                },
-                x => Assert.Contains(supportedProfiles, y => string.Equals(x, y, StringComparison.OrdinalIgnoreCase)));
+
+            // Add this to see what profiles are actually returned
+            var actualProfilesString = string.Join(", ", supportedProfiles);
+            System.Diagnostics.Debug.WriteLine($"Actual profiles returned: {actualProfilesString}");
+
+            // Check each expected profile individually to see which one is missing
+            foreach (var expectedProfile in expectedProfiles)
+            {
+                var found = supportedProfiles.Any(y => string.Equals(expectedProfile, y, StringComparison.OrdinalIgnoreCase));
+                System.Diagnostics.Debug.WriteLine($"Profile '{expectedProfile}' found: {found}");
+                Assert.Contains(supportedProfiles, y => string.Equals(expectedProfile, y, StringComparison.OrdinalIgnoreCase));
+            }
         }
 
         private void CheckOperationOutcomeIssue(