vet-data-utils-ts 0.5.22 → 0.5.24

package/README.md

@@ -172,7 +172,7 @@ It is not an implemented importer API.
 
 `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-safety` value used by explicitly governed portal allowlists. Sector
+`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.
 
@@ -182,11 +182,36 @@ 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.
+
 `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

package/dist/health-dcat.d.ts

@@ -0,0 +1,116 @@
+/** Product sectors whose organization UI may expose HealthDCAT publication. */
+export declare const HealthDcatPublisherSectors: readonly ["public-health", "animal-care", "health-care", "animal-insurance", "health-insurance", "onehealth-insurance", "animal-lab", "health-lab", "onehealth-lab", "animal-research", "health-research", "onehealth-research"];
+export type HealthDcatPublisherSector = typeof HealthDcatPublisherSectors[number];
+export type HealthDcatAccessRights = 'PUBLIC' | 'RESTRICTED' | 'NON_PUBLIC';
+export type HealthDcatSourceKind = 'individual-index' | 'spreadsheet-import' | 'digital-twin-import' | 'curated-dataset';
+export type HealthDcatAnonymizationStatus = 'anonymous' | 'pseudonymized' | 'personal';
+export type HealthDcatPublisherRole = 'data-holder' | 'authorized-intermediary';
+type ClaimValue = string | boolean | number | readonly string[];
+/** Standards-derived flat Dataset claims for indexed product persistence. */
+export declare enum ClaimsHealthDcatDataset {
+    identifier = "dct.identifier",
+    title = "dct.title",
+    description = "dct.description",
+    creator = "dct.creator",
+    publisher = "dct.publisher",
+    custodian = "geodcatap.custodian",
+    accessRights = "dct.accessRights",
+    applicableLegislation = "dcatap.applicableLegislation",
+    distribution = "dcat.distribution",
+    source = "dct.source",
+    provenance = "dct.provenance",
+    personalData = "dpv.hasPersonalData",
+    healthCategory = "healthdcatap.healthCategory",
+    healthDataAccessBody = "healthdcatap.hdab",
+    structuredData = "healthdcatap.hasStructuredData",
+    variables = "healthdcatap.hasVariables",
+    authorizationReference = "prov.qualifiedAttribution",
+    userSelected = "Dataset.user-selected"
+}
+/** Standards-derived flat Catalogue claims for indexed product persistence. */
+export declare enum ClaimsHealthDcatCatalog {
+    identifier = "dct.identifier",
+    title = "dct.title",
+    description = "dct.description",
+    creator = "dct.creator",
+    publisher = "dct.publisher",
+    applicableLegislation = "dcatap.applicableLegislation",
+    dataset = "dcat.dataset",
+    userSelected = "Catalog.user-selected"
+}
+export type HealthDcatResource = Readonly<{
+    resourceType: 'Dataset' | 'Catalog';
+    id: string;
+    meta: Readonly<{
+        claims: Readonly<Record<string, ClaimValue>>;
+    }>;
+}>;
+type ControllerAuthority = Readonly<{
+    organizationIdentifier: string;
+    controllerIdentifier: string;
+    actingControllerIdentifier: string;
+}>;
+/** Builds a claims-first HealthDCAT Dataset description under explicit tenant authority. */
+export declare function buildHealthDcatDataset(input: ControllerAuthority & Readonly<{
+    sector: HealthDcatPublisherSector;
+    id: string;
+    title: string;
+    description: string;
+    publisherRole: HealthDcatPublisherRole;
+    dataHolderIdentifier: string;
+    authorizationReference?: string;
+    sourceKind: HealthDcatSourceKind;
+    sourceReference: string;
+    accessRights: HealthDcatAccessRights;
+    anonymizationStatus: HealthDcatAnonymizationStatus;
+    healthCategory: readonly string[];
+    healthDataAccessBodyIdentifier: string;
+    structuredData: boolean;
+    variableTableGroupIdentifiers?: readonly string[];
+    distributionIdentifiers: readonly string[];
+    applicableLegislation: readonly string[];
+}>): HealthDcatResource;
+/** Builds the tenant-owned marketplace Catalogue; creation is controller-only. */
+export declare function buildHealthDcatCatalog(input: ControllerAuthority & Readonly<{
+    id: string;
+    title: string;
+    description: string;
+    datasetIdentifiers: readonly string[];
+    applicableLegislation: readonly string[];
+}>): HealthDcatResource;
+/** Creates an auditable tenant authorization for host-provided catalogue federation. */
+export declare function buildHealthDcatFederationRequest(input: ControllerAuthority & Readonly<{
+    catalogIdentifier: string;
+    hostServiceProviderIdentifier: string;
+    destinationDataspaceIdentifier: string;
+}>): Readonly<{
+    catalogIdentifier: string;
+    publisherIdentifier: string;
+    hostServiceProviderIdentifier: string;
+    destinationDataspaceIdentifier: string;
+    authorizedBy: string;
+}>;
+/** Advertises a host catalogue endpoint in ICA without leaking tenant inventory. */
+export declare function buildCatalogHostAdvertisement(input: Readonly<{
+    hostIdentifier: string;
+    catalogEndpoint: string;
+    tenantDiscovery: 'public' | 'openid4vp';
+}>): Readonly<{
+    hostIdentifier: string;
+    catalogEndpoint: string;
+    catalogProtocol: 'dataspace-protocol-2025-1';
+    tenantDiscovery: 'public' | 'openid4vp';
+}>;
+/** References standard trust and presentation protocols for restricted catalogue discovery. */
+export declare function buildCatalogDiscoveryPolicy(input: Readonly<{
+    visibility: 'public' | 'trusted-federation' | 'private';
+    trustAnchorIdentifiers?: readonly string[];
+    presentationDefinitionUri?: string;
+}>): Readonly<{
+    visibility: 'public' | 'trusted-federation' | 'private';
+    trustResolution?: 'openid-federation-1.0';
+    presentationProtocol?: 'openid4vp-1.0';
+    trustAnchorIdentifiers?: readonly string[];
+    presentationDefinitionUri?: string;
+}>;
+export {};

