Breaking changes in 5.0

Content

• Target Framework

• Changes in classes

  • Model changes for R3 and higher
  • Model changes for R4 and higher
  • Model changes for R5 and higher
  • Other changes

• Behavior

• Changes specific to the FhirClient

  • Obsolete members removed
  • The public interface has been cleaned

• ValueSets and enums updates

• Removed obsolete members

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

Model changes 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 changes 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.RequirementsElement is now of type Markdown instead of FhirString.
• ElementDefinition.binding.DescriptionElement is now of type Markdown instead of FhirString.
• ElementDefinition.mapping.CommentElement is now of type Markdown instead of FhirString.
• Elements that are of type Markdown now are treated as primitives: they have both a primitive (of type string) and an Element property of type Markdown.

Model changes 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.
• Signature.who[x] and Signature.onBehalfOf[x] are no longer choice types in the R5 HL7 spec, however for backwards compatibility in the shared code of the SDK, we have decided to keep the type of these elements the same as they were (DataType), even though from R5 on this can only be a ResourceReference.

Other changes

• 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?.
• 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).

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.

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 now virtual).
• Making it possible to switch to another (read: the newer) serializer.

Obsolete members removed

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

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)

ValueSets and enums updates

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:

ValueSet	Corresponding (new) enum
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

Removed obsolete members

The following obsolete member are removed in this version:

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