Breaking changes in 5.0

Behavior

• When you serialize a FHIR resource with the option summary != SummaryType.False then we add now 2 Meta tags in the resource: one for the context STU3 and one for the context R4 and higher.

Target Framework

This version of the SDK no longer supports .NET Framework 4.5.2. The following framework are supported:

• .NET 6.0
• NetStandard 2.0

Changes in classes

• The constructor of previously abstract class BaseFhirClient is now public and requires a ModelInspector and fhirVersion. The nullable parameter IStructureDefinitionSummaryProvider has been removed.
• The classes BundleToEntryRequest, TypedEntryResponseToBundle, EntryRequest, EntryRequestHeaders, EntryResponse, TypedEntryResponse, EntryToTypedEntryExtensions, EntryToHttpExtensions, HttpToEntryExtensions and TypedEntryResponseToBundle have been made internal. They exposed internal details about the FhirClient and should never have been public.
• The default parameter IStructureDefinitionSummaryProvider provider of all the constructors of FhirClient have been removed.
• We have added nullability annotations to BaseFhirClient and FhirClient, which means you may get compiler errors about the fact that most functions on these classes return a nullable resource, which may have gone unhandled until now. These functions return null when the operation resulted in an OperationOutcome instead of the expected resource type. In such cases, check LastResult for the OperationOutcome.
• The constructor of classes BaseFhirParser and BaseFhirSerializer requires a ModelInspector.
• The protected methods BaseFhirParser.MakeElementStack are not static anymore.
• ModelInfo.ConformanceResources and ModelInfo.ConformanceResourceTypes have been removed.
• ModelInfo.FhirCoreProfileBaseUri has been removed. Use now Canonical.FHIR_CORE_PROFILE_BASE_URI.
• Obsolete members ModelInfo.IsProfiledQuantity and ModelInfoExtensions.GetCollectionName have been removed.
• Partial class `ModelInfo' is not static anymore.
• SchemaCollection has been removed
• ValidationSettings.XsdSchemaCollection is now of type XmlSchemaSet instead of SchemaCollection.
• IncorrectElementDefinitionException has been removed
• Interface IConformanceSource is now derived from ICommonConformanceSource. And IConformanceSource.FindCodeSystemByValueSet(string) has been moved to this new interface ICommonConformanceSource.
• Obsolete extension methods of ResourceResolverExtensions has been removed: FindExtensionDefinition, FindStructureDefinition, FindStructureDefinitionForCoreType and FindValueSet.
• The constructor of ProfileAssertion and ProfilePreprocessor require now a ModelInspector as a parameter.
• The public method of ProfileAssertion.SetDeclaredType has been removed.
• The overloaded methods Validate of the class Validator with the parameter ITypedElement requires now a ModelInspector as a parameter.
• The public method of Validator.IsBindeableFhirType has been removed.
• The type of property TranslateParameters.ConceptMap has been changed from ConceptMap to Resource.
• The type of the parameter conceptMap in TranslateParameters has been changed from ConceptMap to Resource.
• The public method ElementDefinitionExtensions.PrimaryTypeCode has been changed to GetTypeCode() and the return type is now string?.
• The FindConceptMaps() and FindConceptMapsAsync() methods in FhirPackageSource and CommonFhirPackageSource will now return an empty list, not null when no items are found (this was the original intention of the interface, but was implemented incorrrectly).
• FhirPath's ExpressionVisitor has been simplified, it no longer requires a SymbolTable arguments to Accept and the Visit methods.
• The public class SemVersion has been made internal. If you want to keep using this functionality we recommend to use the external Semver NuGet package.
• The public class ProfileReference has been removed. All functionality has been moved to Canonical.
• UriParamList.FromUri has been removed - it always returned null
• The regex pattern for Base64Binary was updated.
• The regex pattern for FhirDateTime, Instant, Time was updated.
• the regex pattern for Markdown was updated.
• CodeSystemContentMode has been moved out of the CodeSystem class and is now a top-level enum (it is re-used in TerminologyCapabilities).

Changes specific to the FhirClient

The FhirClient is one of the oldest parts of the SDK and is showing its age (both on the public interface and inside). We have started a gradual renovation process, which includes the following:

• Adding support for CancellationTokens (done)
• Better alignment with HttpMessageHandler/HttpMessageContent and testability (scheduled for 5.1)
• Making it possible to mock the FhirClient (done - we have made all its methods are now virtual).
• Making it possible to switch to another (read: the newer) serializer.

We have started to remove obsolete members:

These members have been removed, you can use the FhirClient.Settings property or the settings argument in the constructor instead:

• VerifyFhirVersion
• PreferredFormat
• UseFormatParam
• Timeout
• ReturnFullResource
• PreferredReturn
• PreferredParameterHandling
• PreferCompressedResponses
• CompressRequestBody
• ParserSettings
• OnBeforeRequest: add a HttpClientEventHandler or another HttpMessageHandler to the constructor to use this functionality
• OnAfterResponseRequest: add a HttpClientEventHandler or another HttpMessageHandler to the constructor to use this functionality

Obsolete class LegacyFhirClient has been removed.

The public interface has been cleaned up to be able to renovate the internals

Some classes were exposed that are blocking us from refactoring the client, while at the same time they don't provide a lot of functionality for general use:

• BaseFhirClient's property HttpClientRequester Requester { get; init; } went from protected to internal.
• Its protected constructor has been replaced by multiple public constructor.
• BaseFhirClient is no longer abstract.
• BundleToEntryRequest, EntryRequest, EntryRequestHeaders, EntryResponse and TypedEntryResponse are now internal.
• Extension classes EntryToTypedEntryExtensions, HttpToEntryExtensions and TypedEntryResponseToBundle are now internal
• WebRequestExtensions has been removed (all methods were already internal)

Removed obsolete members

• Hl7.Fhir.Model.ElementDefinitionExtensions.GetDeclaredProfiles(TypeRefComponent). Use ElementDefinition.TypeRefComponent.GetTypeProfile() instead.
• Hl7.Fhir.ElementModel.ElementNode.Clone(). Use Hl7.Fhir.ElementModel.ElementNode.ShallowCopy() instead.
• Hl7.Fhir.ElementModel.Types.DateTime.FromDateTime(DateTimeOffset). Use Hl7.Fhir.ElementModel.Types.DateTime.FromDateTimeOffset(DateTimeOffset) instead.
• Hl7.Fhir.Serialization.FhirXmlSerializationSettings.SkipUnknownElements. Use Hl7.Fhir.Serialization.FhirXmlSerializationSettings.IgnoreUnknownElements instead.
• Hl7.Fhir.Serialization.ParserSettings.Default. Use Hl7.Fhir.Serialization.ParserSettings.CreateDefault() instead.
• Hl7.Fhir.Support.DateExtensions.ToFhirDateTime(DateTime). Use Hl7.Fhir.Support.DateExtensions.ToFhirDateTime(DateTimeOffset) instead.
• Hl7.Fhir.Support.DateExtensions.ToFhirDateTime(DateTime?). Use Hl7.Fhir.Support.DateExtensions.ToFhirDateTime(DateTimeOffset?) instead.
• Hl7.Fhir.Specification.Source.OriginInformation. Use Hl7.Fhir.Specification.Source.OriginAnnotation instead.
• Hl7.Fhir.Specification.Snapshot.SnapshotGeneratorSettings.Default. Use ``Hl7.Fhir.Specification.Snapshot.SnapshotGeneratorSettings.CreateDefault()` instead.
• Hl7.Fhir.Specification.Source.ConformanceSummaryProperties.GetConformanceStatus(IArtifactSummaryPropertyBag). Use Hl7.Fhir.Specification.Source.ConformanceSummaryProperties.GetPublicationStatus(IArtifactSummaryPropertyBag) instead.
• Hl7.Fhir.Specification.Source.DirectorySource(bool). Use Hl7.Fhir.Specification.Source.DirectorySource(DirectorySourceSettings) instead.
• Hl7.Fhir.Specification.Source.DirectorySource(string, bool). Use Hl7.Fhir.Specification.Source.DirectorySource(DirectorySourceSettings) instead.
• Hl7.Fhir.Introspection.ClassMapping.AddMappingForType(Type. FhirRelease, ClassMapping).
• Hl7.Fhir.Introspection.ClassMapping.DeclaredType.
• Hl7.Fhir.Introspection.ClassMapping.Create(Type). Use Hl7.Fhir.Introspection.ClassMapping.TryCreate(Type, ClassMapping, FhirRelease) instead.
• Hl7.Fhir.Introspection.ClassMapping.IsMappableType(Type). Use Hl7.Fhir.Introspection.ClassMapping.TryCreate(Type, ClassMapping, FhirRelease) instead.
• Hl7.Fhir.Introspection.FhirVersionDependentExtensions.AppliesToVersion(IFhirVersionDependent, FhirRelease). Use Hl7.Fhir.Introspection.FhirVersionDependentExtensions.AppliesToRelease(Attribute, FhirRelease) instead.
• Hl7.Fhir.Introspection.PropertyMapping.ElementType. Use Hl7.Fhir.Introspection.PropertyMapping.ImplementingType instead.
• Hl7.Fhir.Introspection.PropertyMapping.IsResourceChoice.
• Hl7.Fhir.Introspection.PropertyMapping.Create(PropertyInfo, ClassMapping, FhirRelease). Use Hl7.Fhir.Introspection.PropertyMapping.TryCreate(PropertyInfo, out PropertyMapping?, ClassMapping, FhirRelease) instead.
• Hl7.Fhir.Model.Date.ToDateTime(). Use Hl7.Fhir.Model.Date.ToDateTimeOffset() instead.
• Hl7.Fhir.Model.FhirDateTime.FhirDateTime(DateTime). Use Hl7.Fhir.Model.FhirDateTime.FhirDateTime(DateTimeOffset) instead.
• Hl7.Fhir.Model.FhirDateTime.FhirDateTime(int, int, int, int, int, int). Use Hl7.Fhir.Model.FhirDateTime.FhirDateTime(int, int, int, int, int, int, TimeSpan) instead.
• Hl7.Fhir.Model.FhirDateTime.ToDateTimeOffset(TimeSpan?). Use Hl7.Fhir.Model.FhirDateTime.ToDateTimeOffset(TimeSpan) instead.
• Hl7.Fhir.Model.FhirDateTime.ToDateTime(). Use Hl7.Fhir.Model.FhirDateTime.ToDateTimeOffset(TimeSpan) instead.
• Hl7.Fhir.Model.XHtml.IsValidValue(string). Use Hl7.Fhir.Model.XHtml.IsValidNarrativeXhtml(string) instead (or IsValidXml if that is more appropriate).
• Hl7.Fhir.Rest.EntryToHttpExtensions.ToHttpWebRequest(EntryRequest, Uri, FhirClientSettings). Use Hl7.Fhir.Rest.EntryToHttpExtensions.ToHttpRequestMessage(EntryRequest, Uri, FhirClientSettings) instead.
• Hl7.Fhir.Rest.SearchParams.FromParameters(object). Use Parameters.ToSearchParameters() method instead.
• Hl7.Fhir.Rest.ResourceIdentity.Endpoint. Use Hl7.Fhir.Rest.ResourceIdentity.BaseUri instead.
• Hl7.Fhir.Specification.Terminology.ValueSetExpanderSettings.Default. Use Hl7.Fhir.Specification.Terminology.ValueSetExpanderSettings.CreateDefault() instead.
• Hl7.Fhir.Support.Issue.PROFILE_INCOMPLETE_BINDING. This issue will not be raised by the validator anymore. Use 'PROFILE_ELEMENTDEF_INCORRECT' instead.
• Hl7.Fhir.Utility.FhirReleaseParser.TryFhirReleaseFromMimeVersion(string, out FhirRelease?). Use Hl7.Fhir.Utility.FhirReleaseParser.TryGetFhirReleaseFromMimeVersion(string, out FhirRelease?) instead.
• Hl7.Fhir.Utility.FhirReleaseParser.TryFhirReleaseFromCorePackageName(string, out FhirRelease?). Use Hl7.Fhir.Utility.FhirReleaseParser.TryGetFhirReleaseFromCorePackageName(string, out FhirRelease?) instead.
• Hl7.Fhir.Utility.ObjectListExtensions. This class has been removed.
• Hl7.FhirPath.EvaluationContext.Default. Use Hl7.FhirPath.EvaluationContext.CreateDefault() instead.
• ResourceReferenceNotFoundException
• OperationValidCodeExtensions
• FhirPackageSource
• CommonFhirPackageSource

