NHSDigital-CapabilityStatement-1

An absolute URI that is used to identify this capability statement when it is referenced in a specification, model, design or an instance. This SHALL be a URL, SHOULD be globally unique, and SHOULD be an address at which this capability statement is (or will be) published. The URL SHOULD include the major version of the capability statement. For more information see Technical and Business Versions.

Allows the capability statement to be referenced by a single globally unique identifier.

This version of the profile requires a URL element.

FHIR-CONF-01: All FHIR ReST endpoints MUST publish their conformance

FHIR-VER-02: HL7 FHIR version in FHIR Endpoint URL

FHIR-VER-04: Major Profile Version in Resource ID

Capability statements of kind 'requirements' example: https://fhir.nhs.uk/STU3/CapabilityStatement/ODSAPI-CapabilityStatement-1

Capability statements of kind 'instance' example [TBC]: https://directory.spineservices.nhs.uk /STU3/SpineDirectory-CapabilityStatement-1

The identifier that is used to identify this version of the capability statement when it is referenced in a specification, model, design or instance. This is an arbitrary value managed by the capability statement 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.

Capability statements of kind 'requirements' MUST support the version element.

FHIR-VER-05: Minor and Patch Profile Version will use FHIR versioning

The version element within the resource will contain the full semantic version of the resource, and will look like this: <version value=”1.1.3”/>

There may be different capability statement instances that have the same identifier but different versions. The version can be appended to the url in a reference to allow a refrence to a particular business version of the capability statement with the format [url]|[version].

A natural language name identifying the capability statement. This name should be usable as an identifier for the module by machine processing applications such as code generation.

Support human navigation and code generation.

This version of the profile requires a name element.

FHIR-VER-04: Major Profile Version in Resource ID

National NHS Digital capability statements MUST support the NHS Digital agreed pattern. Refer to:

• NHS-Digital-FHIR-Artefact-Naming.docx

The name is not expected to be globally unique. The name should be a simple alpha-numeric type name to ensure that it is computable friendly.

A short, descriptive, user-friendly title for the capability statement.

This name does not need to be machine-processing friendly and may contain punctuation, white-space, etc.

The status of this capability statement. Enables tracking the life-cycle of the content.

For all under development CapabilityStatement profiles the status MUST be 'draft'.

NB: This is not intended for use with actual conformance statements (instances)

Allows filtering of capability statements that are appropriate for use vs. not.
This is labeled as "Is Modifier" because applications should not use a retired capability statement without due consideration. This is not intended for use with actual capability statements, but where capability statements are used to describe possible or desired systems.

A boolean value to indicate that this capability statement is authored for testing purposes (or education/evaluation/marketing), and is not intended to be used for genuine usage.

Enables experimental content to be developed following the same lifecycle that would be used for a production-level capability statement.

Allows filtering of capability statement that are appropriate for use vs. not. This is labeled as "Is Modifier" because applications should not use an experimental capability statement in production.

The date (and optionally time) when the capability statement was published. The date must change if and 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 capability statement changes.

Note that this is not the same as the resource last-modified-date, since the resource may be a secondary representation of the capability statement. Additional specific dates may be added as extensions or be found by consulting Provenances associated with past versions of the resource.

The name of the individual or organization that published the capability statement.

Helps establish the "authority/credibility" of the capability statement. May also allow for contact.

This version of the profile requires a publisher element.

National Spine REST API capability statements of kind ‘requirements’ and server ‘instances’ MUST populate this element with ‘NHS Digital’.

MUST be populated with the name of the individual or organization that published the capability statement.

Usually an organization, but may be an individual. The publisher (or steward) of the capability statement is the organization or individual primarily responsible for the maintenance and upkeep of the capability statement. 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 capability statement. This item SHOULD be populated unless the information is available from context.

The name of an individual to contact.

This version of the profile requires a contact name element.

National capability statements of kind ‘requirements’ MUST populate this element with ‘Interoperability Team’.

Capability statements of kind ‘instance’ SHOULD populate this element with relevant service desk details.

Telecommunications form for contact point - what communications system is required to make use of the contact.

Note that FHIR strings may not exceed 1MB in size

The actual contact point details, in a form that is meaningful to the designated communication system (i.e. phone number or email address).