package/dist/health-dcat.js

@@ -0,0 +1,160 @@
+// Copyright 2026 Connecting Solution & Applications Ltd under the Apache License, Version 2.0.
+/** Product sectors whose organization UI may expose HealthDCAT publication. */
+export const HealthDcatPublisherSectors = Object.freeze([
+    'public-health',
+    'animal-care', 'health-care',
+    'animal-insurance', 'health-insurance', 'onehealth-insurance',
+    'animal-lab', 'health-lab', 'onehealth-lab',
+    'animal-research', 'health-research', 'onehealth-research',
+]);
+/** Standards-derived flat Dataset claims for indexed product persistence. */
+export var ClaimsHealthDcatDataset;
+(function (ClaimsHealthDcatDataset) {
+    ClaimsHealthDcatDataset["identifier"] = "dct.identifier";
+    ClaimsHealthDcatDataset["title"] = "dct.title";
+    ClaimsHealthDcatDataset["description"] = "dct.description";
+    ClaimsHealthDcatDataset["creator"] = "dct.creator";
+    ClaimsHealthDcatDataset["publisher"] = "dct.publisher";
+    ClaimsHealthDcatDataset["custodian"] = "geodcatap.custodian";
+    ClaimsHealthDcatDataset["accessRights"] = "dct.accessRights";
+    ClaimsHealthDcatDataset["applicableLegislation"] = "dcatap.applicableLegislation";
+    ClaimsHealthDcatDataset["distribution"] = "dcat.distribution";
+    ClaimsHealthDcatDataset["source"] = "dct.source";
+    ClaimsHealthDcatDataset["provenance"] = "dct.provenance";
+    ClaimsHealthDcatDataset["personalData"] = "dpv.hasPersonalData";
+    ClaimsHealthDcatDataset["healthCategory"] = "healthdcatap.healthCategory";
+    ClaimsHealthDcatDataset["healthDataAccessBody"] = "healthdcatap.hdab";
+    ClaimsHealthDcatDataset["structuredData"] = "healthdcatap.hasStructuredData";
+    ClaimsHealthDcatDataset["variables"] = "healthdcatap.hasVariables";
+    ClaimsHealthDcatDataset["authorizationReference"] = "prov.qualifiedAttribution";
+    ClaimsHealthDcatDataset["userSelected"] = "Dataset.user-selected";
+})(ClaimsHealthDcatDataset || (ClaimsHealthDcatDataset = {}));
+/** Standards-derived flat Catalogue claims for indexed product persistence. */
+export var ClaimsHealthDcatCatalog;
+(function (ClaimsHealthDcatCatalog) {
+    ClaimsHealthDcatCatalog["identifier"] = "dct.identifier";
+    ClaimsHealthDcatCatalog["title"] = "dct.title";
+    ClaimsHealthDcatCatalog["description"] = "dct.description";
+    ClaimsHealthDcatCatalog["creator"] = "dct.creator";
+    ClaimsHealthDcatCatalog["publisher"] = "dct.publisher";
+    ClaimsHealthDcatCatalog["applicableLegislation"] = "dcatap.applicableLegislation";
+    ClaimsHealthDcatCatalog["dataset"] = "dcat.dataset";
+    ClaimsHealthDcatCatalog["userSelected"] = "Catalog.user-selected";
+})(ClaimsHealthDcatCatalog || (ClaimsHealthDcatCatalog = {}));
+function required(value, field) {
+    const normalized = value.trim();
+    if (!normalized)
+        throw new Error(`${field} is required`);
+    return normalized;
+}
+function assertController(input) {
+    if (required(input.actingControllerIdentifier, 'actingControllerIdentifier') !==
+        required(input.controllerIdentifier, 'controllerIdentifier')) {
+        throw new Error('Only the organization controller may perform this operation');
+    }
+}
+/** Builds a claims-first HealthDCAT Dataset description under explicit tenant authority. */
+export function buildHealthDcatDataset(input) {
+    assertController(input);
+    if (!HealthDcatPublisherSectors.includes(input.sector)) {
+        throw new Error(`Sector ${input.sector} cannot publish HealthDCAT metadata`);
+    }
+    if (input.publisherRole === 'authorized-intermediary' && !input.authorizationReference?.trim()) {
+        throw new Error('authorizationReference is required for an authorized intermediary');
+    }
+    if (input.healthCategory.length === 0)
+        throw new Error('healthCategory is required');
+    if (input.applicableLegislation.length === 0)
+        throw new Error('applicableLegislation is required');
+    if (input.accessRights === 'NON_PUBLIC' && input.distributionIdentifiers.length === 0) {
+        throw new Error('A non-public Dataset requires an HDAB Distribution');
+    }
+    if (input.structuredData && !input.variableTableGroupIdentifiers?.length) {
+        throw new Error('Structured data requires variableTableGroupIdentifiers');
+    }
+    const organizationIdentifier = required(input.organizationIdentifier, 'organizationIdentifier');
+    const sourceReference = required(input.sourceReference, 'sourceReference');
+    const claims = {
+        [ClaimsHealthDcatDataset.identifier]: required(input.id, 'id'),
+        [ClaimsHealthDcatDataset.title]: required(input.title, 'title'),
+        [ClaimsHealthDcatDataset.description]: required(input.description, 'description'),
+        [ClaimsHealthDcatDataset.creator]: input.controllerIdentifier,
+        [ClaimsHealthDcatDataset.publisher]: organizationIdentifier,
+        [ClaimsHealthDcatDataset.custodian]: required(input.dataHolderIdentifier, 'dataHolderIdentifier'),
+        [ClaimsHealthDcatDataset.accessRights]: input.accessRights,
+        [ClaimsHealthDcatDataset.applicableLegislation]: Object.freeze([...input.applicableLegislation]),
+        [ClaimsHealthDcatDataset.distribution]: Object.freeze([...input.distributionIdentifiers]),
+        [ClaimsHealthDcatDataset.source]: sourceReference,
+        [ClaimsHealthDcatDataset.provenance]: `${input.sourceKind}:${sourceReference}`,
+        [ClaimsHealthDcatDataset.personalData]: input.anonymizationStatus !== 'anonymous',
+        [ClaimsHealthDcatDataset.healthCategory]: Object.freeze([...input.healthCategory]),
+        [ClaimsHealthDcatDataset.healthDataAccessBody]: required(input.healthDataAccessBodyIdentifier, 'healthDataAccessBodyIdentifier'),
+        [ClaimsHealthDcatDataset.structuredData]: input.structuredData,
+        [ClaimsHealthDcatDataset.userSelected]: true,
+    };
+    if (input.variableTableGroupIdentifiers?.length) {
+        claims[ClaimsHealthDcatDataset.variables] = Object.freeze([...input.variableTableGroupIdentifiers]);
+    }
+    if (input.authorizationReference) {
+        claims[ClaimsHealthDcatDataset.authorizationReference] = input.authorizationReference;
+    }
+    return Object.freeze({ resourceType: 'Dataset', id: input.id, meta: Object.freeze({ claims: Object.freeze(claims) }) });
+}
+/** Builds the tenant-owned marketplace Catalogue; creation is controller-only. */
+export function buildHealthDcatCatalog(input) {
+    assertController(input);
+    if (input.applicableLegislation.length === 0)
+        throw new Error('applicableLegislation is required');
+    const claims = {
+        [ClaimsHealthDcatCatalog.identifier]: required(input.id, 'id'),
+        [ClaimsHealthDcatCatalog.title]: required(input.title, 'title'),
+        [ClaimsHealthDcatCatalog.description]: required(input.description, 'description'),
+        [ClaimsHealthDcatCatalog.creator]: input.controllerIdentifier,
+        [ClaimsHealthDcatCatalog.publisher]: required(input.organizationIdentifier, 'organizationIdentifier'),
+        [ClaimsHealthDcatCatalog.applicableLegislation]: Object.freeze([...input.applicableLegislation]),
+        [ClaimsHealthDcatCatalog.dataset]: Object.freeze([...input.datasetIdentifiers]),
+        [ClaimsHealthDcatCatalog.userSelected]: true,
+    };
+    return Object.freeze({ resourceType: 'Catalog', id: input.id, meta: Object.freeze({ claims: Object.freeze(claims) }) });
+}
+/** Creates an auditable tenant authorization for host-provided catalogue federation. */
+export function buildHealthDcatFederationRequest(input) {
+    assertController(input);
+    return Object.freeze({
+        catalogIdentifier: required(input.catalogIdentifier, 'catalogIdentifier'),
+        publisherIdentifier: required(input.organizationIdentifier, 'organizationIdentifier'),
+        hostServiceProviderIdentifier: required(input.hostServiceProviderIdentifier, 'hostServiceProviderIdentifier'),
+        destinationDataspaceIdentifier: required(input.destinationDataspaceIdentifier, 'destinationDataspaceIdentifier'),
+        authorizedBy: input.controllerIdentifier,
+    });
+}
+/** Advertises a host catalogue endpoint in ICA without leaking tenant inventory. */
+export function buildCatalogHostAdvertisement(input) {
+    const endpoint = required(input.catalogEndpoint, 'catalogEndpoint');
+    if (!endpoint.startsWith('https://'))
+        throw new Error('catalogEndpoint must use HTTPS');
+    return Object.freeze({
+        hostIdentifier: required(input.hostIdentifier, 'hostIdentifier'),
+        catalogEndpoint: endpoint,
+        catalogProtocol: 'dataspace-protocol-2025-1',
+        tenantDiscovery: input.tenantDiscovery,
+    });
+}
+/** References standard trust and presentation protocols for restricted catalogue discovery. */
+export function buildCatalogDiscoveryPolicy(input) {
+    if (input.visibility === 'trusted-federation') {
+        if (!input.trustAnchorIdentifiers?.length)
+            throw new Error('trustAnchorIdentifiers are required');
+        const presentationDefinitionUri = required(input.presentationDefinitionUri ?? '', 'presentationDefinitionUri');
+        if (!presentationDefinitionUri.startsWith('https://'))
+            throw new Error('presentationDefinitionUri must use HTTPS');
+        return Object.freeze({
+            visibility: input.visibility,
+            trustResolution: 'openid-federation-1.0',
+            presentationProtocol: 'openid4vp-1.0',
+            trustAnchorIdentifiers: Object.freeze([...input.trustAnchorIdentifiers]),
+            presentationDefinitionUri,
+        });
+    }
+    return Object.freeze({ visibility: input.visibility });
+}

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export * from './digital-twin.js';
 export * from './emergency.js';
 export * from './financial.js';
 export * from './group.js';