Model (for R3 and higher)

• Methods ConceptMap.SourceAsString() and ConceptMap.TargetAsString() are removed
• The class Hl7.Fhir.Model.Attachment moved to the library Base.
• Hl7.Fhir.Model.Attachment.UrlElement is now of type FhirUri instead of FhirUrl.
• DomainResource.modifierExtension is a summary element now.
• Hl7.Fhir.Model.Signature
• Cardinality of Signature.type is now 0..* (was 1..*)
• Cardinality of Signature.when is now 0..1 (was 1..1)
• Cardinality of Signature.who is now 0..1 (was 1..1)

Model (for R4 and higher)

• The type of CapabilityStatement.Type has been changed to string? (was ResourceType?)
• The type of CapabilityStatement.TypeElement has been changed to Code (was Code<Hl7.Fhir.Model.ResourceType>)
• The AllowedTypes attribute has been removed from the following properties:
  • ElementDefinition.Value
  • ElementDefinition.DefaultValue
  • ElementDefinition.Pattern
  • ElementDefinition.Fixed
• Enum ElementDefinition.ConstraintSeverity has been moved to Template-Bindings.cs.
• Description of Money values has been corrected (diacritics)
• The class Hl7.Fhir.Model.RelatedArtifact has been moved to Conformance library
• ElementDefinition.constraint.Requirements is now of type Markdown instead of string.
• ElementDefinition.constraint.RequirementElement has been removed.
• ElementDefinition.binding.Description is now of type Markdown instead of string.
• ElementDefinition.binding.DescriptionElement has been removed.
• ElementDefinition.mapping.Comment is now of type Markdown instead of string.
• ElementDefinition.mapping.CommentElement has been removed.

