vet-data-utils-ts 0.4.11 → 0.5.0

package/README.md

@@ -8,22 +8,34 @@ Current surfaces cover the canonical animal-card DID, veterinary summary
 sections, animal-only emergency data, pseudonymous DigitalTwin search input and
 veterinary assistant intents.
 
+FHIR R5 ResearchStudy screens consume the exact 25 resource-specific search
+parameters and the separate associated-party projection from
+`vet-data-utils-ts/research-study`. The complete `associatedParty` object stays
+beside each flat projection so repeating roles, periods and classifiers cannot
+be attributed to the wrong party. A party classifier describes an organization
+category; it never represents Consent or CRUDS authorization. See
+[`docs/research-study-r5-contract.md`](docs/research-study-r5-contract.md).
+
 Reusable Communication screens receive immutable workflow presets from
 `vet-data-utils-ts/communication`. The research-agreement screen is fixed to
 FHIR `notification` plus HL7 v3 ActReason `HRESCH` and does not expose a topic
 picker. See [`docs/communication-inbox-filters.md`](docs/communication-inbox-filters.md).
 
-Veterinary clinical entry screens obtain their allowed coding systems from
-`vet-data-utils-ts/clinical-terminology`. Observations and diagnostic reports
-use LOINC; conditions additionally support ICD-10; SNOMED CT is offered for
-conditions, procedures and allergies only when the selected ISO country is an
-official SNOMED member territory. A returned candidate is never accepted
+Veterinary clinical entry screens obtain browser-safe source identifiers and
+response types from `vet-data-utils-ts/clinical-terminology`; the terminology
+server remains authoritative for each FHIR field. Observations and diagnostic
+reports use LOINC and conditions additionally support ICD-10. SNOMED GPS is
+globally available, while full SNOMED CT and the veterinary extension are
+offered only when the selected ISO country is an official member territory.
+These sources share one FHIR system URI, so portals must preserve the source
+scope returned by the server rather than authorizing from the URI. A returned candidate is never accepted
 automatically: the professional must review and select it before creating the
 FHIR resource. Membership does not replace national edition, attribution or
 affiliate-license requirements. See the [official member list](https://www.snomed.org/members).
 Veterinary immunizations use the distinct WHO ATCvet classification (group QI
-for immunologicals), with SNOMED CT as an additional candidate system where
-territorial use is permitted; ordinary human ATC is not substituted for it.
+for immunologicals); ordinary human ATC is not substituted for it. Veterinary
+allergy product coding may also use ATCvet, while manifestations use an allowed
+SNOMED source.
 
 The deferred spreadsheet shape for member and employee role assignments is
 documented in [`docs/member-import-contract.md`](docs/member-import-contract.md).

package/dist/clinical-terminology.d.ts

@@ -5,6 +5,44 @@ export declare const VeterinaryClinicalTerminologySystems: Readonly<{
     /** WHO Collaborating Centre ATCvet classification, distinct from human ATC. */
     readonly AtcVet: "http://www.whocc.no/atcvet";
 }>;
+/**
+ * Source scopes are authorization/content boundaries, not Coding.system URIs.
+ * GPS, full SNOMED CT and the veterinary extension intentionally share the
+ * canonical SNOMED system URI.
+ * https://www.snomed.org/gps
+ */
+export declare const VeterinaryTerminologySourceScopes: Readonly<{
+    readonly Loinc: "LNC";
+    readonly SnomedGps: "SNOMED_GPS";
+    readonly SnomedCt: "SNOMED_CT";
+    readonly SnomedVeterinary: "SNOMEDCT_VET";
+    readonly Icd10: "ICD10";
+    readonly AtcVet: "ATCVET";
+}>;
+export type VeterinaryTerminologySourceScope = typeof VeterinaryTerminologySourceScopes[keyof typeof VeterinaryTerminologySourceScopes];
+export type VeterinaryTerminologyCapability = Readonly<{
+    type: 'terminology-capability';
+    id: string;
+    attributes: Readonly<{
+        fhirVersion: 'R4';
+        sector: string;
+        jurisdiction: string;
+        resourceType: VeterinaryCodedResourceType;
+        elementPath: string;
+        flatClaims?: Readonly<{
+            code: string;
+            text: string;
+            display: string;
+        }>;
+        defaultSource: VeterinaryTerminologySourceScope;
+        sources: readonly Readonly<{
+            id: VeterinaryTerminologySourceScope;
+            system: string;
+            availability: 'hosted' | 'catalog';
+            globallyUsable: boolean;
+        }>[];
+    }>;
+}>;
 /**
  * ISO 3166-1 alpha-2 territories enumerated by the official SNOMED
  * International member page on 2026-09-05.
@@ -17,4 +55,6 @@ export declare const VeterinaryClinicalTerminologySystems: Readonly<{
  */
 export declare const SnomedMemberCountryCodes: readonly ["AR", "BZ", "CA", "CL", "CR", "SV", "JM", "US", "UY", "AD", "AT", "BE", "HR", "CY", "CZ", "DK", "EE", "FI", "FR", "DE", "HU", "IS", "IE", "IL", "JO", "LV", "LT", "LU", "MT", "NL", "NO", "PT", "QA", "SI", "SA", "SK", "ZA", "ES", "SE", "CH", "AE", "GB", "AU", "BN", "HK", "IN", "ID", "MY", "MN", "NZ", "KR", "SG", "TH", "UZ"];
 export type VeterinaryCodedResourceType = 'Condition' | 'Procedure' | 'DiagnosticReport' | 'Observation' | 'AllergyIntolerance' | 'Immunization';
