Service Discovery Strategies for the U.S. Healthcare Ecosystem

Executive Summary

Bottom line up front: The United States does not need a single new centralized health directory to solve many service discovery problems. It needs a common, policy-backed way for health care organizations to publish authoritative, machine-readable discovery documents at predictable URLs. The same well-known pattern already used for identity, banking, app links, and security contacts can be adapted for health care to make endpoints, keys, organizational relationships, vetted applications, and directory feeds easier to find and verify.

For government officials and policy makers, the opportunity is practical: standardize the publication point, require participation where federal programs already have leverage, and allow state, federal, and private directories to aggregate self-published records rather than manually reconciling stale information. A standard URL such as /.well-known/ushealthregistry-configuration could become a low-cost coordination layer across health systems, payers, HIEs, public health agencies, community organizations, and patient-facing apps.

Why it matters: Digital health infrastructure often fails at the basic discovery step — where to find the right endpoint, public key, directory, or policy document. That friction slows patient access, app onboarding, provider directory accuracy, payer-provider exchange, and trust establishment. Discovery documents give each organization a consistent place to publish what it supports and how others can verify it.

Policy lever: CMS, ONC, state Medicaid agencies, and federal grant programs could make publication of a signed health care discovery document a condition of participation, certification, or funding for selected programs. This avoids waiting for every directory problem to be solved through one national database and instead creates a decentralized publication model that can be aggregated and audited.

What this enables: A standardized health discovery document could support SMART on FHIR and FHIR endpoint discovery, public keys for verifying signed software statements, organization and facility relationships, provider directory pointers, payer network information, trusted app lists, Direct and PKI metadata, and HIE or TEFCA-related connection information.

Recommended next step: Convene a federal/state pilot with several health systems, payers, HIEs, patient-facing apps, and public agencies to define the first version of the schema, publish sample .well-known documents, test signed artifacts using JWT/JWKS patterns, and measure improvements in endpoint accuracy, onboarding time, and directory freshness.

Introduction

The notion of discovery is present throughout modern digital systems. In this article, discovery means machine-readable documents published in known locations. This article describes common discovery patterns in use today and outlines ways the same approach could simplify health data exchange logistics.

