Generate the TypeScript FHIR Schemas from the Implementation Guides by PSchmiedmayer · Pull Request #47 · SchmiedmayerLab/grove-ts

PSchmiedmayer · 2026-08-20T22:37:03Z

♻️ Current situation & Problem

We need one place to define the FHIR structures exchanged across Grove and a deterministic way to keep every language implementation aligned with that contract. The Grove FHIR Implementation Guides are authoritative: mobile carries the shared exchange contract, while the adapter guides define source-specific claims.

The FHIR types and Zod schemas in packages/fhir were maintained by hand across hundreds of files. That does not scale to the supported surface and cannot reliably prevent TypeScript from diverging from Swift, Kotlin, or the published Implementation Guides.

This change generates the package contracts, measurement catalog, and conformance fixtures from the Implementation Guides. The source archive is checksum-pinned to SchmiedmayerLab/grove-fhir#42 (9c5eff4), which settles the producer contract shared with Swift and Kotlin, so regeneration is reproducible and any drift becomes a failing build. The commits from f350506 onward align this package with it; everything before them is unchanged.

⚙️ Release Notes

Generate the Zod schemas from the FHIR StructureDefinitions and the measurement surfaces from the published catalogs.
Expose source-neutral shared measurements separately from adapter-owned measurements.
Add strict R4 exchange, provider, recording, questionnaire, identity, retraction, and semantic-validation APIs.
Adopt the v0 event, entry-node, and domain-separated HMAC identity contract.
Validate governed Patient references, including protocol-reserved identifier systems and Grove identifier roles.
Preserve provider response bodies as exact application/json payloads and omit release-coupled Coding.version from recording instances.
Preserve HealthKit clinical-record bytes for both DSTU2 and R4 while declaring the source release with the standard versioned FHIR JSON media type.
Generate conformance fixtures deterministically and fail when obsolete generated fixtures remain.
Validate FHIR date and time values at the wire boundary instead of accepting arbitrary strings.

Producer alignment with grove-fhir#42 (f350506 onward):

Identifier systems: deriveOpaqueIdentitySystems derives all twelve deployment identifier systems from one root, key id and epoch. Systems are a branded IdentifierSystem (parseIdentifierSystem).
Record identities: deriveSourceRecordIdentity and deriveProviderRecordIdentity mint output and artifact identities from their record. deriveOpaqueIdentifier no longer accepts the record kinds. The part index is a branded canonical unsigned decimal (parsePartIndex).
Study context: StudyEnrollment (protocolUrl, protocolVersion) bundles ResearchStudy, PlanDefinition and ResearchSubject.
Retries: isSemanticallyEqual decides retry equality over lossless JSON tokens with a dependency-free tokenizer.
Diagnostics: IssueCode is closed to schema codes plus the generated registry codes. Of the 37 former local codes, 21 are registered and 16 folded into existing rules. ProducerDiagnostic carries the registry reason, and isProducerDiagnostic narrows to it. location is optional, so a refusal needs no pointer.
Warnings: Result.warnings uses the mobile-omission.* codes; a source-offset warning names the element in location.
Vocabulary and roles: Writer replaces sourceAuthor. gateway-application is a converter role. The docs recommend a form for application and host device tokens.
Package shape: zod is a peer dependency, and the provider guard moves out of /mobile. A .d.ts surface snapshot sits beside the runtime export snapshot.
Questionnaire languages: language is required on Questionnaires and responses; translations use the standard translation extension and are kept; buildQuestionnaireResponse(input, questionnaire) writes the response language and writes item text and coded answer displays only in the base language. Pair checks report pair-item-text and pair-response-language, and single-resource checks report qg-language-required, gqr-language-required and qg-translation-1, all as QuestionnaireRuleCode.
Dependency advisories: resolve the open advisories (vitest 4.1.11) and drop the two documentation audit exceptions that no longer apply.

Breaking: identifier systems require parseIdentifierSystem. StudyEnrollment.protocol becomes protocolUrl and protocolVersion, and sourceAuthor becomes writer. ProviderOutputCoordinates becomes OutputCoordinates with role and discriminator. Record kinds go through the record identity functions. buildQuestionnaireResponse takes the Questionnaire it answers, and its input drops the questionnaire canonical and item text.

📚 Documentation

The package documentation explains the public TypeScript surface and links to the authoritative Implementation Guides instead of restating version-specific contracts.

✅ Testing

819 unit tests across 31 suites.
Strict ESLint, Prettier, and TypeScript checks.
Deterministic catalog, Zod schema, and 59-resource conformance-fixture regeneration.
Package and browser smoke tests.
Structural and official FHIR R4 Validator conformance for 58 producer resources plus the Questionnaire and QuestionnaireResponse against the exact pinned Implementation Guide commit.
At 2034f2c, locally against the archive fetched and digest-checked from 9c5eff4:
- @schmiedmayerlab/grove-fhir: 1023 tests in 35 suites.
- The workspace tests, release tests and audit script tests.
- Format, lint, typecheck, pack, audit and signature checks.
- Catalog and fixture regeneration: 84 R4 resources.
- Browser and package smoke tests, and the public surface snapshots.
- Structural and official Validator conformance: 59 producer resources plus the Questionnaire and the English and Spanish QuestionnaireResponses.
- Pages build, REUSE and actionlint.