Need to support legacy numbers that are not in a tightly controlled format.

Additional text data such as phone extension numbers, or notes about use of the contact are sometimes included in the value.

Identifies the purpose for the contact point.

Need to track the way a person uses this contact, so a user can choose which is appropriate for their purpose.

This is labeled as "Is Modifier" because applications should not mistake a temporary or old contact etc.for a current/permanent one. Applications can assume that a contact is current unless it explicitly says that it is temporary or old.

Specifies a preferred order in which to use a set of contacts. Contacts are ranked with lower values coming before higher values.

Note that rank does not necessarily follow the order in which the contacts are represented in the instance.

The start of the period. The boundary is inclusive.

If the low element is missing, the meaning is that the low boundary is not known.

The end of the period. If the end of the period is missing, it means that the period is ongoing. The start may be in the past, and the end date in the future, which means that period is expected/planned to end at that time.

The high value includes any matching date/time. i.e. 2012-02-03T10:00:00 is in a period that has a end value of 2012-02-03.

If the end of the period is missing, it means that the period is ongoing

A free text natural language description of the capability statement from a consumer's perspective. Typically, this is used when the capability statement describes a desired rather than an actual solution, for example as a formal expression of requirements as part of an RFP.

Capability statements of kind ‘requirements’ MUST support the description element.

The description of the capability statement will be described and published within the NHS Digital Jekyll API Implementation Guide publication.

This description can be used to capture details such as why the capability statement was built, comments about misuse, instructions for clinical use and interpretation, literature references, examples from the paper world, etc. It is not a rendering of the capability statement as conveyed in the 'text' field of the resource itself. This item SHOULD be populated unless the information is available from context (e.g. the language of the profile is presumed to be the predominant language in the place the profile was created). This does not need to be populated if the description is adequately implied by the software or implementation details.

NHS Digital Business Rules: Conformance statements of kind 'requirements' MUST support the description element. The description of the capability statement will be described and published within the NHS Digital Jekyll API Implementation Guide publication.

The identification of the code system that defines the meaning of the symbol in the code.

Need to be unambiguous about the source of the definition of the symbol.

The URI may be an OID (urn:oid:...) or a UUID (urn:uuid:...). OIDs and UUIDs SHALL be references to the HL7 OID registry. Otherwise, the URI should come from HL7's list of FHIR defined special URIs or it should de-reference to some definition that establish the system clearly and unambiguously.

The version of the code system which was used when choosing this code. Note that a well-maintained code system does not need the version reported, because the meaning of codes is consistent across versions. However this cannot consistently be assured. and when the meaning is not guaranteed to be consistent, the version SHOULD be exchanged.

Where the terminology does not clearly define what string should be used to identify code system versions, the recommendation is to use the date (expressed in FHIR date format) on which that version was officially published as the version date.

A symbol in syntax defined by the system. The symbol may be a predefined code or an expression in a syntax defined by the coding system (e.g. post-coordination).

Need to refer to a particular code in the system.

Note that FHIR strings may not exceed 1MB in size

A representation of the meaning of the code in the system, following the rules of the system.

Need to be able to carry a human-readable meaning of the code for readers that do not know the system.

Note that FHIR strings may not exceed 1MB in size

Indicates that this coding was chosen by a user directly - i.e. off a pick list of available items (codes or displays).

This has been identified as a clinical safety criterium - that this exact system/code pair was chosen explicitly, rather than inferred by the system based on some rules or language processing.

Amongst a set of alternatives, a directly chosen code is the most appropriate starting point for new translations. There is some ambiguity about what exactly 'directly chosen' implies, and trading partner agreement may be needed to clarify the use of this element and its consequences more completely.

The identification of the code system that defines the meaning of the symbol in the code.

Need to be unambiguous about the source of the definition of the symbol.

The URI may be an OID (urn:oid:...) or a UUID (urn:uuid:...). OIDs and UUIDs SHALL be references to the HL7 OID registry. Otherwise, the URI should come from HL7's list of FHIR defined special URIs or it should de-reference to some definition that establish the system clearly and unambiguously.

