Requirements

Introduction

Scope and Usage

The Requirements Resource a set of statements that are requirements for some design artifact to meet. The requirements resource is intended to meet two principle use cases:

• Documenting known regulatory, business, functional and technical requirements for interoperability specifications, particularly those published as Implementation Guides
• Performing the same role for clinical processes as documented in PlanDefinition and ActivityDefinition

The Requirements Resource is focused on gathering known requirements and providing traceability from solutions to the requirements they are intended to meet.

In any set of requirements, some of them may already be met by preexisting specifications, while others are requirements that must be fulfilled by some specification or design that is created with or subsequent to the requirements. For this reason, requirements can directly identify features of specifications that satisfy the stated requirement, but in most cases, it is expected that the specifications and designs that meet the requirements will provice traceability to the requirement.

Each Requirements resource carries a set of statements about requirements. Each statement has:

• identity: Computable and human identification of the statement
• requirement: The wording of the requirement
• conformance: The strength associated with the statement. The strength is almost always embedded in the language of the requirement, but this allows for filtering and a degree of automated processing
• source: Source information about who was the source of the requirement
• satisfied by: A reference to some pre-existing specification element that satisfies the requirement

Boundaries and Relationships

Requirements may by referenced from almost any resource by the Requirements Satisfied extension. Generally, this extension will be found in the Canonical Resources but this is not a hard rule.

If requirements are satisfied by an existing specification, they SHOULD reference a FHIR resource by {url} or a particular element by {url}#id, but the target of a reference does not need to be a resource at all.

The requirements resource carries minimal provenance information - the name of the publisher, and the source of the statements. Additional provenance information should be carried in a Provenance resource.

Background and Context

A number of stakeholders publishing FHIR implementation guides wish to do formal requirements tracing. This resource exists for them.

StructureDefinition

Elements (Simplified)

• Requirements [0..*]: - A set of requirements - features of systems that are necessary
• Requirements.url [0..1]: uri Canonical identifier for this Requirements, represented as a URI (globally unique)
• Requirements.identifier [0..*]: Identifier Additional identifier for the Requirements (business identifier)
• Requirements.version [0..1]: string Business version of the Requirements
• Requirements.versionAlgorithm[x] [0..1]: string, Coding extensible:version-algorithm How to compare versions
• Requirements.name [0..1]: string Name for this Requirements (computer friendly)
• Requirements.title [0..1]: string Name for this Requirements (human friendly)
• Requirements.status [1..1]: code required:publication-status draft | active | retired | unknown
• Requirements.experimental [0..1]: boolean For testing only - never for real usage
• Requirements.date [0..1]: dateTime Date last changed
• Requirements.publisher [0..1]: string Name of the publisher/steward (organization or individual)
• Requirements.contact [0..*]: ContactDetail Contact details for the publisher
• Requirements.description [0..1]: markdown Natural language description of the requirements
• Requirements.useContext [0..*]: UsageContext The context that the content is intended to support
• Requirements.jurisdiction [0..*]: CodeableConcept extensible:jurisdiction Jurisdiction of the authority that maintains the Requirements (if applicable)
• Requirements.purpose [0..1]: markdown Why this Requirements is defined
• Requirements.copyright [0..1]: markdown Notice about intellectual property ownership, can include restrictions on use
• Requirements.copyrightLabel [0..1]: string Copyright holder and year(s)
• Requirements.derivedFrom [0..*]: canonical Other set of Requirements this builds on
• Requirements.imports [0..*]: - External requirements that apply here
• Requirements.imports.reference [1..1]: canonical Source of imported statements
• Requirements.imports.key [0..*]: id Statement key
• Requirements.reference [0..*]: url External artifact (rule/document etc. that) created this set of requirements
• Requirements.actor [0..*]: - Actor for these requirements
• Requirements.actor.reference [1..1]: canonical Actor referenced
• Requirements.actor.key [0..1]: id Unique label for actor (used in statements)
• Requirements.statement [0..*]: BackboneElement Conformance requirement statement
• Requirements.statement.key [1..1]: id Key that identifies this statement
• Requirements.statement.label [0..1]: string Short Human label for this statement
• Requirements.statement.conformance [0..*]: code required:conformance-expectation SHALL | SHOULD | MAY | SHOULD-NOT | SHALL-NOT
• Requirements.statement.conditionality [0..1]: boolean Set to true if requirements statement is conditional
• Requirements.statement.requirement [1..1]: markdown The actual requirement
• Requirements.statement.category [0..*]: Coding High level categorization of a statement
• Requirements.statement.derivedFrom [0..1]: - Another statement this is refining, tightening, or establishing more context for
• Requirements.statement.derivedFrom.reference [0..1]: canonical Pointer to Requirements instance
• Requirements.statement.derivedFrom.key [1..1]: id Key of referenced statement
• Requirements.statement.partOf [0..1]: - Higher-level requirement or statement which this is a logical sub-requirement of
• Requirements.statement.partOf.reference [0..1]: canonical Pointer to Requirements instance
• Requirements.statement.partOf.key [1..1]: id Key of referenced statement
• Requirements.statement.satisfiedBy [0..*]: url Design artifact that satisfies this requirement
• Requirements.statement.reference [0..*]: url External artifact (rule/document etc. that) created this requirement
• Requirements.statement.source [0..*]: [Reference(CareTeam](/Reference(CareTeam), Device, Group, HealthcareService, Organization, Patient, Practitioner, PractitionerRole, RelatedPerson)) Who asked for this statement
• Requirements.statement.actor [0..*]: id Key of relevant actor

