vet-data-utils-ts

Lost-animal access and behavior

normalizeIso3166Jurisdiction(...) and buildLostAnimalEmergencyJurisdictionActors(...) create exact country or subdivision Consent actors such as urn:iso:3166-2:CA-BC. The LostAnimalEmergencyAccess profile limits standing access to licensed veterinarians, emergency treatment and a minimal veterinary summary. GW still verifies the credential, active licence, route jurisdiction and exact animal.

buildAnimalBehaviorObservation(...) records controller-reported temperament and fear context as a claims-first social-history Observation. It deliberately uses narrative text rather than inventing a veterinary diagnosis code.

The product-local place-service-directory export models persistent public sites as claims-only Schema.org Place resources and their offerings as claims-only Service or Product resources. A care organization publishes services; an insurance organization publishes products in a Schema.org OfferCatalog. Photos, accessibility, coordinates, address and opening-hours specifications remain neutral indexed claims. Native FHIR R5 Location, HealthcareService and InsurancePlan are produced only by explicit projection helpers. Member-specific FHIR Coverage is never a public catalog entry. The shared gdc-* claim catalog remains unchanged while this profile is validated in VetChain.

The customer-facing Schema.org OfferCatalog is distinct from the Eclipse Dataspace Protocol catalog. buildDataspaceCatalogAdvertisement(...) exposes a transferable catalog snapshot as a DSP 2025-1 Dataset with an ODRL use Offer; buildDataspaceDataAddress(...) describes the endpoint only in the negotiated transfer flow. The package deliberately has no third-party DSP runtime dependency: the Eclipse project publishes the specification and Java TCK/EDC implementation, while currently available npm implementations are independent projects and are not adopted implicitly.

Veterinary immunization credentials

buildVeterinaryImmunization(...) creates a FHIR R4 Immunization with the animal in patient and the veterinarian's real PractitionerRole in performer.actor. The caller must supply a governed vaccine coding selected for the animal species, jurisdiction and current terminology release; this package does not guess a rabies or medicinal-product code.

prepareSmartHealthCard(...) minimizes a FHIR Bundle, serializes it deterministically and returns the exact raw-DEFLATE ES256 signing input. The tenant issuer signs that input with its dedicated P-256 credential key and publishes the matching public JWK at iss + /.well-known/jwks.json. encodeSmartHealthCardQr(...) then produces standard shc:/ numeric QR data.

encodePostQuantumCompanionProofUri(...) carries an RFC 7797 detached ML-DSA JWS as pqc:/.... This is a VetChain transition transport, not part of the SMART Health Cards standard. encodePostQuantumCompanionProofQr(...) applies the same two-decimal-digits-per-JWS-character encoding used by SHC, defaults to two numbered large QR labels, and never repeats the external payload. Each attester signs the exact uncompressed SHC payload bytes; verification therefore requires both QR sets.

buildSmartHealthCardPayloadReferences(...) returns two deliberately distinct SHA3-384 identifiers over those exact canonical bytes: a urn:multibase:z... multihash for exact ledger lookup and a base58btc CIDv1 with the raw codec for content-addressed retrieval. The IHC print projection shows FHIR Immunization.occurrenceDateTime, vaccineCode and protocolApplied.targetDisease. Its issuer-supplied validity interval is not FHIR Immunization.expirationDate, which means vaccine-batch expiry.

prepareVeterinaryIndexTaggedBundle(...) creates the interoperable messaging copy of a native FHIR Bundle document. It derives only the caller-allowlisted <ResourceType>.<search-param-or-custom> Coding systems in resource.meta.tag[], preserves repeated values as repeated tags for later CSV projection, rejects generic Resource.* systems, and never mutates the source Bundle.

projectVeterinaryClaimsIndexForUi(...) is the reverse BFF boundary for an already role-authorized GW search result. It removes every clinical field and meta.claims, returning only fullUrl, resourceType, id and allowlisted meta.tag[]; CSV claims are restored as repeated tags. summarizeVeterinaryTaggedIndex(...) then sorts and counts that minimized copy without inspecting resource content.

readVeterinaryBundleTags(...) is the fail-closed UI reader for that minimized shape. It is intentionally separate from the clinical Bundle Reader and rejects meta.claims, clinical fields, resource types or tags outside the caller's already server-authorized policy. Its cards output groups repeated Coding values by resource-qualified search parameter, so an index-only screen can use the same card shell without constructing a clinical-resource view. An authorized full Bundle may first be reduced with projectVeterinaryClaimsIndexForUi(...) when it only needs that summary; the full clinical reader itself remains claims-first and unchanged.

buildSmartHealthCardJwsProofReference(...) serves a different purpose: it hashes the exact compact SHC JWS, including its ES256 signature, with a domain separator. A product ledger/resolver may use that key to retrieve the existing detached pqc:/ proofs when only the SHC QR is printed and internet access is available. Offline PQC verification still requires the companion QR labels.