Model (for R5 and higher)

• RelatedArtifact.UrlElement has been removed from the spec. The property is still available in RelatedArtifact, but should not be used in R5.
• The enum value ElementDefinition.DiscriminatorType.Pattern has been deprecated for R5. Do not use this enum value for R5.
• ElementDefinition.constraint.xpath has been removed from the spec. The property is still available in ElementDefinition, but should not be used in R5.
• ValueSet.scope.focus has been removed from the spec. The property is still available in ValueSet, but should not be used in R5.
• Obsolete NamingSystem Purpose/Experimental/ExperimentalElement properties have been removed.

ValueSets/enums update

Over the last year we have discovered that we have generated enum names that were not capitalized. This has been corrected. This means the following enums have had their names capitalized:

• (R3) Sequence.qualityType, Sequence.repositoryType
• (R4 and higher) MolecularSequence.orientationType, qualityType, repositoryType, sequenceType, strandType,
• (R4 and higher) medicationRequestIntent, medicationRequestStatus
• (R4 and higher) v3-ConfidentialityClassification has been renamed to ConfidentialityClassification
• (R4 and higher) VerificationResult.status
• (R4 and higher) messageheader_response_request has been renamed to MessageHeaderResponseRequest

The names of the following valuesets clashed with properties within the classes, which meant we had properties which names ended with an underscore. This has been corrected for the following valuesets:

• ["http://hl7.org/fhir/ValueSet/characteristic-combination"] = "CharacteristicCombinationCode",
• ["http://hl7.org/fhir/ValueSet/claim-use"] = "ClaimUseCode",
• ["http://hl7.org/fhir/ValueSet/content-type"] = "ContentTypeCode",
• ["http://hl7.org/fhir/ValueSet/exposure-state"] = "ExposureStateCode",
• ["http://hl7.org/fhir/ValueSet/verificationresult-status"] = "StatusCode",
• ["http://terminology.hl7.org/ValueSet/v3-Confidentiality"] = "ConfidentialityCode",
• ["http://hl7.org/fhir/ValueSet/variable-type"] = "VariableTypeCode",
• ["http://hl7.org/fhir/ValueSet/group-measure"] = "GroupMeasureCode"