Mappings

• Requirements Mappings — 30 mapping entries

Implementation Guide

implementationguide-Requirements-core.xml

<?xml version="1.0" encoding="UTF-8"?>

<ImplementationGuide xmlns="http://hl7.org/fhir">
  <id value="Requirements-core"/>
  <version value="0.01"/>
  <name value="RequirementsProfilesAndExtensions"/>
  <title value="Requirements  Profiles and  Extensions"/>
  <status value="draft"/>
  <date value="2022-01-11T10:00:00+10:00"/>
  <publisher value="HL7"/>
  <description value="Defines profiles used with or related to the Requirements resource"/>
</ImplementationGuide>

Resource Packs

list-Requirements-packs.xml

<?xml version="1.0" encoding="UTF-8"?>

<List xmlns="http://hl7.org/fhir" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://hl7.org/fhir ../../publish/List.xsd">
  <id value="Requirements-packs"/>
  <status value="current"/>
  <mode value="working"/>
  <entry>
    <item>
      <reference value="ImplementationGuide/Requirements-core"/>
    </item>
  </entry>
</List>

Search Parameters

• context — token — A use context assigned to the requirements — (Requirements.useContext.value.ofType(CodeableConcept))
• context-quantity — quantity — A quantity- or range-valued use context assigned to the requirements — (Requirements.useContext.value.ofType(Quantity)) | (Requirements.useContext.value.ofType(Range))
• context-type — token — A type of use context assigned to the requirements — Requirements.useContext.code
• context-type-quantity — composite — A use context type and quantity- or range-based value assigned to the requirements — Requirements.useContext
• context-type-value — composite — A use context type and value assigned to the requirements — Requirements.useContext
• date — date — The requirements publication date — Requirements.date
• description — string — The description of the requirements — Requirements.description
• identifier — token — External identifier for the requirements — Requirements.identifier
• jurisdiction — token — Jurisdiction of the authority that maintains the the requirements — Requirements.jurisdiction
• name — string — Computationally friendly name of the requirements — Requirements.name
• publisher — string — Name of the publisher of the requirements — Requirements.publisher
• status — token — The current status of the requirements — Requirements.status
• title — string — The human-friendly name of the requirements — Requirements.title
• url — uri — The uri that identifies the requirements — Requirements.url
• version — token — The business version of the requirements — Requirements.version
• derived-from — reference — The requirements these are derived from — Requirements.derivedFrom
• actor — reference — An actor these requirements are for — Requirements.actor.reference
• experimental — token — Whether the Requirements is experimental — Requirements.experimental