+/** Resource-level summary; field-level authority comes from the terminology API capability response. */
+export declare function veterinaryTerminologySourcesFor(resourceType: VeterinaryCodedResourceType, countryCode: string): readonly VeterinaryTerminologySourceScope[];
 export declare function veterinaryTerminologySystemsFor(resourceType: VeterinaryCodedResourceType, countryCode: string): readonly string[];

package/dist/clinical-terminology.js

@@ -5,6 +5,20 @@ export const VeterinaryClinicalTerminologySystems = Object.freeze({
     /** WHO Collaborating Centre ATCvet classification, distinct from human ATC. */
     AtcVet: 'http://www.whocc.no/atcvet',
 });
+/**
+ * Source scopes are authorization/content boundaries, not Coding.system URIs.
+ * GPS, full SNOMED CT and the veterinary extension intentionally share the
+ * canonical SNOMED system URI.
+ * https://www.snomed.org/gps
+ */
+export const VeterinaryTerminologySourceScopes = Object.freeze({
+    Loinc: 'LNC',
+    SnomedGps: 'SNOMED_GPS',
+    SnomedCt: 'SNOMED_CT',
+    SnomedVeterinary: 'SNOMEDCT_VET',
+    Icd10: 'ICD10',
+    AtcVet: 'ATCVET',
+});
 /**
  * ISO 3166-1 alpha-2 territories enumerated by the official SNOMED
  * International member page on 2026-09-05.
@@ -22,23 +36,35 @@ export const SnomedMemberCountryCodes = Object.freeze([
     'SI', 'SA', 'SK', 'ZA', 'ES', 'SE', 'CH', 'AE', 'GB',
     'AU', 'BN', 'HK', 'IN', 'ID', 'MY', 'MN', 'NZ', 'KR', 'SG', 'TH', 'UZ',
 ]);
-export function veterinaryTerminologySystemsFor(resourceType, countryCode) {
+/** Resource-level summary; field-level authority comes from the terminology API capability response. */
+export function veterinaryTerminologySourcesFor(resourceType, countryCode) {
     if (resourceType === 'Observation' || resourceType === 'DiagnosticReport') {
-        return [VeterinaryClinicalTerminologySystems.Loinc];
+        return [VeterinaryTerminologySourceScopes.Loinc];
     }
     const permitsSnomed = SnomedMemberCountryCodes.includes(countryCode.toUpperCase());
-    if (resourceType === 'Condition') {
-        return permitsSnomed
-            ? [VeterinaryClinicalTerminologySystems.SnomedCt, VeterinaryClinicalTerminologySystems.Icd10]
-            : [VeterinaryClinicalTerminologySystems.Icd10];
-    }
-    if (resourceType === 'Immunization') {
-        // ATCvet group QI owns veterinary immunological products. SNOMED CT may
-        // additionally express a vaccine concept where territorial use permits it.
-        // https://atcddd.fhi.no/atcvet/atcvet_index/
-        return permitsSnomed
-            ? [VeterinaryClinicalTerminologySystems.AtcVet, VeterinaryClinicalTerminologySystems.SnomedCt]
-            : [VeterinaryClinicalTerminologySystems.AtcVet];
-    }
-    return permitsSnomed ? [VeterinaryClinicalTerminologySystems.SnomedCt] : [];
+    const clinical = permitsSnomed
+        ? [
+            VeterinaryTerminologySourceScopes.SnomedGps,
+            VeterinaryTerminologySourceScopes.SnomedCt,
+            VeterinaryTerminologySourceScopes.SnomedVeterinary,
+        ]
+        : [VeterinaryTerminologySourceScopes.SnomedGps];
+    if (resourceType === 'Condition')
+        return [...clinical, VeterinaryTerminologySourceScopes.Icd10];
+    if (resourceType === 'Immunization')
+        return [VeterinaryTerminologySourceScopes.AtcVet, ...clinical];
+    if (resourceType === 'AllergyIntolerance')
+        return [...clinical, VeterinaryTerminologySourceScopes.AtcVet];
+    return clinical;
+}
+export function veterinaryTerminologySystemsFor(resourceType, countryCode) {
+    const sourceSystem = {
+        [VeterinaryTerminologySourceScopes.Loinc]: VeterinaryClinicalTerminologySystems.Loinc,
+        [VeterinaryTerminologySourceScopes.SnomedGps]: VeterinaryClinicalTerminologySystems.SnomedCt,
+        [VeterinaryTerminologySourceScopes.SnomedCt]: VeterinaryClinicalTerminologySystems.SnomedCt,
+        [VeterinaryTerminologySourceScopes.SnomedVeterinary]: VeterinaryClinicalTerminologySystems.SnomedCt,
+        [VeterinaryTerminologySourceScopes.Icd10]: VeterinaryClinicalTerminologySystems.Icd10,
+        [VeterinaryTerminologySourceScopes.AtcVet]: VeterinaryClinicalTerminologySystems.AtcVet,
+    };
+    return [...new Set(veterinaryTerminologySourcesFor(resourceType, countryCode).map((source) => sourceSystem[source]))];
 }