The version of the code system which was used when choosing this code. Note that a well-maintained code system does not need the version reported, because the meaning of codes is consistent across versions. However this cannot consistently be assured. and when the meaning is not guaranteed to be consistent, the version SHOULD be exchanged.

Where the terminology does not clearly define what string should be used to identify code system versions, the recommendation is to use the date (expressed in FHIR date format) on which that version was officially published as the version date.

A symbol in syntax defined by the system. The symbol may be a predefined code or an expression in a syntax defined by the coding system (e.g. post-coordination).

Need to refer to a particular code in the system.

Note that FHIR strings may not exceed 1MB in size

A representation of the meaning of the code in the system, following the rules of the system.

Need to be able to carry a human-readable meaning of the code for readers that do not know the system.

Note that FHIR strings may not exceed 1MB in size

Indicates that this coding was chosen by a user directly - i.e. off a pick list of available items (codes or displays).

This has been identified as a clinical safety criterium - that this exact system/code pair was chosen explicitly, rather than inferred by the system based on some rules or language processing.

Amongst a set of alternatives, a directly chosen code is the most appropriate starting point for new translations. There is some ambiguity about what exactly 'directly chosen' implies, and trading partner agreement may be needed to clarify the use of this element and its consequences more completely.

A human language representation of the concept as seen/selected/uttered by the user who entered the data and/or which represents the intended meaning of the user.

The codes from the terminologies do not always capture the correct meaning with all the nuances of the human using them, or sometimes there is no appropriate code at all. In these cases, the text is used to capture the full meaning of the source.

Very often the text is the same as a displayName of one of the codings.

Explaination of why this capability statement is needed and why it has been designed as it has.

This element does not describe the usage of the capability statement 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 capability statement.

A copyright statement relating to the capability statement and/or its contents. Copyright statements are generally legal restrictions on the use and publishing of the capability statement.

Consumers must be able to determine any legal restrictions on the use of the capability statement and/or its content.

All NHS Digital national REST API Capability statements of kind ‘requirements’ and server 'instances' MUST support the copyright element.

Example: Copyright © 2017 NHS Digital.

Systems are not required to have markdown support, and there is considerable variation in markdown syntax, so the text should be readable without markdown processing. The preferred markdown syntax is described here: http://daringfireball.net/projects/markdown/syntax (and tests here: http://daringfireball.net/projects/downloads/MarkdownTest_1.0.zip)

The way that this statement is intended to be used, to describe an actual running instance of software, a particular product (kind not instance of software) or a class of implementation (e.g. a desired purchase).

Allow searching the 3 modes.

The 'requirements' code MUST be used for all capability statements profiles defined by national API IGs - it sets out what systems should do rather than what a particular system does do.

A server implementation MUST use the code ‘instance’. It describes what a particular system does do.

The 'instance' code MUST be used when a capability statement describes the capabilities of a deployed and configured solution available at a particular access point or set of access points. The statement describes exactly how to interface with that deployed solution and thus provides for a degree of self-configuration of software solutions.

The capabilities of a deployed 'instance' can be conformance tested against the expected capabilities of a national API 'requirements' IG.

Note that FHIR strings may not exceed 1MB in size

Reference to a canonical URL of another CapabilityStatement that this software implements or uses. This capability statement is a published API description that corresponds to a business service. The rest of the capability statement does not need to repeat the details of the referenced resource, but can do so.

A server 'instance' of a national Capability Statement MUST reference the ‘requirements’ CapabilityStatement. [TBC]

HL7 defines the following Services: Terminology Service.

Many Implementation Guides define additional services.

Name software is known by.

Note that FHIR strings may not exceed 1MB in size

The version identifier for the software covered by this statement.

If possible, a version should be specified, as statements are likely to be different for different versions of software.

Date this version of the software was released.

Information about the specific installation that this capability statement relates to.

Note that FHIR strings may not exceed 1MB in size

An absolute base URL for the implementation. This forms the base for REST interfaces as well as the mailbox and document interfaces.

see http://en.wikipedia.org/wiki/Uniform_resource_identifier

The version of the FHIR specification on which this capability statement is based.

STU3 CapabilityStatements resources MUST support "3.0.1".

RFC 4122

A code that indicates whether the application accepts unknown elements or extensions when reading resources.

Both national 'requirements' profiles and server 'instance' profiles MUST use the code ‘no’.