Full Search Parameters

Examples

• example1 — Requirements-example1
• example2 — Requirements-example2
• requirements-examples-header — requirements-examples-header

Full Examples

Mapping Exceptions

requirements-definition-mapping-exceptions.xml

Divergent Elements

• Definition.url → Requirements.url
  • shortUnmatched | reason=Unknown | pattern=Canonical identifier for this requirements, represented as an absolute URI (globally unique) | resource=Canonical identifier for this Requirements, represented as a URI (globally unique)
  • definitionUnmatched | reason=Unknown | pattern=An absolute URI that is used to identify this requirements when it is referenced in a specification, model, design or an instance; also called its canonical identifier. This SHOULD be globally unique and SHOULD be a literal address at which an authoritative instance of this requirements is (or will be) published. This URL can be the target of a canonical reference. It SHALL remain the same when the requirements is stored on different servers. | resource=An absolute URI that is used to identify this Requirements when it is referenced in a specification, model, design or an instance; also called its canonical identifier. This SHOULD be globally unique and SHOULD be a literal address at which an authoritative instance of this Requirements is (or will be) published. This URL can be the target of a canonical reference. It SHALL remain the same when the Requirements is stored on different servers.
  • commentsUnmatched | reason=Unknown | pattern=Can be a urn:uuid: or a urn:oid: but real http/s: addresses are preferred. Multiple instances may share the same URL if they have a distinct version.

The determination of when to create a new version of a resource (same url, new version) vs. defining a new artifact is up to the author. Considerations for making this decision are found in Technical and Business Versions.

In some cases, the resource can no longer be found at the stated url, but the url itself cannot change. Implementations can use the meta.source element to indicate where the current master source of the resource can be found. | resource=Can be a urn:uuid: or a urn:oid: but real http: addresses are preferred. Multiple instances may share the same URL if they have a distinct version.

The determination of when to create a new version of a resource (same url, new version) vs. defining a new artifact is up to the author. Considerations for making this decision are found in Technical and Business Versions.

In some cases, the resource can no longer be found at the stated url, but the url itself cannot change. Implementations can use the meta.source element to indicate where the current master source of the resource can be found.

• requirementsUnmatched | reason=Unknown | pattern=Allows the requirements to be referenced by a single globally unique identifier. | resource=Allows the Requirements to be referenced by a single globally unique identifier.
• Definition.identifier → Requirements.identifier
  • shortUnmatched | reason=Unknown | pattern=Business identifier for requirements | resource=Additional identifier for the Requirements (business identifier)
  • definitionUnmatched | reason=Unknown | pattern=A formal identifier that is used to identify this requirements when it is represented in other formats, or referenced in a specification, model, design or an instance. | resource=A formal identifier that is used to identify this Requirements when it is represented in other formats, or referenced in a specification, model, design or an instance.
  • commentsUnmatched | reason=Unknown | pattern=Typically, this is used for identifiers that can go in an HL7 V3 II (instance identifier) data type, and can then identify this requirements outside of FHIR, where it is not possible to use the logical URI.
  • requirementsUnmatched | reason=Unknown | pattern=Allows externally provided and/or usable business identifiers to be easily associated with the requirements. | resource=Allows externally provided and/or usable business identifiers to be easily associated with the module.