package/dist/index.d.ts

@@ -7,5 +7,6 @@ export * from './emergency.js';
 export * from './financial.js';
 export * from './iso-jurisdictions.js';
 export * from './organization-application.js';
+export * from './research-study.js';
 export * from './sectors.js';
 export * from './veterinary-sections.js';

package/dist/index.js

@@ -7,5 +7,6 @@ export * from './emergency.js';
 export * from './financial.js';
 export * from './iso-jurisdictions.js';
 export * from './organization-application.js';
+export * from './research-study.js';
 export * from './sectors.js';
 export * from './veterinary-sections.js';

package/dist/research-study.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Browser-safe FHIR R5 ResearchStudy flat-claim contract.
+ *
+ * The standard catalogue is copied from the R5 SearchParameter definitions,
+ * not inferred from similarly named resource elements. In particular, the
+ * `date` SearchParameter targets `ResearchStudy.period`, not the publication
+ * date element. Associated-party projections are indexed separately because
+ * base R5 defines no ResearchStudy party SearchParameter.
+ *
+ * @see https://hl7.org/fhir/R5/researchstudy.html
+ * @see https://hl7.org/fhir/R5/researchstudy-search.html
+ */
+export declare const ResearchStudyR5Version: "5.0.0";
+/**
+ * Immutable codes defined by the FHIR R5 5.0.0 ResearchStudy party-role code
+ * system. The element binding remains extensible; this catalogue is the closed
+ * set a portal may offer by default, not a validator for every conformant
+ * external Coding.
+ *
+ * @see https://hl7.org/fhir/R5/codesystem-research-study-party-role.html
+ */
+export declare const ResearchStudyR5PartyRoleSystem: "http://hl7.org/fhir/research-study-party-role";
+export declare const ResearchStudyR5PartyRoleCodes: readonly ["sponsor", "lead-sponsor", "sponsor-investigator", "primary-investigator", "collaborator", "funding-source", "general-contact", "recruitment-contact", "sub-investigator", "study-director", "study-chair", "irb"];
+export type ResearchStudyR5PartyRoleCode = (typeof ResearchStudyR5PartyRoleCodes)[number];
+export declare const ResearchStudyAssociatedPartyBindings: Readonly<{
+    readonly role: Readonly<{
+        valueSet: "http://hl7.org/fhir/ValueSet/research-study-party-role";
+        strength: "extensible";
+    }>;
+    readonly classifier: Readonly<{
+        valueSet: "http://hl7.org/fhir/ValueSet/research-study-party-organization-type";
+        strength: "example";
+    }>;
+}>;
+export type ResearchStudySearchParameterType = 'composite' | 'date' | 'number' | 'reference' | 'string' | 'token';
+export type ResearchStudyR5SearchParameter = Readonly<{
+    code: string;
+    type: ResearchStudySearchParameterType;
+    expression: string;
+    components: readonly string[];
+}>;
+/** Exact resource-specific SearchParameters published by FHIR R5 5.0.0. */
+export declare const ResearchStudyR5SearchParameterCatalog: readonly ResearchStudyR5SearchParameter[];
+declare const standardSearchClaims: readonly `ResearchStudy.${string}`[];
+declare const associatedPartyClaims: readonly ["ResearchStudy.associated-party-name", "ResearchStudy.associated-party-role", "ResearchStudy.associated-party-period-start", "ResearchStudy.associated-party-period-end", "ResearchStudy.associated-party-classifier", "ResearchStudy.associated-party-party"];
+/**
+ * Governed flat claims for ResearchStudy.
+ *
+ * `standardSearch` contains only official R5 SearchParameters. The
+ * `associatedParty` list is an explicit operational projection of the R5
+ * backbone element; none of those names is advertised as a standard search
+ * parameter and `classifier` never carries CRUD or authorization policy.
+ */
+export declare const ResearchStudyFlatClaimCatalog: Readonly<{
+    standardSearch: readonly `ResearchStudy.${string}`[];
+    associatedParty: readonly ["ResearchStudy.associated-party-name", "ResearchStudy.associated-party-role", "ResearchStudy.associated-party-period-start", "ResearchStudy.associated-party-period-end", "ResearchStudy.associated-party-classifier", "ResearchStudy.associated-party-party"];
+    all: readonly `ResearchStudy.${string}`[];
+}>;
+export type ResearchStudyCoding = Readonly<{
+    system?: string;
+    code?: string;
+    display?: string;
+}>;
+export type ResearchStudyCodeableConcept = Readonly<{
+    coding?: readonly ResearchStudyCoding[];
+    text?: string;
+}>;
+export type ResearchStudyPeriod = Readonly<{
+    start?: string;
+    end?: string;
+}>;
+export type ResearchStudyAssociatedPartyReferenceType = 'Organization' | 'Practitioner' | 'PractitionerRole';
+export type ResearchStudyAssociatedPartyReference = Readonly<{
+    reference: string;
+    type?: ResearchStudyAssociatedPartyReferenceType;
+    display?: string;
+}>;
+export type ResearchStudyAssociatedParty = Readonly<{
+    name?: string;
+    role: ResearchStudyCodeableConcept;
+    period?: readonly ResearchStudyPeriod[];
+    classifier?: readonly ResearchStudyCodeableConcept[];
+    party?: ResearchStudyAssociatedPartyReference;
+}>;
+export type ResearchStudyAssociatedPartyClaimProjection = Readonly<{
+    /** The complete party is retained beside its derived claims to preserve correlation. */
+    associatedParty: ResearchStudyAssociatedParty;
+    claims: Readonly<Record<(typeof associatedPartyClaims)[number], readonly string[]>>;
+}>;
+export type ResearchStudyR5SearchClaim = (typeof standardSearchClaims)[number];
+export type ResearchStudyR5SearchClaims = Readonly<Partial<Record<ResearchStudyR5SearchClaim, readonly string[]>>>;
+/**
+ * Projects the official resource-specific R5 SearchParameters from one native
+ * ResearchStudy into flat `resource.meta.claims`. Composite values use FHIR's
+ * `$` component separator; associatedParty remains a separate projection and
+ * never becomes authorization data.
+ *
+ * @see https://hl7.org/fhir/R5/researchstudy-search.html
+ */
+export declare function projectResearchStudyR5SearchClaims(input: unknown): ResearchStudyR5SearchClaims;
+/**
+ * Normalizes the R5 `associatedParty[]` backbone without flattening parties
+ * into unrelated parallel arrays. This function validates data shape only; it
+ * does not grant study access or interpret classifier values as permissions.
+ */
+export declare function normalizeResearchStudyAssociatedParties(input: unknown): readonly ResearchStudyAssociatedParty[];
+/**
+ * Produces one flat-claim map per associated party. Keeping the normalized
+ * party beside each map preserves the party/role/period/classifier boundary
+ * required when a later Bundle PATCH changes one party.
+ */
+export declare function projectResearchStudyAssociatedPartyClaims(input: unknown): readonly ResearchStudyAssociatedPartyClaimProjection[];
+export {};