Unknown elements in a resource can only arise as later versions of the specification are published, because this is the only place where such elements can be defined. Hence accepting unknown elements is about inter-version compatibility.

Applications are recommended to accept unknown extensions and elements ('both'), but this is not always possible.

A list of the formats supported by this implementation using their content types.

National REST APIs MUST support one of JSON, XML or both formats.

This element MUST be populated to meet this requirement.

Spine mime-type conformance: • Spine SHALL support the formal mime-type for STU3 XML + JSON FHIR resources: ‘application/fhir+xml’ or ‘application/fhir+json’ • Spine MAY support the the formal mime-types for DSTU2 XML +JSON FHIR resources: ‘application/xml+fhir’ or ‘application/json+fhir’ • Spine MAY support generic mime-types e.g. ‘text/html’, ‘xml’, ‘text/xml’, ‘application/xml’, ‘json’ and ‘application/json’ Spine SHOULD support the FHIR STU3 implementation note: https://www.hl7.org/fhir/http.html#mime-type

"xml", "json" and "ttl" are allowed, which describe the simple encodings described in the specification (and imply appropriate bundle support). Otherwise, mime types are legal here.

A list of the patch formats supported by this implementation using their content types.

NHS Digital Business Rules:

National REST APIs MAY support the patch operation.

At present, the patch mime types application/json-patch+json and application/xml-patch+xml are legal. Generally, if a server supports PATCH, it would be expected to support the patch formats and match the formats it supports, but this is not always possible or necessary.

A list of implementation guides that the server does (or should) support in their entirety.

A national 'requirements' profile MUST link to the NHS Developer site for FINAL releases of national API IG specifications.

A server 'instance' MUST list the implementation guides that the server does (or should) support in their entirety.

see http://en.wikipedia.org/wiki/Uniform_resource_identifier

Optional Extension Element - found in all resources.

NHS Digital Business Rules:

The ‘nhsdigital-profile-link-1’ extension in the STU3 CapabilityStatement resource links profiles to the resources they are based upon for the purpose of ‘describing’ profile specific capabilties such as specific search criteria or operations which are supported on a profile by profile bases.

There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone.

A reference to a location at which the other resource is found. The reference may be a relative reference, in which case it is relative to the service base URL, or an absolute URL that resolves to the location where the resource is found. The reference may be version specific or not. If the reference is not to a FHIR RESTful server, then it should be assumed to be version specific. Internal fragment references (start with '#') refer to contained resources.

Using absolute URLs provides a stable scalable approach suitable for a cloud/web context, while using relative/logical references provides a flexible approach suitable for use when trading across closed eco-system boundaries. Absolute URLs do not need to point to a FHIR RESTful server, though this is the preferred approach. If the URL conforms to the structure "/[type]/[id]" then it should be assumed that the reference is to a FHIR RESTful server.

An identifier for the other resource. This is used when there is no way to reference the other resource directly, either because the entity is not available through a FHIR server, or because there is no way for the author of the resource to convert a known identifier to an actual location. There is no requirement that a Reference.identifier point to something that is actually exposed as a FHIR instance, but it SHALL point to a business concept that would be expected to be exposed as a FHIR instance, and that instance would need to be of a FHIR resource type allowed by the reference.

When an identifier is provided in place of a reference, any system processing the reference will only be able to resolve the identifier to a reference if it understands the business context in which the identifier is used. Sometimes this is global (e.g. a national identifier) but often it is not. For this reason, none of the useful mechanisms described for working with references (e.g. chaining, includes) are possible, nor should servers be expected to be able resolve the reference. Servers may accept an identifier based reference untouched, resolve it, and/or reject it - see CapabilityStatement.rest.resource.referencePolicy.

When both an identifier and a literal reference are provided, the literal reference is preferred. Applications processing the resource are allowed - but not required - to check that the identifier matches the literal reference

Applications converting a logical reference to a literal reference may choose to leave the logical reference present, or remove it.

Plain text narrative that identifies the resource in addition to the resource reference.

This is generally not the same as the Resource.text of the referenced resource. The purpose is to identify what's being referenced, not to fully describe it.

Identifies whether this portion of the statement is describing the ability to initiate or receive restful operations.