• Definition.version → Requirements.version
  • shortUnmatched | reason=Unknown | pattern=Business version of the requirements | resource=Business version of the Requirements
  • definitionUnmatched | reason=Unknown | pattern=The identifier that is used to identify this version of the requirements when it is referenced in a specification, model, design or instance. This is an arbitrary value managed by the requirements author and is not expected to be globally unique. For example, it might be a timestamp (e.g. yyyymmdd) if a managed version is not available. There is also no expectation that versions can be placed in a lexicographical sequence. | resource=The identifier that is used to identify this version of the Requirements when it is referenced in a specification, model, design or instance. This is an arbitrary value managed by the Requirements author and is not expected to be globally unique. For example, it might be a timestamp (e.g. yyyymmdd) if a managed version is not available. There is also no expectation that versions can be placed in a lexicographical sequence.
  • commentsUnmatched | reason=Unknown | pattern=There may be different requirementss that have the same url but different versions. The version can be appended to the url in a reference to allow a reference to a particular business version of the requirements with the format. The version SHOULD NOT contain a '#' - see Business Version. | resource=There may be different Requirements instances that have the same identifier but different versions. The version can be appended to the url in a reference to allow a reference to a particular business version of the Requirements with the format [url]|[version]. The version SHOULD NOT contain a '#' - see Business Version.
• Definition.name → Requirements.name
  • shortUnmatched | reason=Unknown | pattern=Name for this requirements (computer friendly) | resource=Name for this Requirements (computer friendly)
  • definitionUnmatched | reason=Unknown | pattern=A natural language name identifying the requirements. This name should be usable as an identifier for the module by machine processing applications such as code generation. | resource=A natural language name identifying the Requirements. This name should be usable as an identifier for the module by machine processing applications such as code generation.
  • commentsUnmatched | reason=Unknown | pattern=The name is not expected to be globally unique. The name should be a simple alphanumeric type no-whitespace name to ensure that it is machine-processing friendly. | resource=The name is not expected to be globally unique. The name should be a simple alphanumeric type name to ensure that it is machine-processing friendly.
  • requirementsUnmatched | reason=Unknown | pattern=Supports code generation. | resource=Support human navigation and code generation.
• Definition.title → Requirements.title
  • shortUnmatched | reason=Unknown | pattern=Name for this requirements (human friendly) | resource=Name for this Requirements (human friendly)
  • definitionUnmatched | reason=Unknown | pattern=A short, descriptive, user-friendly title for the requirements. | resource=A short, descriptive, user-friendly title for the Requirements.
• Definition.derivedFromCanonical → Requirements.derivedFrom
  • missingTypes | reason=Unknown | pattern=canonical(Definition)
  • extraTypes | reason=Unknown
  • shortUnmatched | reason=Unknown | pattern=Based on FHIR protocol or definition | resource=Other set of Requirements this builds on
  • definitionUnmatched | reason=Unknown | pattern=The canonical URL pointing to another FHIR-defined protocol, guideline, orderset or other definition that is adhered to in whole or in part by this definition. | resource=Another set of Requirements that this set of Requirements builds on and updates.
  • requirementsUnmatched | reason=Unknown | pattern=Protocols and order sets may be refinements of more generic protocols and order sets.
• Definition.status → Requirements.status
  • definitionUnmatched | reason=Unknown | pattern=The current state of this requirements. | resource=The status of this Requirements. Enables tracking the life-cycle of the content.
  • commentsUnmatched | reason=Unknown | pattern=A nominal state-transition diagram can be found in the] documentation

Unknown does not represent 'other' - one of the defined statuses must apply. Unknown is used when the authoring system is not sure what the current status is. | resource=Allows filtering of Requirements that are appropriate for use versus not.

See guidance around (not) making local changes to elements here.

• requirementsUnmatched | reason=Unknown | pattern=Enables tracking the lifecycle of the content and filtering of requirementss that are appropriate for use versus not.
• Definition.experimental → Requirements.experimental
  • definitionUnmatched | reason=Unknown | pattern=A Boolean value to indicate that this requirements is authored for testing purposes (or education/evaluation/marketing) and no version of this resource will ever be intended for genuine usage. | resource=A Boolean value to indicate that this Requirements is authored for testing purposes (or education/evaluation/marketing) and no version of this resource will ever be intended for genuine usage.
  • commentsUnmatched | reason=Unknown | pattern=Allows filtering of requirementss that are appropriate for use versus not. | resource=Allows filtering of Requirements that are appropriate for use versus not.. Experimental resources might include example instances in implementation guides, instances created solely for testing purposes, etc
  • requirementsUnmatched | reason=Unknown | pattern=Enables experimental content to be developed following the same lifecycle that would be used for a production-level requirements. | resource=Enables experimental content to be developed following the same lifecycle that would be used for a production-level Requirements.
