SequoiaProjectHealthcareDirectoryImplementationGuideSTU3 - Local Development build (v0.0.1). See the Directory of published versions
Carequality Usage Guidelines
Previous Page - Directory Document Semantics
Background
The Carequality Directory uses the FHIR Organization resource to represent all types of non-person entities involved in exchange activities. Therefore, Carequality Implementers MUST represent themselves and any entities participating in exchange through their implementation as Organization resources, with specific field requirements further outlined in this specification.
All Carequality Implementer entities in the directory MUST have executed the Carequality Connected Agreement.
All Carequality Connection entities in the directory MUST have a legally binding obligation to the Carequality Connection Terms, ultimately enforced through the parent Carequality Implementer entity in the directory.
Data Quality
- Implementers publishing directory addresses SHOULD check the address to ensure high quality data that is complete, accurate, formatted correctly and is machine parseable.
- Use USPS formatting rules.
- Be compatible with the Google Maps API (which is used to geoencode and display an interactive map of directory locations).
Contacts (Organizational-Level Objects)
Required/Optional/Conditional
Required for all Carequality Implementers
Optional for Carequality Connections
Organization Name Aliases
The directory Organization name aliases values are optional. If provided, the field may repeat. If the value repeats in the Excel spreadsheet, the multiple entires should be quoted strings using standard (non-typesetting) straight double quote characters (“), separated by comma characters. Embedded quotes should be escaped if needed using a backslash double quote syntax ("). The repeating values should be placed in a single cell of the Excel spreadsheet. If the there is no alias value, the Excel file must have an empty cell (nil). If there is a single value, then the string should not be quoted.
Hierarchy
Carequality Implementers
Above
MUST NOT have a parent Organization entities in the directory.
Below
MAY have zero or more children Carequality Connection entities in the directory.
Carequality Connections
Above
MUST have a parent Organization entity in the directory. The parent Organization can be either a Carequality Connection or a Carequality Implementer.
Below
MAY have zero or more children Carequality Connection Organizational entities in the directory.
Initiator Organizations
The various identifier fields (other than HCID) populated by the ultimate initiator SHOULD use the most specific identifiers possible with the exception that returned HCID SHOULD specify the scope of the entity to which the patient’s data will be shared for the current disclosure.
The “ultimate initiator” is the person or system that originated the message transaction. A non-normative example is a human clinician that queries an HIE via an EMR.
All initiators MUST have an entry in the directory.
Responding Organization
Organizations with Endpoints published in the directory MUST return information for any of that Organizations children within the directory hierarchy.
HomeCommunity IDs (HCIDs)
The Org-Identifier must contain the Organizations Home Comunity OID, in the “urn” format of
urn:oid:######, where the text “urn:oid:” is a constant value, and the text “######” is replaced by the dotted decimal format of a globally unique ISO/IEC Object IDentifier (OID).
Each Organization (HCID) MUST be globally unique.
Each query responder MUST return the most specific HCIDs possible for those entity, or entities, that are represented in the response.
Non-normative guidance: Each query initiator SHOULD target the most specific HCID possible in order to satisfy its query scope.
If a given Organization has two different contractual “paths” to provide (or consume) authorized Carequality services, then that Organization MUST have two different HCIDs, one per path, and that organization MUST have two different “paths” in the directory. For example: One Carequality Connection Organization that uses two different Carequality Implementer Organizations to provide for different Carequality Use Cases.
Enforced Value Sets
- Enforced Value Sets
- Org-CarequalityType
- FHIR resource
- N/A (Extension)
- Required/Optional/Conditional
- Required for all Carequality Implementers
- Required for all Carequality Connections
- Value set
- Implementer
1. Connection
1. Nulls not allowed
- Org-Address (Organization-Level Objects)
- General rules
- Required/Optional/Conditional
1. Organizational addresses MUST be specified
- United States of America (USA)
1. All USA state, territory, district, military and possession addresses MUST follow USPS Postal Addressing Standards.
2. Standard reference
1. United States Postal Service Publication 28 - Postal Addressing Standards
1. https://pe.usps.com/text/pub28/welcome.htm
3. Additional Constraints
1. The USPS format consists of three lines in the address format
- Recipient line
- Delivery address line
- Last Line
- Directory entries MUST use the contact name for the USPS “Recipient line”.
- The USPS “Delivery address” line MUST contain all address information except the “Recipient line”, and except the city, state, zip/postal, and country codes
- The USPS “Alternate location” line MUST not be used
- The Sequoia FHIR based directory MUST use ISO 3166 three letter country codes for all addresses. Non-normative: Country names cannot be listed in full, and they cannot use two letter abbreviations. These constraints are more restrictive than USPS rules. This non-normative reference may be of assistance to implementers: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3
- USPS “General Delivery” address formats MUST NOT be used.
- https://pe.usps.com/text/pub28/28c2_033.htm
- “Indirect” addresses such as US Military AP addresses MAY be used, but will have undefined geocoded latitude and longitude.
- Puerto Rico addresses MUST use the three-line USPS format.
- https://pe.usps.com/text/pub28/28c2_041.htm
- Bahamas
1. In the Bahamas, mail is routed via a Post Office Box, and the concept of delivery to individual homes or addresses does not apply.
2. Sequoia research has not found an authoritative standard for addresses in the Bahamas.
3. Directory entries MUST use the contact name for the USPS “Recipient line”.
4. Non-normative: Implementers may find this source of information to be of use.
1. Universal Postal Union
- https://www.upu.int/en/resources/postcodes/addressing-systems.html
- https://www.upu.int/fileadmin/documentsFiles/activities/addressingUnit/bhsEn.pdf
- See the following sections for more detailed information.
- Bermuda
1. Non-normative: Implementers may find this source of information to be of use.
1. https://www.upu.int/fileadmin/documentsFiles/activities/addressingUnit/bmuEn.pdf
2. All Bermuda addresses published in the directory MUST adhere to Burmuda Postal Office Regulations.
1. See: http://www.bpo.bm/addressing.aspx?itemid=2&activemenu=35&sub=27
2. Caution is advised as the above site does not appear to support HTTPS and thus can be compromised via trivial attacks.
3. Post Office Amendment Regulations 2009
1. http://www.bermudalaws.bm/Laws/Annual%20Laws/2009/Statutory%20Instruments/Post%20Office%20Amendment%20Regulations%202009.pdf
2. Caution is advised as the above site does not appear to support HTTPS and thus can be compromised via trivial attacks.
4. Post Office Regulations 1993
1. See: http://www.bermudalaws.bm/Laws/Consolidated%20Laws/Post%20Office%20Regulations%201933.pdf
2. Caution is advised as the above site does not appear to support HTTPS and thus can be compromised via trivial attacks.
5. Post Office Act 1900 (BR 38/2009)
1. See: http://www.bermudalaws.bm/Laws/Consolidated%20Laws/Post%20Office%20Act%201900.pdf
2. Caution is advised as the above site does not appear to support HTTPS and thus can be compromised via trivial attacks.
6. Postal addresses in Bermuda consist of a 4 character code with an embedded space. Home and business delivery is supported as well as P.O. Box delivery.
7. See the following sections for more detailed information.
- Canada
1. Canadian address MUST follow USPS addressing standards for Canada.
2. Standard reference
1. A32 Canada Only
2. https://pe.usps.com/text/pub28/28apa_005.htm
- Contrary to USPS rules, the Sequoia FHIR based directory MUST use ISO 3166 three letter country codes instead of spelling the country name in full.
- The USPS Canadian address standard utilizes the three line address format.
1. Recipient line
2. Delivery address line
3. Last Line
- The Sequoia FHIR directory MUST use the contact name for the Recipient line.
- Other Countries
1. Countries not specified by this Implementation Guide MUST NOT be published in the directory.
2. International addresses will be constrained in the future before they are allowed to be published in the directory.
3. International country codes are constrained to using the ISO 3166-1 alpha-3 code system and value set.
- Data Sources
1. Non-normative note: Implementers may find the following publicly available data sets to be of use.
1. See: https://www.geonames.org/countries/
- Org-Address Line
- FHIR resource mapping
- Address.line
- See: https://www.hl7.org/fhir/datatypes-definitions.html#Address.line
- MUST NOT repeat
- Required value
- Nulls not allowed
- Warning not error if conformance rules are not followed
- USA addresses MUST specify the “Delivery address line” in USPS one-line format.
- USPS Address Format
- Outside the USA
1. Bahamas
1. The USPS “Delivery address” line MUST contain all address information except the “Recipient line”, and except the city, state, zip/postal, and country codes
2. The USPS “Alternate location” line MUST not be used
3. Use of USPS “General Delivery” standards MUST NOT be used.
- See: https://pe.usps.com/text/pub28/28c2_033.htm
- The P.O. Box number must be in the following format:
- The text “P.O. Box” followed by
- A single space, a dash and then a single space (e.g. “ - “) followed by
- The official two letter post office abbreviation code (e.g. “AB”) followed by
- The numeric post office box number.
- Example: “P.O. Box GT 1234”
- Canada
- Canadian addresses MUST specify the “Delivery address line” in USPS one-line format.
- Org-City
- FHIR resource mapping
- Address.city
- See: https://www.hl7.org/fhir/datatypes-definitions.html#Address.city
- Required value
- Nulls not allowed
- Error if not correct
- USA addresses MUST use the USPS city code system and value set.
- USPS City Value Set
1. Non-normative note: Implementers may find the following publicly available data set to be of use.
1. See: http://download.geonames.org/export/zip/
- Outside the USA
- Canada
1. Canadian addresses MUST specify the city.
- Bahamas
1. The Bahamas “Locality” MUST be specified in this field.
- Org-State
- FHIR resource mapping
- Address.state
- See: https://www.hl7.org/fhir/datatypes-definitions.html#Address.state
- MUST NOT repeat
- MUST be specified
- Nulls not allowed
- Error if not correct
- USA addresses in the directory MUST be published using the USPS Two Letter Abbreviation Value Set.
- See: https://pe.usps.com/text/pub28/28apb.htm
- Outside the USA
- Canada
1. Canadian Provinces and Territories MUST be published in the directory using the USPS code system and two-letter abbreviation value set for Canadian addresses.
2. See: https://pe.usps.com/text/pub28/28apa_005.htm
- Bahamas
1. The Bahamas “Island” two letter abbreviation MUST be specified in this field.
- Org-ZIP
- FHIR resource mapping
- Address.postalCode
- See: https://www.hl7.org/fhir/datatypes-definitions.html#Address.postalCode
- Mapping to postalCode resources
- Nulls not allowed
- Error if not correct
- USA addresses MUST follow USPS standards.
- See: https://pe.usps.com/text/pub28/28apb.htm
- USPS format
- MAY use zip+4 format
- MUST use at least 5 digit zip code format
- Outside the USA
- Bahamas
1. This field MUST be Null (contain no data) for addresses in the Bahamas.
- Canada
- Canadian postal codes MUST be formatted as per USAP standards with three upper case alphanumeric characters, a space, and then three alphanumeric characters.
- Org-Country
- ISO 3166 Three Letter Code
- See: https://www.hl7.org/fhir/datatypes-definitions.html#Address.country
- Only ISO three letter country codes are allowed in this field
- ISO 3166-1 alpha-3
- Nulls not allowed
- Error if not correct
- This non-normative reference may be of assistance to implementers: See: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3
- All directory entries MUST contain the country field populated with an ISO 3166 three letter country codes instead of spelling the country name in full.
Next Page - Change Log