This version of the profile MUST support 'server' mode.

The Client mode is out of scope for this version of the profile.

Note that FHIR strings may not exceed 1MB in size

Information about the system's restful capabilities that apply across all applications, such as security.

Note that FHIR strings may not exceed 1MB in size

Server adds CORS headers when responding to requests - this enables javascript applications to use the server.

This version of the profile MUST support 'cors' Boolean element.

All National API FHIR servers SHOULD support CORS.

CORS support is highly recommended - mandatory if using SMART on FHIR.

The easiest CORS headers to add are Access-Control-Allow-Origin: * & Access-Control-Request-Method: GET, POST, PUT, DELETE. All servers SHOULD support CORS.

The identification of the code system that defines the meaning of the symbol in the code.

Need to be unambiguous about the source of the definition of the symbol.

The URI may be an OID (urn:oid:...) or a UUID (urn:uuid:...). OIDs and UUIDs SHALL be references to the HL7 OID registry. Otherwise, the URI should come from HL7's list of FHIR defined special URIs or it should de-reference to some definition that establish the system clearly and unambiguously.

The version of the code system which was used when choosing this code. Note that a well-maintained code system does not need the version reported, because the meaning of codes is consistent across versions. However this cannot consistently be assured. and when the meaning is not guaranteed to be consistent, the version SHOULD be exchanged.

Where the terminology does not clearly define what string should be used to identify code system versions, the recommendation is to use the date (expressed in FHIR date format) on which that version was officially published as the version date.

A symbol in syntax defined by the system. The symbol may be a predefined code or an expression in a syntax defined by the coding system (e.g. post-coordination).

Need to refer to a particular code in the system.

Note that FHIR strings may not exceed 1MB in size

A representation of the meaning of the code in the system, following the rules of the system.

Need to be able to carry a human-readable meaning of the code for readers that do not know the system.

Note that FHIR strings may not exceed 1MB in size

Indicates that this coding was chosen by a user directly - i.e. off a pick list of available items (codes or displays).

This has been identified as a clinical safety criterium - that this exact system/code pair was chosen explicitly, rather than inferred by the system based on some rules or language processing.

Amongst a set of alternatives, a directly chosen code is the most appropriate starting point for new translations. There is some ambiguity about what exactly 'directly chosen' implies, and trading partner agreement may be needed to clarify the use of this element and its consequences more completely.

A human language representation of the concept as seen/selected/uttered by the user who entered the data and/or which represents the intended meaning of the user.

The codes from the terminologies do not always capture the correct meaning with all the nuances of the human using them, or sometimes there is no appropriate code at all. In these cases, the text is used to capture the full meaning of the source.

Very often the text is the same as a displayName of one of the codings.

General description of how security works.

Note that FHIR strings may not exceed 1MB in size

Mime type for a certificate.

Note that FHIR strings may not exceed 1MB in size

Actual certificate.

A stream of bytes, base64 encoded

A container for a single allowable parameter combination.

NHS Digital Business Rules:

CapabilityStatement resource search combinations must be specified using the HL7 maintained ‘capabilityStatement -search-parameter-combination’ common extension which is a container for a single allowable parameter combination.

The extension supports required and optional parameter combinations.

If a search combination is specified, clients should expect that they must submit that required combination or the search will be unsuccesful.

If multiple search parameter combinations are specified, a client may pick between them, and supply the minimal required parameters for any of the combinations.

There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone.

A type of resource exposed via the restful interface.

Note that FHIR strings may not exceed 1MB in size

A reference to a location at which the other resource is found. The reference may be a relative reference, in which case it is relative to the service base URL, or an absolute URL that resolves to the location where the resource is found. The reference may be version specific or not. If the reference is not to a FHIR RESTful server, then it should be assumed to be version specific. Internal fragment references (start with '#') refer to contained resources.

Using absolute URLs provides a stable scalable approach suitable for a cloud/web context, while using relative/logical references provides a flexible approach suitable for use when trading across closed eco-system boundaries. Absolute URLs do not need to point to a FHIR RESTful server, though this is the preferred approach. If the URL conforms to the structure "/[type]/[id]" then it should be assumed that the reference is to a FHIR RESTful server.