+export * from './health-dcat.js';
 export * from './immunization.js';
 export * from './international-health-card.js';
 export * from './index-projection-tags.js';

package/dist/index.js

@@ -7,6 +7,7 @@ export * from './digital-twin.js';
 export * from './emergency.js';
 export * from './financial.js';
 export * from './group.js';
+export * from './health-dcat.js';
 export * from './immunization.js';
 export * from './international-health-card.js';
 export * from './index-projection-tags.js';

package/dist/place-service-directory.d.ts

@@ -152,6 +152,13 @@ export declare const OrganizationOfferingKinds: Readonly<{
     readonly 'animal-care': "Service";
     readonly 'animal-insurance': "Product";
 }>;
+/** Complete VetChain organization-sector presentation allowlist. */
+export declare const OrganizationOfferingKindsBySector: Readonly<{
+    readonly 'animal-care': readonly ["Service"];
+    readonly 'animal-insurance': readonly ["Product"];
+    readonly 'animal-tech': readonly ["Service", "Product"];
+    readonly 'animal-research': readonly ["Service"];
+}>;
 /** Stable Eclipse Dataspace Protocol 2025-1 identifiers, including current editorial errata. */
 export declare const DataspaceProtocol2025: Readonly<{
     readonly release: "2025-1-err1";
@@ -318,7 +325,7 @@ export declare function buildOrganizationOfferCatalog(input: Readonly<{
     id: string;
     name: string;
     organizationIdentifier: string;
-    sector: keyof typeof OrganizationOfferingKinds;
+    sector: keyof typeof OrganizationOfferingKindsBySector;
     offerings: readonly (DirectoryResource | DirectoryFlatClaimsResource)[];
 }>): Readonly<{
     '@context': "https://schema.org";
@@ -333,7 +340,7 @@ export declare function buildOrganizationOfferCatalog(input: Readonly<{
     itemListElement: readonly Readonly<{
         '@type': "Offer";
         itemOffered: Readonly<{
-            '@type': "Service" | "Product";
+            '@type': "Place" | "Service" | "Product";
             identifier: string;
             name: string;
         }>;

package/dist/place-service-directory.js

@@ -68,6 +68,13 @@ export const OrganizationOfferingKinds = Object.freeze({
     'animal-care': 'Service',
     'animal-insurance': 'Product',
 });
+/** Complete VetChain organization-sector presentation allowlist. */
+export const OrganizationOfferingKindsBySector = Object.freeze({
+    'animal-care': Object.freeze(['Service']),
+    'animal-insurance': Object.freeze(['Product']),
+    'animal-tech': Object.freeze(['Service', 'Product']),
+    'animal-research': Object.freeze(['Service']),
+});
 /** Stable Eclipse Dataspace Protocol 2025-1 identifiers, including current editorial errata. */
 export const DataspaceProtocol2025 = Object.freeze({
     release: '2025-1-err1',
@@ -434,10 +441,10 @@ export function projectProductToFhirR5InsurancePlan(product) {
 }
 /** Builds the Schema.org JSON-LD OfferCatalog presented by one organization. */
 export function buildOrganizationOfferCatalog(input) {
-    const expectedKind = OrganizationOfferingKinds[input.sector];
+    const allowedKinds = OrganizationOfferingKindsBySector[input.sector];
     const organizationIdentifier = required(input.organizationIdentifier, 'organization_identifier_required');
     const itemListElement = input.offerings.map(offering => {
-        if (offering.resourceType !== expectedKind)
+        if (!allowedKinds.includes(offering.resourceType))
             throw new TypeError('organization_offering_kind_invalid');
         const isService = offering.resourceType === 'Service';
         const nameClaim = isService ? ClaimsDirectoryServiceSchemaorg.name : ClaimsProductSchemaorg.name;

package/dist/sectors.d.ts

@@ -6,6 +6,7 @@
  * the value grants no organization role, membership or data capability.
  */
 export declare const ExtendedDataspaceSectors: Readonly<{
+    readonly PublicHealth: "public-health";
     readonly PublicSafety: "public-safety";
     readonly HealthCare: "health-care";
     readonly HealthLab: "health-lab";

package/dist/sectors.js

@@ -8,5 +8,6 @@ import { DataspaceSectors } from 'gdc-common-utils-ts/constants/sectors';
  */
 export const ExtendedDataspaceSectors = Object.freeze({
     ...DataspaceSectors,
+    PublicHealth: 'public-health',
     PublicSafety: 'public-safety',
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vet-data-utils-ts",
-  "version": "0.5.22",
+  "version": "0.5.24",
   "description": "Browser-safe governed VetChain data contracts",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",
@@ -44,6 +44,10 @@
       "types": "./dist/group.d.ts",
       "default": "./dist/group.js"
     },
+    "./health-dcat": {
+      "types": "./dist/health-dcat.d.ts",
+      "default": "./dist/health-dcat.js"
+    },
     "./immunization": {
       "types": "./dist/immunization.d.ts",
       "default": "./dist/immunization.js"