vet-data-utils-ts 0.5.24 → 0.5.26

package/README.md

@@ -211,6 +211,18 @@ 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.
+`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

package/dist/health-dcat.d.ts

@@ -19,6 +19,7 @@ export declare enum ClaimsHealthDcatDataset {
     distribution = "dcat.distribution",
     source = "dct.source",
     provenance = "dct.provenance",
+    wasGeneratedBy = "prov.wasGeneratedBy",
     personalData = "dpv.hasPersonalData",
     healthCategory = "healthdcatap.healthCategory",
     healthDataAccessBody = "healthdcatap.hdab",
@@ -38,13 +39,56 @@ export declare enum ClaimsHealthDcatCatalog {
     dataset = "dcat.dataset",
     userSelected = "Catalog.user-selected"
 }
+/** DCAT Catalogue Record editorial claims; status is distinct from data access rights. */
+export declare enum ClaimsHealthDcatCatalogRecord {
+    identifier = "dct.identifier",
+    primaryTopic = "foaf.primaryTopic",
+    status = "adms.status",
+    modified = "dct.modified",
+    conformsTo = "dct.conformsTo",
+    userSelected = "CatalogRecord.user-selected"
+}
+/** DCAT Distribution claims used for downloadable or controlled-access representations. */
+export declare enum ClaimsHealthDcatDistribution {
+    identifier = "dct.identifier",
+    title = "dct.title",
+    accessUrl = "dcat.accessURL",
+    format = "dct.format",
+    mediaType = "dcat.mediaType",
+    accessRights = "dct.accessRights",
+    policy = "odrl.hasPolicy",
+    userSelected = "Distribution.user-selected"
+}
+/** DCAT DataService claims used for host APIs serving one or more Datasets. */
+export declare enum ClaimsHealthDcatDataService {
+    identifier = "dct.identifier",
+    title = "dct.title",
+    publisher = "dct.publisher",
+    endpointUrl = "dcat.endpointURL",
+    servesDataset = "dcat.servesDataset",
+    accessRights = "dct.accessRights",
+    userSelected = "DataService.user-selected"
+}
+export type HealthDcatCatalogRecordStatus = 'draft' | 'published' | 'archived';
+/** Complete allowlist for product-persisted HealthDCAT flat claims. */
+export declare const HealthDcatFlatClaimCatalog: Readonly<{
+    readonly Dataset: readonly ClaimsHealthDcatDataset[];
+    readonly Catalog: readonly ClaimsHealthDcatCatalog[];
+    readonly CatalogRecord: readonly ClaimsHealthDcatCatalogRecord[];
+    readonly Distribution: readonly ClaimsHealthDcatDistribution[];
+    readonly DataService: readonly ClaimsHealthDcatDataService[];
+}>;
 export type HealthDcatResource = Readonly<{
-    resourceType: 'Dataset' | 'Catalog';
+    resourceType: 'Dataset' | 'Catalog' | 'CatalogRecord' | 'Distribution' | 'DataService';
     id: string;
     meta: Readonly<{
         claims: Readonly<Record<string, ClaimValue>>;
     }>;
 }>;
+/** Validates an indexed HealthDCAT resource and rejects nested or unknown claims. */
+export declare function normalizeHealthDcatResource(candidate: unknown): HealthDcatResource;
+/** Explicitly projects internal flat claims to DCAT/HealthDCAT JSON-LD. */
+export declare function projectHealthDcatResourceToJsonLd(resource: unknown): Readonly<Record<string, unknown>>;
 type ControllerAuthority = Readonly<{
     organizationIdentifier: string;
     controllerIdentifier: string;
@@ -78,6 +122,48 @@ export declare function buildHealthDcatCatalog(input: ControllerAuthority & Read
     datasetIdentifiers: readonly string[];
     applicableLegislation: readonly string[];
 }>): HealthDcatResource;
+/** Builds a governed Dataset Distribution without exposing the source records. */
+export declare function buildHealthDcatDistribution(input: ControllerAuthority & Readonly<{
+    id: string;
+    title: string;
+    accessUrl: string;
+    format: string;
+    mediaType?: string;
+    accessRights: HealthDcatAccessRights;
+    healthDataAccessBodyIdentifier: string;
+    policyIdentifier?: string;
+}>): HealthDcatResource;
+/** Builds metadata for a host API that serves published Dataset descriptions. */
+export declare function buildHealthDcatDataService(input: ControllerAuthority & Readonly<{
+    id: string;
+    title: string;
+    endpointUrl: string;
+    servesDatasetIdentifiers: readonly string[];
+    accessRights: HealthDcatAccessRights;
+}>): HealthDcatResource;
+/**
+ * Links one cohort Dataset to the ResearchStudy that generated it and creates
+ * the separate editorial CatalogRecord controlling external discoverability.
+ * ResearchSubject identifiers are deliberately absent from this projection.
+ */
+export declare function buildResearchStudyDatasetPublication(input: ControllerAuthority & Readonly<{
+    dataset: unknown;
+    researchStudyIdentifier: string;
+    catalogRecordIdentifier: string;
+    status: HealthDcatCatalogRecordStatus;
+    modifiedAt: string;
+}>): Readonly<{
+    dataset: HealthDcatResource;
+    record: HealthDcatResource;
+}>;
+/** Controller-only editorial transition; archiving removes external discovery only. */
+export declare function updateHealthDcatCatalogRecordStatus(input: ControllerAuthority & Readonly<{
+    record: unknown;
+    status: HealthDcatCatalogRecordStatus;
+    modifiedAt: string;
+}>): HealthDcatResource;
+/** True only for records eligible for an external marketplace search result. */
+export declare function isHealthDcatCatalogRecordExternallyDiscoverable(record: unknown): boolean;
 /** Creates an auditable tenant authorization for host-provided catalogue federation. */
 export declare function buildHealthDcatFederationRequest(input: ControllerAuthority & Readonly<{
     catalogIdentifier: string;

package/dist/health-dcat.js

@@ -21,6 +21,7 @@ export var ClaimsHealthDcatDataset;
     ClaimsHealthDcatDataset["distribution"] = "dcat.distribution";
     ClaimsHealthDcatDataset["source"] = "dct.source";
     ClaimsHealthDcatDataset["provenance"] = "dct.provenance";
+    ClaimsHealthDcatDataset["wasGeneratedBy"] = "prov.wasGeneratedBy";
     ClaimsHealthDcatDataset["personalData"] = "dpv.hasPersonalData";
     ClaimsHealthDcatDataset["healthCategory"] = "healthdcatap.healthCategory";
     ClaimsHealthDcatDataset["healthDataAccessBody"] = "healthdcatap.hdab";
@@ -41,6 +42,137 @@ export var ClaimsHealthDcatCatalog;
     ClaimsHealthDcatCatalog["dataset"] = "dcat.dataset";
     ClaimsHealthDcatCatalog["userSelected"] = "Catalog.user-selected";
 })(ClaimsHealthDcatCatalog || (ClaimsHealthDcatCatalog = {}));
+/** DCAT Catalogue Record editorial claims; status is distinct from data access rights. */
+export var ClaimsHealthDcatCatalogRecord;
+(function (ClaimsHealthDcatCatalogRecord) {
+    ClaimsHealthDcatCatalogRecord["identifier"] = "dct.identifier";
+    ClaimsHealthDcatCatalogRecord["primaryTopic"] = "foaf.primaryTopic";
+    ClaimsHealthDcatCatalogRecord["status"] = "adms.status";
+    ClaimsHealthDcatCatalogRecord["modified"] = "dct.modified";
+    ClaimsHealthDcatCatalogRecord["conformsTo"] = "dct.conformsTo";
+    ClaimsHealthDcatCatalogRecord["userSelected"] = "CatalogRecord.user-selected";
+})(ClaimsHealthDcatCatalogRecord || (ClaimsHealthDcatCatalogRecord = {}));
+/** DCAT Distribution claims used for downloadable or controlled-access representations. */
+export var ClaimsHealthDcatDistribution;
+(function (ClaimsHealthDcatDistribution) {
+    ClaimsHealthDcatDistribution["identifier"] = "dct.identifier";
+    ClaimsHealthDcatDistribution["title"] = "dct.title";
+    ClaimsHealthDcatDistribution["accessUrl"] = "dcat.accessURL";
+    ClaimsHealthDcatDistribution["format"] = "dct.format";
+    ClaimsHealthDcatDistribution["mediaType"] = "dcat.mediaType";
+    ClaimsHealthDcatDistribution["accessRights"] = "dct.accessRights";
+    ClaimsHealthDcatDistribution["policy"] = "odrl.hasPolicy";
+    ClaimsHealthDcatDistribution["userSelected"] = "Distribution.user-selected";
+})(ClaimsHealthDcatDistribution || (ClaimsHealthDcatDistribution = {}));
+/** DCAT DataService claims used for host APIs serving one or more Datasets. */
+export var ClaimsHealthDcatDataService;
+(function (ClaimsHealthDcatDataService) {
+    ClaimsHealthDcatDataService["identifier"] = "dct.identifier";
+    ClaimsHealthDcatDataService["title"] = "dct.title";
+    ClaimsHealthDcatDataService["publisher"] = "dct.publisher";
+    ClaimsHealthDcatDataService["endpointUrl"] = "dcat.endpointURL";
+    ClaimsHealthDcatDataService["servesDataset"] = "dcat.servesDataset";
+    ClaimsHealthDcatDataService["accessRights"] = "dct.accessRights";
+    ClaimsHealthDcatDataService["userSelected"] = "DataService.user-selected";
+})(ClaimsHealthDcatDataService || (ClaimsHealthDcatDataService = {}));
+/** Complete allowlist for product-persisted HealthDCAT flat claims. */
+export const HealthDcatFlatClaimCatalog = Object.freeze({
+    Dataset: Object.freeze(Object.values(ClaimsHealthDcatDataset)),
+    Catalog: Object.freeze(Object.values(ClaimsHealthDcatCatalog)),
+    CatalogRecord: Object.freeze(Object.values(ClaimsHealthDcatCatalogRecord)),
+    Distribution: Object.freeze(Object.values(ClaimsHealthDcatDistribution)),
+    DataService: Object.freeze(Object.values(ClaimsHealthDcatDataService)),
+});
+/** Validates an indexed HealthDCAT resource and rejects nested or unknown claims. */
+export function normalizeHealthDcatResource(candidate) {
+    if (!candidate || typeof candidate !== 'object')
+        throw new TypeError('health_dcat_resource_invalid');
+    const value = candidate;
+    if (!['Dataset', 'Catalog', 'CatalogRecord', 'Distribution', 'DataService'].includes(String(value.resourceType)))
+        throw new TypeError('health_dcat_resource_invalid');
+    if (typeof value.id !== 'string' || !value.id.trim())
+        throw new TypeError('health_dcat_resource_invalid');
+    if (!value.meta || typeof value.meta !== 'object' || Array.isArray(value.meta))
+        throw new TypeError('health_dcat_resource_invalid');
+    const claims = value.meta.claims;
+    if (!claims || typeof claims !== 'object' || Array.isArray(claims))
+        throw new TypeError('health_dcat_resource_invalid');
+    const resourceType = value.resourceType;
+    const allowed = HealthDcatFlatClaimCatalog[resourceType];
+    const normalized = {};
+    for (const [claim, raw] of Object.entries(claims)) {
+        if (!allowed.includes(claim))
+            throw new TypeError(`health_dcat_claim_not_governed:${claim}`);
+        if (typeof raw === 'string' || typeof raw === 'boolean' || typeof raw === 'number')
+            normalized[claim] = raw;
+        else if (Array.isArray(raw) && raw.every(item => typeof item === 'string'))
+            normalized[claim] = Object.freeze([...raw]);
+        else
+            throw new TypeError(`health_dcat_claim_value_invalid:${claim}`);
+    }
+    return Object.freeze({
+        resourceType,
+        id: value.id,
+        meta: Object.freeze({ claims: Object.freeze(normalized) }),
+    });
+}
+const JsonLdClaimNames = Object.freeze({
+    [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.wasGeneratedBy]: 'prov:wasGeneratedBy',
+    [ClaimsHealthDcatDataset.personalData]: 'dpv:hasPersonalData',
+    [ClaimsHealthDcatDataset.healthCategory]: 'healthdcatap:healthCategory',
+    [ClaimsHealthDcatDataset.healthDataAccessBody]: 'healthdcatap:hdab',
+    [ClaimsHealthDcatDataset.structuredData]: 'healthdcatap:hasStructuredData',
+    [ClaimsHealthDcatDataset.variables]: 'healthdcatap:hasVariables',
+    [ClaimsHealthDcatDataset.authorizationReference]: 'prov:qualifiedAttribution',
+    [ClaimsHealthDcatCatalog.dataset]: 'dcat:dataset',
+    [ClaimsHealthDcatCatalogRecord.primaryTopic]: 'foaf:primaryTopic',
+    [ClaimsHealthDcatCatalogRecord.status]: 'adms:status',
+    [ClaimsHealthDcatCatalogRecord.modified]: 'dct:modified',
+    [ClaimsHealthDcatCatalogRecord.conformsTo]: 'dct:conformsTo',
+    [ClaimsHealthDcatDistribution.accessUrl]: 'dcat:accessURL',
+    [ClaimsHealthDcatDistribution.format]: 'dct:format',
+    [ClaimsHealthDcatDistribution.mediaType]: 'dcat:mediaType',
+    [ClaimsHealthDcatDistribution.policy]: 'odrl:hasPolicy',
+    [ClaimsHealthDcatDataService.endpointUrl]: 'dcat:endpointURL',
+    [ClaimsHealthDcatDataService.servesDataset]: 'dcat:servesDataset',
+});
+/** Explicitly projects internal flat claims to DCAT/HealthDCAT JSON-LD. */
+export function projectHealthDcatResourceToJsonLd(resource) {
+    const normalized = normalizeHealthDcatResource(resource);
+    const output = {
+        '@context': Object.freeze({
+            dcat: 'http://www.w3.org/ns/dcat#',
+            dct: 'http://purl.org/dc/terms/',
+            dcatap: 'http://data.europa.eu/r5r/',
+            geodcatap: 'http://data.europa.eu/930/',
+            healthdcatap: 'http://healthdataportal.eu/ns/health#',
+            dpv: 'https://w3id.org/dpv#',
+            prov: 'http://www.w3.org/ns/prov#',
+            foaf: 'http://xmlns.com/foaf/0.1/',
+            adms: 'http://www.w3.org/ns/adms#',
+            odrl: 'http://www.w3.org/ns/odrl/2/',
+        }),
+        '@id': normalized.id,
+        '@type': `dcat:${normalized.resourceType}`,
+    };
+    for (const [claim, value] of Object.entries(normalized.meta.claims)) {
+        const jsonLdName = JsonLdClaimNames[claim];
+        if (jsonLdName)
+            output[jsonLdName] = value;
+    }
+    return Object.freeze(output);
+}
 function required(value, field) {
     const normalized = value.trim();
     if (!normalized)
@@ -117,6 +249,111 @@ export function buildHealthDcatCatalog(input) {
     };
     return Object.freeze({ resourceType: 'Catalog', id: input.id, meta: Object.freeze({ claims: Object.freeze(claims) }) });
 }
+/** Builds a governed Dataset Distribution without exposing the source records. */
+export function buildHealthDcatDistribution(input) {
+    assertController(input);
+    required(input.healthDataAccessBodyIdentifier, 'healthDataAccessBodyIdentifier');
+    const accessUrl = required(input.accessUrl, 'accessUrl');
+    if (!accessUrl.startsWith('https://'))
+        throw new TypeError('accessUrl must use HTTPS');
+    const claims = {
+        [ClaimsHealthDcatDistribution.identifier]: required(input.id, 'id'),
+        [ClaimsHealthDcatDistribution.title]: required(input.title, 'title'),
+        [ClaimsHealthDcatDistribution.accessUrl]: accessUrl,
+        [ClaimsHealthDcatDistribution.format]: required(input.format, 'format'),
+        [ClaimsHealthDcatDistribution.accessRights]: input.accessRights,
+        [ClaimsHealthDcatDistribution.userSelected]: true,
+    };
+    if (input.mediaType)
+        claims[ClaimsHealthDcatDistribution.mediaType] = required(input.mediaType, 'mediaType');
+    if (input.policyIdentifier)
+        claims[ClaimsHealthDcatDistribution.policy] = required(input.policyIdentifier, 'policyIdentifier');
+    return normalizeHealthDcatResource({ resourceType: 'Distribution', id: input.id, meta: { claims } });
+}
+/** Builds metadata for a host API that serves published Dataset descriptions. */
+export function buildHealthDcatDataService(input) {
+    assertController(input);
+    const endpointUrl = required(input.endpointUrl, 'endpointUrl');
+    if (!endpointUrl.startsWith('https://'))
+        throw new TypeError('endpointUrl must use HTTPS');
+    if (!input.servesDatasetIdentifiers.length)
+        throw new TypeError('servesDatasetIdentifiers are required');
+    return normalizeHealthDcatResource({
+        resourceType: 'DataService', id: input.id, meta: { claims: {
+                [ClaimsHealthDcatDataService.identifier]: required(input.id, 'id'),
+                [ClaimsHealthDcatDataService.title]: required(input.title, 'title'),
+                [ClaimsHealthDcatDataService.publisher]: required(input.organizationIdentifier, 'organizationIdentifier'),
+                [ClaimsHealthDcatDataService.endpointUrl]: endpointUrl,
+                [ClaimsHealthDcatDataService.servesDataset]: Object.freeze([...input.servesDatasetIdentifiers]),
+                [ClaimsHealthDcatDataService.accessRights]: input.accessRights,
+                [ClaimsHealthDcatDataService.userSelected]: true,
+            } },
+    });
+}
+/**
+ * Links one cohort Dataset to the ResearchStudy that generated it and creates
+ * the separate editorial CatalogRecord controlling external discoverability.
+ * ResearchSubject identifiers are deliberately absent from this projection.
+ */
+export function buildResearchStudyDatasetPublication(input) {
+    assertController(input);
+    const dataset = normalizeHealthDcatResource(input.dataset);
+    if (dataset.resourceType !== 'Dataset')
+        throw new TypeError('research_dataset_required');
+    const researchStudyIdentifier = required(input.researchStudyIdentifier, 'researchStudyIdentifier');
+    if (!researchStudyIdentifier.startsWith('ResearchStudy/'))
+        throw new TypeError('research_study_reference_invalid');
+    const modifiedAt = new Date(input.modifiedAt);
+    if (!Number.isFinite(modifiedAt.getTime()) || modifiedAt.toISOString() !== input.modifiedAt)
+        throw new TypeError('modifiedAt must be an ISO instant');
+    const linkedDataset = normalizeHealthDcatResource({
+        ...dataset,
+        meta: { claims: { ...dataset.meta.claims, [ClaimsHealthDcatDataset.wasGeneratedBy]: researchStudyIdentifier } },
+    });
+    const recordId = required(input.catalogRecordIdentifier, 'catalogRecordIdentifier');
+    const record = normalizeHealthDcatResource({
+        resourceType: 'CatalogRecord',
+        id: recordId,
+        meta: { claims: {
+                [ClaimsHealthDcatCatalogRecord.identifier]: recordId,
+                [ClaimsHealthDcatCatalogRecord.primaryTopic]: `Dataset/${dataset.id}`,
+                [ClaimsHealthDcatCatalogRecord.status]: input.status,
+                [ClaimsHealthDcatCatalogRecord.modified]: input.modifiedAt,
+                [ClaimsHealthDcatCatalogRecord.conformsTo]: 'HealthDCAT-AP Release 7',
+                [ClaimsHealthDcatCatalogRecord.userSelected]: true,
+            } },
+    });
+    return Object.freeze({ dataset: linkedDataset, record });
+}
+/** Controller-only editorial transition; archiving removes external discovery only. */
+export function updateHealthDcatCatalogRecordStatus(input) {
+    assertController(input);
+    const record = normalizeHealthDcatResource(input.record);
+    if (record.resourceType !== 'CatalogRecord')
+        throw new TypeError('health_dcat_catalog_record_required');
+    const timestamp = new Date(input.modifiedAt);
+    if (!Number.isFinite(timestamp.getTime()) || timestamp.toISOString() !== input.modifiedAt)
+        throw new TypeError('modifiedAt must be an ISO instant');
+    return normalizeHealthDcatResource({
+        ...record,
+        meta: { claims: {
+                ...record.meta.claims,
+                [ClaimsHealthDcatCatalogRecord.status]: input.status,
+                [ClaimsHealthDcatCatalogRecord.modified]: input.modifiedAt,
+            } },
+    });
+}
+/** True only for records eligible for an external marketplace search result. */
+export function isHealthDcatCatalogRecordExternallyDiscoverable(record) {
+    try {
+        const normalized = normalizeHealthDcatResource(record);
+        return normalized.resourceType === 'CatalogRecord'
+            && normalized.meta.claims[ClaimsHealthDcatCatalogRecord.status] === 'published';
+    }
+    catch {
+        return false;
+    }
+}
 /** Creates an auditable tenant authorization for host-provided catalogue federation. */
 export function buildHealthDcatFederationRequest(input) {
     assertController(input);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vet-data-utils-ts",
-  "version": "0.5.24",
+  "version": "0.5.26",
   "description": "Browser-safe governed VetChain data contracts",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",