Development and releases follow the mandatory local-first TDD and release contract.

Browser-safe, transport-neutral VetChain data contracts shared by GW VET and vet-sdk-core-ts. The package owns governed values and validation only; GW VET owns authorization and the SDK owns request construction.

Current surfaces cover the canonical animal-card DID, veterinary summary sections, animal-only emergency data, pseudonymous DigitalTwin search input and veterinary assistant intents.

Veterinary scheduling

vet-data-utils-ts/scheduling owns claims-first builders for FHIR R5 Location, Schedule, Slot, Appointment and AppointmentResponse. expandVeterinaryAvailability(...) expands bounded weekly periods into Slots and applies weekly or monthly-ordinal exceptions that restrict or extend one or more consultation Locations. It converts clinic-local times through an IANA time zone, including daylight-saving changes.

The official searchable facts remain resource-qualified flat claims. The exported VeterinarySlotSearchParameters catalogue identifies the supported FHIR R5 Slot query codes; generated resources include Slot.identifier, Slot.schedule, Slot.status, Slot.start, Appointment.status, Appointment.start, Appointment.slot and Appointment.actor. Product-only facts use the explicit VeterinaryLocation, VeterinarySlot or VeterinaryAppointment prefix; a Location photo and the seven-day confirmation due time are not presented as official FHIR SearchParameters. All builders return only resourceType, id and meta.claims.

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. GW persistence receives only resourceType, id and flat resource.meta.claims; each party uses its own ResearchStudy.party-* claim map 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.

Explicit study provenance uses a separate claims-first FHIR R5 Provenance resource from vet-data-utils-ts/provenance. It exposes all thirteen resource-specific standard SearchParameters and preserves agent correlation as Provenance.agent-<participation-type>-who, where <participation-type> is an exact code from the FHIR ParticipationRoleType ValueSet and the value is the agent's FHIR Reference or URI. The standard Provenance.agent and Provenance.agent-type claims are indexed alongside that correlation claim. For a professional, use buildPractitionerRoleReferenceFromAssignmentIdentifier() with the real Occupation/PractitionerRole assignment UUID returned by GW. The role-bearing employee URN and role-license hash remain operational authorization identities; they are not substituted for the clinical PractitionerRole reference.

ResearchStudy professional teams use native FHIR R5 Group resources from vet-data-utils-ts/group: required type and membership codes, the exact twelve resource-specific SearchParameters, canonical flat claim projection and enumerated PractitionerRole member normalization. Group membership is descriptive and never carries authorization, permission or scope. See docs/group-r5-contract.md.

projectResearchStudyR5FlatClaimsResource() and projectGroupR5FlatClaimsResource() create the minimal claims-first resource; their repeating-party/member companions return one correlated resource per future PATCH. The matching normalize*FlatClaimsResource() functions reject nested FHIR persistence fields and unknown claims. Native FHIR JSON remains an explicit import, projection or export boundary.