Well-Known URLs: Into the Great /.well-known/*

For background, RFC 8615 is the "Well-Known Uniform Resource Identifiers (URIs)" specification. In short, it creates a registry mechanism for serving resources from a web server under the root path /.well-known/. A typical pattern looks like:

https://example.com/.well-known/[some_data_or_service]

This approach is widely used in modern systems. Here are a few real-world .well-known examples:

• openid-configuration: The OpenID Connect Discovery endpoint helps relying parties automatically configure an OpenID Connect identity provider (IdP). A key required field in this document is jwks_uri, which identifies the JSON Web Key Set endpoint. The jwks_uri contains the public keys used to verify digitally signed ID tokens from the server. An OpenID Connect ID token is a JSON Web Token (JWT), discussed later in this article. Relying parties (RPs) can use jwks_uri information to verify the presented ID token's digital signature. For example, see Google's OpenID configuration at https://accounts.google.com/.well-known/openid-configuration. An OAuth2 authorization server can publish a similar discovery document at /.well-known/oauth-authorization-server. See the OAuth2 Authorization Server Metadata specification at https://datatracker.ietf.org/doc/html/rfc8414.
• apple-app-site-association: Apple Universal Links use this file to safely open a user directly into a native iOS app instead of a browser.
• acme-challenge/: A directory used by Certificate Authorities (like Let's Encrypt) for HTTP-01 domain validation. You place a specific verification file here to prove you own the domain before an SSL certificate is issued.
• security.txt: A standardized text file that tells security researchers how to report vulnerabilities on your site. For example, Instagram publishes its security endpoint at https://www.instagram.com/.well-known/security.
• smart-configuration: The SMART on FHIR specifications define profiles for FHIR, OAuth, and OpenID Connect. SMART on FHIR defines a configuration file at /.well-known/smart-configuration for FHIR services, alongside FHIR's own discovery format called a CapabilityStatement, covered in the next section.

FHIR Discovery

Fast Healthcare Interoperability Resources (FHIR) is a modern standard for health data exchange created by HL7 International. The FHIR specification covers both data models and server behavior. FHIR servers can publish a discovery endpoint at [baseURL]/metadata. This returns a FHIR CapabilityStatement resource that describes the server's features, rules, and behavior. As is typical for service discovery documents, the metadata endpoint itself does not require client authentication. For example, see:

https://hapi.fhir.org/baseR4/metadata
https://hapi.fhir.org/baseR4/metadata?_format=json

Signed Documents for Discovery

JSON Web Tokens (JWTs) are a widely deployed design pattern used in identity, banking, and authentication.

A Quick Primer on JWT

For readers unfamiliar with JWTs, here is a brief explanation of how they work. If you already know the technology, you may skip this section.

In conversation, people often pronounce JWT as "jot." This pronunciation is called out in the JWT standard.

Think of a JWT as a signed, machine-readable document. A signed JWT is tamper-evident: any change to the document invalidates the signature. The content of the document remains readable in most applications where payload encryption is not enabled. A useful metaphor is a digital notary or an instructor signing completion of a training course.

To illustrate, imagine Alice is an instructor for Training, Inc. Widgets, LLC has hired Training, Inc. to hold emergency preparedness training for its employees. Bob works for Widgets, LLC. Training, Inc. wants to communicate who took the class and what grades they earned to Widgets, Bob, and other appropriate parties.

Because Bob cannot record his own grade, Alice assembles the grade information herself. What counts as input to a JWT? There are predefined standard field names and conventions. We will use those, but we will also add a new field called eprep_training_final_grade to record the final grade. Other information, such as name and date, is included as well.

Bob took the class but did not perform well. His final grade was a dismal 42. Our JWT will create a signed artifact expressing these claims. In JWT terminology, claims are fields in the payload.

Using Training, Inc.'s private key, Alice signs the document input, creating the JWT file as output. She can hand the JWT file to Bob, Widgets, LLC, or others as appropriate. Assuming Training, Inc.'s public key used for grading is discoverable, anyone with the JWT can verify the signature. If Bob's friend Chuck tries to change the final grade from 42 to 92, the attempt fails because any change to the payload invalidates the signature.

Alice provides final grades for all students to Widgets, LLC through a private shared folder. In this scenario, there is one JWT for each student. Training, Inc. publishes its public keys at a jwks_uri so anyone with a JWT can verify the signature. For example, Training, Inc. might make those public keys or certificates available at:

https://grades.training-inc.com/.well-known/certs

A JWT file is much like a tamper-evident file that can be digitally signed. The signature can be verified by anyone who has both the JWT and the signer's public key.

Ideas for Improving the U.S. Healthcare Ecosystem with Discovery Documents

The following examples show how these widespread discovery patterns could be applied directly to the U.S. health care system.

Signed Software Statements for Patient Access

A software statement is a JSON Web Token (JWT) that asserts metadata about client software as a bundle.

A signed software statement contains information needed to dynamically register an application so a patient could potentially use it right away. CMS already maintains a public directory of connected apps. We could imagine CMS publishing this information not only as a human-readable website, but also as a set of machine-readable JWTs. This would help reduce the friction of registering an app separately in every health provider system. This idea was explored about 10 years ago but never gained traction. See Pre-OAuth Entity Trust at https://github.com/transparenthealth/poet for background on that earlier work.

See Josh Mandel's recent thoughtful article, "Software Statements for the Medicare App Library," at https://www.linkedin.com/pulse/software-statements-medicare-app-library-josh-mandel-md-robze/.

This idea for application signing deserves fresh consideration. Let's now consider how discovery documents can be used to support a national health directory.

Discovery Documents as the Backbone of a National Healthcare Directory

What questions should a national health care directory answer?

Here are a few common questions such a directory should support:

• Is this provider organization covered under a given insurance plan (Medicare, Medicaid, or commercial)?
• Is this drug covered under my insurance (and how)?
• Is this individual provider covered by my insurance, and are they accepting new patients?
• When does an individual provider X work at a location Y?
• Where are the electronic endpoints for this provider organization?
• Where are the facility locations?
• What is the contact information for the location and relevant individual contacts?

We can imagine additional questions, but these cover several major pain points. The U.S. health care ecosystem would benefit from its own well-known URI. It could look like this:

https://example.com/.well-known/ushealthregistry-configuration

Its purpose would be to give organizations a standard way to self-publish key information. This approach has several advantages:

• Self-publication: Organizations can publish their own /.well-known/ushealthregistry-configuration file. That file can then serve as a source for a national or state-level aggregated system.
• Low technical barriers: The technology is easy and inexpensive. Organizations need only publish a read-only document to a specific URL.
• Reduced duplication: Electronic endpoint information would no longer need to be stored in multiple disconnected places. This is cleaner than trying to use NPPES for information it was not designed to manage.

What should the layout be for this envisioned ushealthregistry-configuration endpoint? That is a good topic for a separate article, and I would welcome feedback. Below are three examples to further illustrate the concept.

Example 1 – A Health Provider Organization

In this hypothetical example we use Duke Health as a demonstration. (I picked Duke as an example because I live in Durham, North Carolina and receive primary care through Duke Health.)

It could look like this:

https://dukehealth.org/.well-known/ushealthregistry-configuration

What the Duke Health example answers

• What is the official domain for Duke Health? See line 3.
• Where are the electronic endpoints published? See lines 5–12.
• What facilities and suborganizations belong to Duke? See lines 13–14.
• What providers are part of Duke? See lines 15–16.
• Is an insurance plan accepted for a given facility and location? See lines 17–18.
• Which providers work at each facility location? See line 19.
• Where is the FHIR-based provider directory? See line 29.

Other organization types, such as insurance companies, faith-based organizations, commercial labs, and health information exchanges, could use the same document blueprint. Fields would vary by type as appropriate.

Example 2 – A Federal Agency's Registry of Applications

Let's take the example of the Centers for Medicare and Medicaid Services (CMS) creating a discovery document for connected applications. The URL may look like this:

https://connected-health-registry.cms.hhs.gov/.well-known/ushealthregistry-configuration

What the CMS Connected Applications example answers

• What apps have been vetted and digitally signed by CMS? See line 6.
• How do I verify that CMS signed the software statement for an app? See line 5.

This can allow any CMS-aligned network to automate application registration instead of re-vetting every app. For more background on this idea, see "Software Statements for the Medicare App Library" at https://www.linkedin.com/pulse/software-statements-medicare-app-library-josh-mandel-md-robze/.

Example 3 – A State Health Information Exchange (HIE)

Here is another pseudo-example for WVHIN, West Virginia's health information exchange. WVHIN could publish the document at:

https://wvhin.org/.well-known/ushealthregistry-configuration

It shares many features with the earlier examples. Some differences appear in the organization and outbound connection sections.

What the WVHIN example answers

• What is the official domain for WVHIN? See line 3.
• Where are the electronic endpoints published? See lines 5–10.
• Which organizations provide information to this health information exchange? Note the use of the domain as the key.
• What outbound systems are connected to WVHIN? TEFCA and CIVITAS are included as examples.

As these examples show, a machine-readable document at a well-known URL can solve many practical pain points in the U.S. health care ecosystem. Of course, there is still an elephant in the room: how would we get everyone to participate in this approach? Would it take a government mandate? I would say yes.

Conclusion

I hope these ideas spark conversation about how to move U.S. health information infrastructure in a direction that has a real impact on patient care and consumer experience. Discoverable documents at well-known URLs are only one part of the solution, but they are a practical place to start. If you would like to provide feedback or ideas, please email me at alan@transparenthealth.org. Topic ideas for future blog articles are also welcome.

— Alan Viars