• Definition.date → Requirements.date
  • definitionUnmatched | reason=Unknown | pattern=The date (and optionally time) when the requirements was last significantly changed. The date must change when the business version changes and it must change if the status code changes. In addition, it should change when the substantive content of the requirements changes. | resource=The date (and optionally time) when the Requirements was published. The date must change when the business version changes and it must change if the status code changes. In addition, it should change when the substantive content of the Requirements changes.
  • commentsUnmatched | reason=Unknown | pattern=The date is often not tracked until the resource is published, but may be present on draft content. Note that this is not the same as the resource last-modified-date, since the resource may be a secondary representation of the requirements. Additional specific dates may be added as extensions or be found by consulting Provenances associated with past versions of the resource. | resource=Note that this is not the same as the resource last-modified-date, since the resource may be a secondary representation of the Requirements. Additional specific dates may be added as extensions or be found by consulting Provenances associated with past versions of the resource.

See guidance around (not) making local changes to elements here.

• Definition.publisher → Requirements.publisher
  • definitionUnmatched | reason=Unknown | pattern=The name of the organization or individual responsible for the release and ongoing maintenance of the requirements. | resource=The name of the organization or individual responsible for the release and ongoing maintenance of the Requirements.
  • commentsUnmatched | reason=Unknown | pattern=Usually an organization but may be an individual. The publisher (or steward) of the requirements is the organization or individual primarily responsible for the maintenance and upkeep of the requirements. This is not necessarily the same individual or organization that developed and initially authored the content. The publisher is the primary point of contact for questions or issues with the requirements. This item SHOULD be populated unless the information is available from context. | resource=Usually an organization but may be an individual. The publisher (or steward) of the Requirements is the organization or individual primarily responsible for the maintenance and upkeep of the Requirements. This is not necessarily the same individual or organization that developed and initially authored the content. The publisher is the primary point of contact for questions or issues with the Requirements. This item SHOULD be populated unless the information is available from context.
  • requirementsUnmatched | reason=Unknown | pattern=Helps establish the "authority/credibility" of the requirements. May also allow for contact. | resource=Helps establish the "authority/credibility" of the Requirements. May also allow for contact.
• Definition.description → Requirements.description
  • summary | reason=Unknown | pattern=true
  • definitionUnmatched | reason=Unknown | pattern=A free text natural language description of the requirements from a consumer's perspective. | resource=A free text natural language description of the requirements.
  • commentsUnmatched | reason=Unknown | pattern=This description can be used to capture details such as comments about misuse, instructions for clinical use and interpretation, literature references, examples from the paper world, etc. It is not a rendering of the requirements as conveyed in the 'text' field of the resource itself. This item SHOULD be populated unless the information is available from context. | resource=This description can be used for a general description of the requirements, and which covers why it was defined.
• Definition.useContext → Requirements.useContext
  • definitionUnmatched | reason=Unknown | pattern=The content was developed with a focus and intent of supporting the contexts that are listed. These contexts may be general categories (gender, age, ...) or may be references to specific programs (insurance plans, studies, ...) and may be used to assist with indexing and searching for appropriate requirementss. | resource=The content was developed with a focus and intent of supporting the contexts that are listed. These contexts may be general categories (gender, age, ...) or may be references to specific programs (insurance plans, studies, ...) and may be used to assist with indexing and searching for appropriate Requirements instances.
  • commentsUnmatched | reason=Unknown | pattern=When multiple useContexts are specified, there is no expectation that all or even any of the contexts apply. | resource=When multiple useContexts are specified, there is no expectation that all or any of the contexts apply.
