Investigate unrecognized and version-specific create targets in Resources

[Gordex2014]

Summary

Opening the Resources page with an unrecognized type query parameter leaves the page without a selected rail item or an explanation. Clicking Create new then opens a draft whose resourceType is copied directly from the URL.

For example:

/ui/resources?type=NoLongerValid

produces:

{
  "resourceType": "NoLongerValid"
}

The editor reports that the resource type and schema are unknown. Save is blocked, so the current evidence does not show invalid data reaching storage.

This behavior should not be treated as a confirmed product defect until HFS defines what counts as a valid create target for each FHIR version.

Why research is required

The FHIR create interaction creates an instance of the type named in POST [base]/[type]. The request body must contain a resource of that type. Servers publish supported resource types and their allowed interactions through CapabilityStatement.rest.resource.

FHIR R4 restricts this field to resource types defined by that version. The current R6 specification also permits additional or custom resource types when the server advertises them and provides their StructureDefinition.

A fix that validates only against HFS's generated core resource list could reject a valid R6 additional resource. Conversely, accepting every URL value creates drafts the editor and REST API cannot process.

Relevant specification sections:

• FHIR R4 create interaction
• FHIR R4 CapabilityStatement resource support
• FHIR R6 CapabilityStatement
• FHIR R6 additional resource definitions

This issue may be closed without code changes if the research establishes that URL passthrough is intentional, the current editor feedback is considered sufficient, and both the UI and REST write paths reliably prevent unsupported resources from being stored.

Environment

• HFS 0.2.1
• FHIR R4
• SQLite
• Spanish locale
• Light theme

Steps to reproduce

1. Open:

   /ui/resources?type=NoLongerValid
   

2. Inspect the resource-type rail and the main workspace.

3. Click Create new.

4. Inspect the generated document and validation messages.

5. Do not submit the document.

Actual behavior

• The URL keeps the unknown type.
• No resource in the rail is selected.
• The page does not explain that the type is unknown or unavailable in the active FHIR version.
• Create new remains enabled.
• The generated draft uses the unknown value as resourceType.
• The editor reports that the resource type and schema cannot be resolved.
• Save validation blocks the document.

Research questions

Before changing code, determine:

1. Whether create targets should come from the active CapabilityStatement, the generated schema catalog, the resource rail, or a combination of these sources.
2. Whether the UI should require a create interaction for the selected resource type.
3. Whether HFS currently supports R6 additional resources or plans to support them.
4. How the editor should obtain schemas for additional resources.
5. Whether a type compiled into the binary but absent from the active FHIR version should be accepted by the REST write path.
6. Whether an unknown deep link should show an error, select a safe default, remove the invalid parameter, or preserve it without enabling creation.
7. Whether the current editor errors provide adequate recovery guidance.
8. Whether a stale URL should behave differently from a manually entered custom type.

Required validation matrix

Scenario	Example	Expected research
Core type shared across versions	Patient	Must remain selectable and creatable when advertised
Type introduced after R4	SubscriptionTopic or ActorDefinition	Compare R4, R4B, R5, and R6
R4 type absent from R6	Media or DocumentManifest	Verify stale links after switching versions
Unknown type	NoLongerValid	Define recovery and create-button behavior
Wrong case	patient	Verify case-sensitive handling
Missing or empty value	No type, or type=	Verify the intended default
Advertised type without create	CapabilityStatement entry lacking create	Creation should not be offered unless intentionally supported
R6 additional resource	Advertised with rest.resource.definition	Determine whether HFS and the editor can support it
Unadvertised additional resource	Custom-looking type absent from capabilities	Define rejection and feedback
Single-version build	R4-only or R6-only binary	Ensure validation does not depend on types from unavailable versions
Multi-version build	R4 and R6 enabled	Validate against the effective request version, not any compiled version

For each applicable row, verify:

• Resource rail selection
• Query-builder target
• Create-button state
• Generated editor document
• Schema resolution
• Save validation
• Direct REST create response
• Storage outcome
• Behavior after changing the selected FHIR version

Current implementation notes

The Resources handler obtains the rail entries for the effective request version, but it copies the query parameter directly into selected_type without checking membership:

crates/ui/src/lib.rs

The template exposes that value to the Create button:

crates/ui/templates/pages/resources.html

The browser creates a document from that value:

crates/ui/assets/resources.js

The save path revalidates the document and blocks submission when the editor reports errors:

crates/ui/assets/resources.js

HFS currently builds its CapabilityStatement from the core resource types for the requested version and advertises create for each listed type:

crates/rest/src/handlers/capabilities.rs

crates/rest/src/handlers/capabilities.rs

The REST extractor accepts resource types found in any FHIR version compiled into the binary. The research should verify that later validation consistently applies the effective request version:

crates/rest/src/fhir_types.rs

crates/rest/src/extractors/fhir_resource.rs

Active UI work

PR #631 expands the resource rail and pre-fills the query builder from the selected type. Its current implementation still derives the selected type from the URL without validating it. The research and any resulting behavior should be applied to that branch before merge or tested immediately after merge.

Current test gap

The existing end-to-end coverage verifies that every type shown in the R4 rail can open a matching draft. It does not cover invalid types, version-specific types, stale links, additional R6 resources, or capabilities that omit create.

crates/ui/e2e/tests/resources.spec.ts

Evidence

Unknown resource type produces no visible page-level warning

Create new carries the unknown type into an invalid draft

Acceptance criteria

• The issue contains a written decision about the source of truth for valid create targets.
• The decision covers R4, R4B, R5, R6, single-version builds, and multi-version builds.
• The decision addresses R6 additional resources and CapabilityStatement.rest.resource.definition.
• The validation matrix records the observed UI and REST behavior.
• No implementation begins before the research determines the intended contract.
• If a code change is required, the UI handles unsupported or version-incompatible types explicitly and consistently.
• If no change is required, the issue documents why URL passthrough is intentional and provides tests proving that unsupported resources cannot reach storage.
• PR feat(ui): unified resource-type rail with an app-shell layout #631 does not make an invalid or stale type appear to be a supported create target.