package/dist/research-study.js

@@ -0,0 +1,401 @@
+/**
+ * Browser-safe FHIR R5 ResearchStudy flat-claim contract.
+ *
+ * The standard catalogue is copied from the R5 SearchParameter definitions,
+ * not inferred from similarly named resource elements. In particular, the
+ * `date` SearchParameter targets `ResearchStudy.period`, not the publication
+ * date element. Associated-party projections are indexed separately because
+ * base R5 defines no ResearchStudy party SearchParameter.
+ *
+ * @see https://hl7.org/fhir/R5/researchstudy.html
+ * @see https://hl7.org/fhir/R5/researchstudy-search.html
+ */
+export const ResearchStudyR5Version = '5.0.0';
+/**
+ * Immutable codes defined by the FHIR R5 5.0.0 ResearchStudy party-role code
+ * system. The element binding remains extensible; this catalogue is the closed
+ * set a portal may offer by default, not a validator for every conformant
+ * external Coding.
+ *
+ * @see https://hl7.org/fhir/R5/codesystem-research-study-party-role.html
+ */
+export const ResearchStudyR5PartyRoleSystem = 'http://hl7.org/fhir/research-study-party-role';
+export const ResearchStudyR5PartyRoleCodes = Object.freeze([
+    'sponsor',
+    'lead-sponsor',
+    'sponsor-investigator',
+    'primary-investigator',
+    'collaborator',
+    'funding-source',
+    'general-contact',
+    'recruitment-contact',
+    'sub-investigator',
+    'study-director',
+    'study-chair',
+    'irb',
+]);
+export const ResearchStudyAssociatedPartyBindings = Object.freeze({
+    role: Object.freeze({
+        valueSet: 'http://hl7.org/fhir/ValueSet/research-study-party-role',
+        strength: 'extensible',
+    }),
+    classifier: Object.freeze({
+        valueSet: 'http://hl7.org/fhir/ValueSet/research-study-party-organization-type',
+        strength: 'example',
+    }),
+});
+const searchParameter = (code, type, expression, components = []) => Object.freeze({
+    code,
+    type,
+    expression,
+    components: Object.freeze([...components]),
+});
+/** Exact resource-specific SearchParameters published by FHIR R5 5.0.0. */
+export const ResearchStudyR5SearchParameterCatalog = Object.freeze([
+    searchParameter('classifier', 'token', 'ResearchStudy.classifier'),
+    searchParameter('condition', 'token', 'ResearchStudy.condition'),
+    searchParameter('date', 'date', 'ResearchStudy.period'),
+    searchParameter('description', 'string', 'ResearchStudy.description'),
+    searchParameter('eligibility', 'reference', 'ResearchStudy.recruitment.eligibility'),
+    searchParameter('focus-code', 'token', 'ResearchStudy.focus.concept'),
+    searchParameter('focus-reference', 'reference', 'ResearchStudy.focus.reference'),
+    searchParameter('identifier', 'token', 'ResearchStudy.identifier'),
+    searchParameter('keyword', 'token', 'ResearchStudy.keyword'),
+    searchParameter('name', 'string', 'ResearchStudy.name'),
+    searchParameter('objective-description', 'string', 'ResearchStudy.objective.description'),
+    searchParameter('objective-type', 'token', 'ResearchStudy.objective.type'),
+    searchParameter('part-of', 'reference', 'ResearchStudy.partOf'),
+    searchParameter('phase', 'token', 'ResearchStudy.phase'),
+    searchParameter('progress-status-state-actual', 'composite', 'ResearchStudy.progressStatus', [
+        'http://hl7.org/fhir/SearchParameter/ResearchStudy-state',
+        'http://hl7.org/fhir/SearchParameter/ResearchStudy-actual',
+    ]),
+    searchParameter('progress-status-state-period', 'composite', 'ResearchStudy.progressStatus', [
+        'http://hl7.org/fhir/SearchParameter/ResearchStudy-state',
+        'http://hl7.org/fhir/SearchParameter/ResearchStudy-period',
+    ]),
+    searchParameter('progress-status-state-period-actual', 'composite', 'ResearchStudy.progressStatus', [
+        'http://hl7.org/fhir/SearchParameter/ResearchStudy-state',
+        'http://hl7.org/fhir/SearchParameter/ResearchStudy-period',
+        'http://hl7.org/fhir/SearchParameter/ResearchStudy-actual',
+    ]),
+    searchParameter('protocol', 'reference', 'ResearchStudy.protocol'),
+    searchParameter('recruitment-actual', 'number', 'ResearchStudy.recruitment.actualNumber'),
+    searchParameter('recruitment-target', 'number', 'ResearchStudy.recruitment.targetNumber'),
+    searchParameter('region', 'token', 'ResearchStudy.region'),
+    searchParameter('site', 'reference', 'ResearchStudy.site'),
+    searchParameter('status', 'token', 'ResearchStudy.status'),
+    searchParameter('study-design', 'token', 'ResearchStudy.studyDesign'),
+    searchParameter('title', 'string', 'ResearchStudy.title'),
+]);
+const standardSearchClaims = Object.freeze(ResearchStudyR5SearchParameterCatalog.map(parameter => `ResearchStudy.${parameter.code}`));
+const associatedPartyClaims = Object.freeze([
+    'ResearchStudy.associated-party-name',
+    'ResearchStudy.associated-party-role',
+    'ResearchStudy.associated-party-period-start',
+    'ResearchStudy.associated-party-period-end',
+    'ResearchStudy.associated-party-classifier',
+    'ResearchStudy.associated-party-party',
+]);
+/**
+ * Governed flat claims for ResearchStudy.
+ *
+ * `standardSearch` contains only official R5 SearchParameters. The
+ * `associatedParty` list is an explicit operational projection of the R5
+ * backbone element; none of those names is advertised as a standard search
+ * parameter and `classifier` never carries CRUD or authorization policy.
+ */
+export const ResearchStudyFlatClaimCatalog = Object.freeze({
+    standardSearch: standardSearchClaims,
+    associatedParty: associatedPartyClaims,
+    all: Object.freeze([...standardSearchClaims, ...associatedPartyClaims]),
+});
+/**
+ * Projects the official resource-specific R5 SearchParameters from one native
+ * ResearchStudy into flat `resource.meta.claims`. Composite values use FHIR's
+ * `$` component separator; associatedParty remains a separate projection and
+ * never becomes authorization data.
+ *
+ * @see https://hl7.org/fhir/R5/researchstudy-search.html
+ */
+export function projectResearchStudyR5SearchClaims(input) {
+    if (!isRecord(input) || input.resourceType !== 'ResearchStudy') {
+        throw new TypeError('research_study_resource_invalid');
+    }
+    const claims = {};
+    addClaim(claims, 'ResearchStudy.classifier', conceptsValue(input.classifier, 'research_study_classifier_invalid'));
+    addClaim(claims, 'ResearchStudy.condition', conceptsValue(input.condition, 'research_study_condition_invalid'));
+    addClaim(claims, 'ResearchStudy.date', periodValues(input.period, 'research_study_period_invalid'));
+    addClaim(claims, 'ResearchStudy.description', strings(input.description));
+    addClaim(claims, 'ResearchStudy.eligibility', references(input.recruitment, 'eligibility'));
+    addClaim(claims, 'ResearchStudy.focus-code', codeableReferences(input.focus, 'concept'));
+    addClaim(claims, 'ResearchStudy.focus-reference', codeableReferences(input.focus, 'reference'));
+    addClaim(claims, 'ResearchStudy.identifier', identifiers(input.identifier));
+    addClaim(claims, 'ResearchStudy.keyword', conceptsValue(input.keyword, 'research_study_keyword_invalid'));
+    addClaim(claims, 'ResearchStudy.name', strings(input.name));
+    addClaim(claims, 'ResearchStudy.objective-description', backboneStrings(input.objective, 'description'));
+    addClaim(claims, 'ResearchStudy.objective-type', backboneConcepts(input.objective, 'type'));
+    addClaim(claims, 'ResearchStudy.part-of', references(input.partOf));
+    addClaim(claims, 'ResearchStudy.phase', conceptsValue(input.phase, 'research_study_phase_invalid'));
+    const progress = progressStatusValues(input.progressStatus);
+    addClaim(claims, 'ResearchStudy.progress-status-state-actual', progress.stateActual);
+    addClaim(claims, 'ResearchStudy.progress-status-state-period', progress.statePeriod);
+    addClaim(claims, 'ResearchStudy.progress-status-state-period-actual', progress.statePeriodActual);
+    addClaim(claims, 'ResearchStudy.protocol', references(input.protocol));
+    addClaim(claims, 'ResearchStudy.recruitment-actual', nestedNumber(input.recruitment, 'actualNumber'));
+    addClaim(claims, 'ResearchStudy.recruitment-target', nestedNumber(input.recruitment, 'targetNumber'));
+    addClaim(claims, 'ResearchStudy.region', conceptsValue(input.region, 'research_study_region_invalid'));
+    addClaim(claims, 'ResearchStudy.site', references(input.site));
+    addClaim(claims, 'ResearchStudy.status', strings(input.status));
+    addClaim(claims, 'ResearchStudy.study-design', conceptsValue(input.studyDesign, 'research_study_design_invalid'));
+    addClaim(claims, 'ResearchStudy.title', strings(input.title));
+    return Object.freeze(claims);
+}
+/**
+ * Normalizes the R5 `associatedParty[]` backbone without flattening parties
+ * into unrelated parallel arrays. This function validates data shape only; it
+ * does not grant study access or interpret classifier values as permissions.
+ */
+export function normalizeResearchStudyAssociatedParties(input) {
+    if (!Array.isArray(input))
+        throw new TypeError('research_study_associated_parties_invalid');
+    return Object.freeze(input.map((value, index) => normalizeAssociatedParty(value, index)));
+}
+/**
+ * Produces one flat-claim map per associated party. Keeping the normalized
+ * party beside each map preserves the party/role/period/classifier boundary
+ * required when a later Bundle PATCH changes one party.
+ */
+export function projectResearchStudyAssociatedPartyClaims(input) {
+    const parties = normalizeResearchStudyAssociatedParties(input);
+    return Object.freeze(parties.map(party => Object.freeze({
+        associatedParty: party,
+        claims: Object.freeze({
+            'ResearchStudy.associated-party-name': Object.freeze(party.name ? [party.name] : []),
+            'ResearchStudy.associated-party-role': Object.freeze(conceptValues([party.role])),
+            'ResearchStudy.associated-party-period-start': Object.freeze((party.period || []).flatMap(period => period.start ? [period.start] : [])),
+            'ResearchStudy.associated-party-period-end': Object.freeze((party.period || []).flatMap(period => period.end ? [period.end] : [])),
+            'ResearchStudy.associated-party-classifier': Object.freeze(conceptValues(party.classifier || [])),
+            'ResearchStudy.associated-party-party': Object.freeze(party.party ? [party.party.reference] : []),
+        }),
+    })));
+}
+function normalizeAssociatedParty(value, index) {
+    if (!isRecord(value))
+        throw new TypeError(`research_study_associated_party_${index}_invalid`);
+    const role = normalizeConcept(value.role, `research_study_associated_party_${index}_role_required`);
+    const name = optionalString(value.name);
+    const period = value.period === undefined
+        ? undefined
+        : normalizePeriods(value.period, index);
+    const classifier = value.classifier === undefined
+        ? undefined
+        : normalizeConcepts(value.classifier, `research_study_associated_party_${index}_classifier_invalid`);
+    const party = value.party === undefined ? undefined : normalizePartyReference(value.party, index);
+    return Object.freeze({
+        ...(name ? { name } : {}),
+        role,
+        ...(period ? { period } : {}),
+        ...(classifier ? { classifier } : {}),
+        ...(party ? { party } : {}),
+    });
+}
+function normalizeConcepts(value, error) {
+    if (!Array.isArray(value))
+        throw new TypeError(error);
+    return Object.freeze(value.map(item => normalizeConcept(item, error)));
+}
+function normalizeConcept(value, error) {
+    if (!isRecord(value))
+        throw new TypeError(error);
+    const text = optionalString(value.text);
+    let coding;
+    if (value.coding !== undefined) {
+        if (!Array.isArray(value.coding))
+            throw new TypeError(error);
+        coding = Object.freeze(value.coding.map(item => normalizeCoding(item, error)));
+    }
+    if (!text && (!coding || coding.length === 0 || !coding.some(item => item.code)))
+        throw new TypeError(error);
+    return Object.freeze({ ...(coding ? { coding } : {}), ...(text ? { text } : {}) });
+}
+function normalizeCoding(value, error) {
+    if (!isRecord(value))
+        throw new TypeError(error);
+    const system = optionalString(value.system);
+    const code = optionalString(value.code);
+    const display = optionalString(value.display);
+    if (!code && !display)
+        throw new TypeError(error);
+    return Object.freeze({ ...(system ? { system } : {}), ...(code ? { code } : {}), ...(display ? { display } : {}) });
+}
+function normalizePeriods(value, index) {
+    if (!Array.isArray(value))
+        throw new TypeError(`research_study_associated_party_${index}_period_invalid`);
+    return Object.freeze(value.map(item => {
+        if (!isRecord(item))
+            throw new TypeError(`research_study_associated_party_${index}_period_invalid`);
+        const start = optionalString(item.start);
+        const end = optionalString(item.end);
+        if (!start && !end)
+            throw new TypeError(`research_study_associated_party_${index}_period_invalid`);
+        if ((start && !isFhirDateTime(start)) || (end && !isFhirDateTime(end))) {
+            throw new TypeError(`research_study_associated_party_${index}_period_invalid`);
+        }
+        if (start && end && Date.parse(end) < Date.parse(start)) {
+            throw new TypeError(`research_study_associated_party_${index}_period_invalid`);
+        }
+        return Object.freeze({ ...(start ? { start } : {}), ...(end ? { end } : {}) });
+    }));
+}
+function normalizePartyReference(value, index) {
+    const error = `research_study_associated_party_${index}_party_reference_invalid`;
+    if (!isRecord(value))
+        throw new TypeError(error);
+    const reference = optionalString(value.reference);
+    const type = optionalString(value.type);
+    const display = optionalString(value.display);
+    if (!reference)
+        throw new TypeError(error);
+    const allowed = ['Organization', 'Practitioner', 'PractitionerRole'];
+    if (type && !allowed.includes(type))
+        throw new TypeError(error);
+    const relativeType = reference.match(/^(Organization|Practitioner|PractitionerRole|[A-Z][A-Za-z]+)\//)?.[1];
+    if (relativeType && !allowed.includes(relativeType))
+        throw new TypeError(error);
+    return Object.freeze({
+        reference,
+        ...(type ? { type: type } : {}),
+        ...(display ? { display } : {}),
+    });
+}
+function conceptValues(concepts) {
+    return concepts.flatMap(concept => {
+        const coded = (concept.coding || []).flatMap(coding => coding.code
+            ? [`${coding.system ? `${coding.system}|` : ''}${coding.code}`]
+            : []);
+        return coded.length > 0 ? coded : concept.text ? [concept.text] : [];
+    });
+}
+function addClaim(claims, name, values) {
+    if (values.length > 0)
+        claims[name] = Object.freeze([...values]);
+}
+function strings(value) {
+    const result = optionalString(value);
+    return result ? [result] : [];
+}
+function conceptsValue(value, error) {
+    if (value === undefined)
+        return [];
+    const concepts = Array.isArray(value)
+        ? normalizeConcepts(value, error)
+        : Object.freeze([normalizeConcept(value, error)]);
+    return conceptValues(concepts);
+}
+function references(value, nestedKey) {
+    let candidate = value;
+    if (nestedKey) {
+        if (!isRecord(value))
+            return [];
+        candidate = value[nestedKey];
+    }
+    if (candidate === undefined)
+        return [];
+    const items = Array.isArray(candidate) ? candidate : [candidate];
+    return items.flatMap(item => isRecord(item) && optionalString(item.reference) ? [String(item.reference).trim()] : []);
+}
+function identifiers(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new TypeError('research_study_identifier_invalid');
+    return value.flatMap(item => {
+        if (!isRecord(item))
+            throw new TypeError('research_study_identifier_invalid');
+        const system = optionalString(item.system);
+        const identifier = optionalString(item.value);
+        return identifier ? [`${system ? `${system}|` : ''}${identifier}`] : [];
+    });
+}
+function periodValues(value, error) {
+    if (value === undefined)
+        return [];
+    if (!isRecord(value))
+        throw new TypeError(error);
+    const start = optionalString(value.start);
+    const end = optionalString(value.end);
+    if ((start && !isFhirDateTime(start)) || (end && !isFhirDateTime(end)))
+        throw new TypeError(error);
+    return [start, end].filter((item) => Boolean(item));
+}
+function codeableReferences(value, key) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new TypeError('research_study_focus_invalid');
+    return value.flatMap(item => {
+        if (!isRecord(item))
+            throw new TypeError('research_study_focus_invalid');
+        return key === 'concept'
+            ? conceptsValue(item.concept, 'research_study_focus_invalid')
+            : references(item.reference);
+    });
+}
+function backboneStrings(value, key) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new TypeError('research_study_backbone_invalid');
+    return value.flatMap(item => isRecord(item) ? strings(item[key]) : []);
+}
+function backboneConcepts(value, key) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new TypeError('research_study_backbone_invalid');
+    return value.flatMap(item => isRecord(item) ? conceptsValue(item[key], 'research_study_backbone_invalid') : []);
+}
+function nestedNumber(value, key) {
+    if (!isRecord(value) || value[key] === undefined)
+        return [];
+    const number = Number(value[key]);
+    if (!Number.isInteger(number) || number < 0)
+        throw new TypeError('research_study_recruitment_invalid');
+    return [String(number)];
+}
+function progressStatusValues(value) {
+    const result = { stateActual: [], statePeriod: [], statePeriodActual: [] };
+    if (value === undefined)
+        return result;
+    if (!Array.isArray(value))
+        throw new TypeError('research_study_progress_status_invalid');
+    for (const item of value) {
+        if (!isRecord(item))
+            throw new TypeError('research_study_progress_status_invalid');
+        const states = conceptsValue(item.state, 'research_study_progress_status_invalid');
+        const dates = periodValues(item.period, 'research_study_progress_status_invalid');
+        const actual = typeof item.actual === 'boolean' ? String(item.actual) : undefined;
+        for (const state of states) {
+            if (actual)
+                result.stateActual.push(`${state}$${actual}`);
+            for (const date of dates) {
+                result.statePeriod.push(`${state}$${date}`);
+                if (actual)
+                    result.statePeriodActual.push(`${state}$${date}$${actual}`);
+            }
+        }
+    }
+    return result;
+}
+function optionalString(value) {
+    const normalized = typeof value === 'string' ? value.trim() : '';
+    return normalized || undefined;
+}
+function isFhirDateTime(value) {
+    return /^\d{4}(?:-\d{2}(?:-\d{2}(?:T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2}))?)?)?$/.test(value)
+        && !Number.isNaN(Date.parse(value));
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vet-data-utils-ts",
-  "version": "0.4.11",
+  "version": "0.5.0",
   "description": "Browser-safe governed VetChain data contracts",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",
@@ -44,6 +44,10 @@
       "types": "./dist/organization-application.d.ts",
       "default": "./dist/organization-application.js"
     },
+    "./research-study": {
+      "types": "./dist/research-study.d.ts",
+      "default": "./dist/research-study.js"
+    },
     "./sectors": {
       "types": "./dist/sectors.d.ts",
       "default": "./dist/sectors.js"