• Definition.jurisdiction → Requirements.jurisdiction
  • shortUnmatched | reason=Unknown | pattern=Intended jurisdiction for requirements (if applicable) | resource=Jurisdiction of the authority that maintains the Requirements (if applicable)
  • definitionUnmatched | reason=Unknown | pattern=A legal or geographic region in which the requirements is intended to be used. | resource=A legal or geographic region in which the authority that maintains the resource is operating. In general, the jurisdiction is also found in the useContext. The useContext may reference additional jurisdictions because the defining jurisdiction does not necessarily limit the jurisdictions of use.
  • commentsUnmatched | reason=Unknown | pattern=It may be possible for the requirements to be used in jurisdictions other than those for which it was originally designed or intended

DEPRECATION NOTE: For consistency, implementations are encouraged to migrate to using the new 'jurisdiction' code in the useContext element. (I.e. useContext.code indicating http://terminology.hl7.org/CodeSystem/usage-context-type#jurisdiction and useContext.valueCodeableConcept indicating the jurisdiction.). | resource=It may be possible for the Requirements to be used in jurisdictions other than those for which it was originally designed or intended

DEPRECATION NOTE: For consistency, implementations are encouraged to migrate to using the new 'jurisdiction' code in the useContext element. (I.e. useContext.code indicating http://terminology.hl7.org/CodeSystem/usage-context-type#jurisdiction and useContext.valueCodeableConcept indicating the jurisdiction.).

• Definition.purpose → Requirements.purpose
  • shortUnmatched | reason=Unknown | pattern=Why this requirements is defined | resource=Why this Requirements is defined
  • definitionUnmatched | reason=Unknown | pattern=Explanation of why this requirements is needed and why it has been designed as it has. | resource=Explanation of why this Requirements is needed and why it has been designed as it has.
  • commentsUnmatched | reason=Unknown | pattern=This element does not describe the usage of the requirements. Instead, it provides traceability of ''why'' the resource is either needed or ''why'' it is defined as it is. This may be used to point to source materials or specifications that drove the structure of this requirements. | resource=This element does not describe the usage of the Requirements. Instead, it provides traceability of ''why'' the resource is either needed or ''why'' it is defined as it is. This may be used to point to source materials or specifications that drove the structure of this Requirements.
• Definition.copyright → Requirements.copyright
  • definitionUnmatched | reason=Unknown | pattern=A copyright statement relating to the requirements and/or its contents. Copyright statements are notices of intellectual property ownership and can include restrictions on the use and publishing of the requirements. | resource=A copyright statement relating to the Requirements and/or its contents. Copyright statements are notices of intellectual property ownership and can include restrictions on the use and publishing of the Requirements.
  • requirementsUnmatched | reason=Unknown | pattern=Consumers of the requirements must be able to determine any legal restrictions on the use of the artifact and/or its content. | resource=Consumers must be able to determine any legal restrictions on the use of the Requirements.

Unmapped Elements

• Definition.approvalDate — Unknown
• Definition.effectivePeriod — Unknown
• Definition.product — Unknown
• Definition.code — Unknown
• Definition.lastReviewDate — Unknown
• Definition.subject — Unknown
• Definition.derivedFromUri — Unknown
• Definition.performerType — Unknown
• Definition.partOf — Unknown
• Definition.topic — Unknown

requirements-fivews-mapping-exceptions.xml

Unmapped Elements

• FiveWs.what — Not relevant for this resource
• FiveWs.author — Not relevant for this resource
• FiveWs.actor — Not relevant for this resource
• FiveWs.cause — Not relevant for this resource
• FiveWs.where — Not relevant for this resource
• FiveWs.context — Not relevant for this resource
• FiveWs.init — Not relevant for this resource
• FiveWs.grade — Not relevant for this resource
• FiveWs.planned — Not relevant for this resource
• FiveWs.done — Not relevant for this resource
• FiveWs.subject — Not relevant for this resource