Animal-insurance eligibility Consent uses the same boundary through vet-data-utils-ts/insurance-consent: FHIR-equivalent authorization semantics live in canonical flat claims, the complete query-shaped ODRL Agreement lives in an application/odrl+json attachment, semantic divergence fails closed, and native R4/R5 appears only when explicitly requested. Aggregations such as "latest date" and "count" remain ODRL-only because FHIR Consent has no native field for them. See docs/insurance-consent-odrl.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.

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. Veterinary immunizations use the distinct WHO ATCvet classification (group QI 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.

vet-data-utils-ts/veterinary-biologic-product keeps three independent axes:

• WHO ATCvet QI is the international medicine classification;
• the authorized commercial product and its identifier are regional, sourced from EMA UPD, USDA APHIS CVB or CFIA CCVB;
• targetDiseases contains the separately coded diseases/antigens used by FHIR Immunization.protocolApplied.targetDisease.

Source adapters preserve the authority's original product/true/trade names, manufacturer, agents and identifiers. Filtering uses reviewed exact NCBI taxa; broad words such as “poultry” are source labels, not invented species IDs.

The shared IPS reader boundary is projectClinicalBundleForReading(...) from vet-data-utils-ts/clinical-bundle-reader. It accepts a native FHIR Bundle (including R4/R5 resources supported by the common normalizer) or resources already carrying canonical meta.claims, creates a presentation-only copy, and fills the governed primary *-text/*-display claims through an injected exact terminology resolver. The resolver is called with system, code and locale; the original verified Bundle is never mutated. Local UI labels render as text (English display) outside English, English renders only display, and missing labels fall back to the canonical system|code token.

The deferred spreadsheet shape for member and employee role assignments is documented in docs/member-import-contract.md. It is not an implemented importer API.

Active sector extension

vet-data-utils-ts/sectors extends the frozen CORE catalog without changing gdc-common-utils-ts or GW CORE. It adds the product-neutral public-health and public-safety values used by explicitly governed portal allowlists. Sector selection classifies an organization service; it does not grant membership, an occupation, an index role or access to any person or animal.

import { ExtendedDataspaceSectors } from 'vet-data-utils-ts/sectors'

// The portal chooses its exact subset. Do not expose the complete catalog as
// an authorization decision or infer capabilities from this selection.
const allowedSectors = [
  ExtendedDataspaceSectors.PublicHealth,
  ExtendedDataspaceSectors.PublicSafety,
  ExtendedDataspaceSectors.AnimalCare,
] as const

Health dataset catalogues

vet-data-utils-ts/health-dcat provides product-local, claims-first HealthDCAT metadata for public-health, care, insurance, lab and research organizations. Only the organization's controller creates its marketplace Catalogue or authorizes federation by a host service to another dataspace. The tenant remains the publisher; the host does not become the data holder.

Dataset creation records the actual holder, access level, source and provenance. Spreadsheet ingestion, an individual index, a digital-twin import, and pseudonymization are data-processing facts, not publication authority. An intermediary therefore needs an explicit authorization reference. A non-public Dataset must reference its HDAB Distribution, and structured data must reference its CSVW variable TableGroup. The flat keys are compact forms of DCAT-AP, HealthDCAT-AP, DPV, PROV-O and GeoDCAT-AP properties; JSON-LD/DSP serialization remains an explicit transport projection.

ICA advertisement exposes the host catalogue endpoint and supported discovery profile, not a tenant list. Restricted catalogue discovery references OpenID Federation 1.0 trust anchors and OpenID4VP 1.0 presentation definitions; catalogue exchange remains Dataspace Protocol 2025-1. X.509/TLS chain validation, federation trust resolution, VP verification and catalogue authorization are separate checks performed by their owning adapters. normalizeHealthDcatResource() rejects unknown or nested index claims, while projectHealthDcatResourceToJsonLd() is the explicit standards serialization boundary used by host/dataspace adapters.

Research publication is study-scoped. A derived cohort Dataset links to its generating ResearchStudy through PROV-O and a separate CatalogRecord controls whether external catalogue searches may return it. Archiving that record withdraws discovery without deleting the study, eligibility/team Groups, ResearchSubjects or Dataset, and without changing dct:accessRights. No individual ResearchSubject identifier is projected into HealthDCAT. The Dataset dct:provenance points to the separate FHIR Provenance record; it does not replace the prov:wasGeneratedBy study relationship. Distribution describes the HDAB-controlled representation; DataService describes the host API serving Dataset metadata.

vet-data-utils-ts/organization-application is the product-neutral application value used by UHC UNID, VetChain and SOSChain adapters. The host supplies the allowed sector list and translated labels. The value contains one official identifier (TAX, EIN or BN), ISO country, optional matching ISO subdivision, optional official licence, legal representative, technical controller and six independent index participation roles. It rejects a second taxId and every PIN field: profile protection happens immediately after login, before any application screen.

organizationServiceTypeForParticipationRoles() projects those explicit business roles into the canonical GW Service.serviceType capability claim. Index and Digital Twin providers receive the corresponding cruds capability; consumers receive only rs. The application continues to retain the six roles separately, so this operational projection never erases who provides the index service and who merely provides or consumes its data.

The financial surface defines provider-neutral flat claims for FHIR R5 Account, Invoice, PaymentNotice and PaymentReconciliation. Account tracks charges and balances; the responsible party is represented through Invoice.recipient, Account.guarantor-party and, for an actual payment, PaymentReconciliation.payment-issuer. Payment processors and wallets remain adapters outside this package. Communication transports or references these resources but does not duplicate their financial claims.

vet-data-utils-ts/iso-jurisdictions exports the assigned ISO 3166-1 alpha-2 country catalogue and every ISO 3166-2 subdivision level, including type and parent relationships. Consumers persist codes such as CA, CA-BC, ES-MD or its child province ES-M; localized labels remain presentation concerns. Selecting a jurisdiction grants no authority. The generated catalogue comes from Debian iso-codes 4.20.1; run npm run update:iso-jurisdictions to refresh it deliberately.

The catalogue retains longitudinal sections that also apply to animal care, with animal-facing labels where needed. Human advance directives (LOINC|42348-3) are deliberately excluded because they express the patient's own legal/autonomy decisions, not controller preferences.

Digital-twin search input contains one section, one or more resource types allowed by that section, display text, dateFrom and optional dateTo. VeterinaryDigitalTwinSectionSearchProfiles owns the corresponding code-display and date claims so browser code never supplies claim names. Identifying fields and caller-authored claim/dateClaim values are rejected.