@twin.org/federated-catalogue-models 0.0.3-next.4 → 0.0.3-next.5

package/dist/es/index.js

@@ -1,12 +1,11 @@
 // Copyright 2025 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
 export * from "./factories/federatedCatalogueFilterFactory.js";
-export * from "./models/federatedCatalogueContexts.js";
-export * from "./models/filters/IBaseFilter.js";
-export * from "./models/IFederatedCatalogueComponent.js";
-export * from "./models/IFederatedCatalogueFilter.js";
 export * from "./models/api/ICatalogRequestRequest.js";
 export * from "./models/api/ICatalogRequestResponse.js";
 export * from "./models/api/IGetDatasetRequest.js";
 export * from "./models/api/IGetDatasetResponse.js";
+export * from "./models/filters/IBaseFilter.js";
+export * from "./models/IFederatedCatalogueComponent.js";
+export * from "./models/IFederatedCatalogueFilter.js";
 //# sourceMappingURL=index.js.map

package/dist/es/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,cAAc,gDAAgD,CAAC;AAE/D,cAAc,wCAAwC,CAAC;AACvD,cAAc,iCAAiC,CAAC;AAChD,cAAc,0CAA0C,CAAC;AACzD,cAAc,uCAAuC,CAAC;AAEtD,cAAc,wCAAwC,CAAC;AACvD,cAAc,yCAAyC,CAAC;AACxD,cAAc,oCAAoC,CAAC;AACnD,cAAc,qCAAqC,CAAC","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nexport * from \"./factories/federatedCatalogueFilterFactory.js\";\n\nexport * from \"./models/federatedCatalogueContexts.js\";\nexport * from \"./models/filters/IBaseFilter.js\";\nexport * from \"./models/IFederatedCatalogueComponent.js\";\nexport * from \"./models/IFederatedCatalogueFilter.js\";\n\nexport * from \"./models/api/ICatalogRequestRequest.js\";\nexport * from \"./models/api/ICatalogRequestResponse.js\";\nexport * from \"./models/api/IGetDatasetRequest.js\";\nexport * from \"./models/api/IGetDatasetResponse.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,cAAc,gDAAgD,CAAC;AAC/D,cAAc,wCAAwC,CAAC;AACvD,cAAc,yCAAyC,CAAC;AACxD,cAAc,oCAAoC,CAAC;AACnD,cAAc,qCAAqC,CAAC;AACpD,cAAc,iCAAiC,CAAC;AAChD,cAAc,0CAA0C,CAAC;AACzD,cAAc,uCAAuC,CAAC","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nexport * from \"./factories/federatedCatalogueFilterFactory.js\";\nexport * from \"./models/api/ICatalogRequestRequest.js\";\nexport * from \"./models/api/ICatalogRequestResponse.js\";\nexport * from \"./models/api/IGetDatasetRequest.js\";\nexport * from \"./models/api/IGetDatasetResponse.js\";\nexport * from \"./models/filters/IBaseFilter.js\";\nexport * from \"./models/IFederatedCatalogueComponent.js\";\nexport * from \"./models/IFederatedCatalogueFilter.js\";\n"]}

package/dist/es/models/IFederatedCatalogueComponent.js.map

@@ -1 +1 @@
-{"version":3,"file":"IFederatedCatalogueComponent.js","sourceRoot":"","sources":["../../../src/models/IFederatedCatalogueComponent.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IComponent } from \"@twin.org/core\";\nimport type { IDcatCatalog, IDcatDataset } from \"@twin.org/standards-w3c-dcat\";\n\n/**\n * Interface describing a federated catalogue component.\n * Provides Dataspace Protocol-compliant catalog endpoints for dataset registry and query.\n */\nexport interface IFederatedCatalogueComponent extends IComponent {\n\t/**\n\t * Retrieve a dataset by its unique identifier.\n\t * @param dataSetId The unique identifier of the dataset.\n\t * @returns The dataset if found.\n\t * @throws NotFoundError if the dataset does not exist.\n\t */\n\tget(dataSetId: string): Promise<IDcatDataset>;\n\n\t/**\n\t * Insert or update a dataset in the catalogue.\n\t * This method is internal and should not be exposed via REST endpoints.\n\t * @param dataSet The dataset to store.\n\t * @returns Nothing.\n\t */\n\tset(dataSet: IDcatDataset): Promise<void>;\n\n\t/**\n\t * Execute a query against the catalogue using registered filter plugins.\n\t * Returns a complete DCAT Catalog object with proper JSON-LD context, metadata, and datasets.\n\t * Filter plugins must be registered in FilterFactory before service initialization.\n\t * The filter payload is evaluated by the appropriate filter plugin based on its structure.\n\t * Pagination properties (cursor, limit) and filter type (@type) should be included\n\t * within the filter object per Eclipse Dataspace Protocol JSON-LD extension patterns.\n\t * @param filter The filter criteria containing @type, optional cursor and limit properties.\n\t * @returns Complete ICatalog object with @context, @id, @type, dcat:dataset, and optional cursor.\n\t * @throws NotFoundError if the @type field is missing or if the filter type is not registered.\n\t */\n\tquery(filter?: unknown[]): Promise<IDcatCatalog>;\n\n\t/**\n\t * Remove a dataset from the catalogue by its unique identifier.\n\t * @param dataSetId The unique identifier of the dataset to remove.\n\t * @returns Nothing.\n\t */\n\tremove(dataSetId: string): Promise<void>;\n}\n"]}
+{"version":3,"file":"IFederatedCatalogueComponent.js","sourceRoot":"","sources":["../../../src/models/IFederatedCatalogueComponent.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IComponent } from \"@twin.org/core\";\nimport type {\n\tIDataspaceProtocolCatalog,\n\tIDataspaceProtocolCatalogError\n} from \"@twin.org/standards-dataspace-protocol\";\nimport type { IDcatDataset } from \"@twin.org/standards-w3c-dcat\";\n\n/**\n * Interface describing a federated catalogue component.\n * Provides Dataspace Protocol-compliant catalog endpoints for dataset registry and query.\n */\nexport interface IFederatedCatalogueComponent extends IComponent {\n\t/**\n\t * Retrieve a dataset by its unique identifier.\n\t * @param dataSetId The unique identifier of the dataset.\n\t * @returns The dataset if found, or a CatalogError if not found or an error occurs.\n\t */\n\tget(dataSetId: string): Promise<IDcatDataset | IDataspaceProtocolCatalogError>;\n\n\t/**\n\t * Insert or update a dataset in the catalogue.\n\t * This method is internal and should not be exposed via REST endpoints.\n\t * @param dataSet The dataset to store.\n\t * @returns Nothing.\n\t */\n\tset(dataSet: IDcatDataset): Promise<void>;\n\n\t/**\n\t * Execute a query against the catalogue using registered filter plugins.\n\t * Returns a DS Protocol compliant Catalog object with participantId.\n\t *\n\t * The root catalog's participantId is the requesting participant (from context).\n\t * Own datasets (matching requestingParticipantId) go directly in root dataset[].\n\t * Other participants' datasets are grouped in nested catalog[] entries.\n\t *\n\t * For anonymous requests (no context), uses the first publisher found as fallback.\n\t * Returns CatalogError 404 when no datasets exist.\n\t *\n\t * @param filter The filter criteria containing @type.\n\t * @param cursor Optional cursor for pagination.\n\t * @param limit Optional limit for pagination.\n\t * @returns Complete IDataspaceProtocolCatalog with @context, @id, @type, participantId, dataset/catalog,\n\t * or IDataspaceProtocolCatalogError if no datasets found.\n\t * @throws NotFoundError if the @type field is missing or if the filter type is not registered.\n\t */\n\tquery(\n\t\tfilter?: unknown[],\n\t\tcursor?: string,\n\t\tlimit?: number\n\t): Promise<{\n\t\tcatalog: IDataspaceProtocolCatalog | IDataspaceProtocolCatalogError;\n\t\tcursor?: string;\n\t}>;\n\n\t/**\n\t * Remove a dataset from the catalogue by its unique identifier.\n\t * @param dataSetId The unique identifier of the dataset to remove.\n\t * @returns Nothing.\n\t */\n\tremove(dataSetId: string): Promise<void>;\n}\n"]}

package/dist/es/models/IFederatedCatalogueFilter.js.map

@@ -1 +1 @@
-{"version":3,"file":"IFederatedCatalogueFilter.js","sourceRoot":"","sources":["../../../src/models/IFederatedCatalogueFilter.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IComponent } from \"@twin.org/core\";\nimport type { IDcatDataset } from \"@twin.org/standards-w3c-dcat\";\n\n/**\n * Interface describing a filter plugin for the federated catalogue.\n * Filter plugins provide extensible query semantics and indexing strategies.\n * Filters are registered by name in the FilterFactory and do not need to self-identify.\n */\nexport interface IFederatedCatalogueFilter extends IComponent {\n\t/**\n\t * Execute a filter-specific query over the catalogue.\n\t * Each filter interprets the payload according to its own semantics.\n\t * Pagination properties (cursor, limit) are extracted from the filter object by the service layer.\n\t * @param filter The filter criteria (structure depends on the filter implementation).\n\t * @returns Object containing datasets matching the filter criteria and optional cursor for next page.\n\t */\n\tquery(filter: unknown): Promise<{ datasets: IDcatDataset[]; cursor?: string }>;\n\n\t/**\n\t * Generate filter indexes for a dataset to optimize future queries.\n\t * Indexes are stored as properties on the dataset entity itself.\n\t * @param dataSet The dataset to index.\n\t * @returns Record mapping filter-specific index keys to values.\n\t */\n\tcreateIndex(dataSet: IDcatDataset): Promise<{ [key: string]: unknown }>;\n}\n"]}
+{"version":3,"file":"IFederatedCatalogueFilter.js","sourceRoot":"","sources":["../../../src/models/IFederatedCatalogueFilter.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IComponent } from \"@twin.org/core\";\nimport type { IDcatDataset } from \"@twin.org/standards-w3c-dcat\";\n\n/**\n * Interface describing a filter plugin for the federated catalogue.\n * Filter plugins provide extensible query semantics and indexing strategies.\n * Filters are registered by name in the FilterFactory and do not need to self-identify.\n */\nexport interface IFederatedCatalogueFilter extends IComponent {\n\t/**\n\t * Execute a filter-specific query over the catalogue.\n\t * Each filter interprets the payload according to its own semantics.\n\t * @param filter The filter criteria (structure depends on the filter implementation).\n\t * @param cursor The pagination cursor from the previous query, if any.\n\t * @param limit The maximum number of results to return.\n\t * @returns Object containing datasets matching the filter criteria and optional cursor for next page.\n\t */\n\tquery(\n\t\tfilter: unknown,\n\t\tcursor?: string,\n\t\tlimit?: number\n\t): Promise<{ datasets: IDcatDataset[]; cursor?: string }>;\n\n\t/**\n\t * Generate filter indexes for a dataset to optimize future queries.\n\t * Indexes are stored as properties on the dataset entity itself.\n\t * @param dataSet The dataset to index.\n\t * @returns Record mapping filter-specific index keys to values.\n\t */\n\tcreateIndex(dataSet: IDcatDataset): Promise<{ [key: string]: unknown }>;\n}\n"]}

package/dist/es/models/api/ICatalogRequestRequest.js.map

@@ -1 +1 @@
-{"version":3,"file":"ICatalogRequestRequest.js","sourceRoot":"","sources":["../../../../src/models/api/ICatalogRequestRequest.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IDataspaceProtocolCatalogRequestMessage } from \"@twin.org/standards-dataspace-protocol\";\n\n/**\n * The request parameters for the catalog request method.\n */\nexport interface ICatalogRequestRequest {\n\t/**\n\t * The request body containing the catalog query.\n\t */\n\tbody: IDataspaceProtocolCatalogRequestMessage;\n}\n"]}
+{"version":3,"file":"ICatalogRequestRequest.js","sourceRoot":"","sources":["../../../../src/models/api/ICatalogRequestRequest.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IDataspaceProtocolCatalogRequestMessage } from \"@twin.org/standards-dataspace-protocol\";\n\n/**\n * The request parameters for the catalog request method.\n */\nexport interface ICatalogRequestRequest {\n\t/**\n\t * The request body containing the catalog query.\n\t */\n\tbody: IDataspaceProtocolCatalogRequestMessage;\n\n\t/**\n\t * Optional query parameters for pagination.\n\t * Used when following Link header URLs per DS Protocol spec.\n\t */\n\tquery?: {\n\t\t/**\n\t\t * Opaque cursor token for pagination.\n\t\t */\n\t\tcursor?: string;\n\n\t\t/**\n\t\t * Limit for pagination.\n\t\t */\n\t\tlimit?: string;\n\t};\n}\n"]}

package/dist/es/models/api/ICatalogRequestResponse.js.map

@@ -1 +1 @@
-{"version":3,"file":"ICatalogRequestResponse.js","sourceRoot":"","sources":["../../../../src/models/api/ICatalogRequestResponse.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IDcatCatalog } from \"@twin.org/standards-w3c-dcat\";\n\n/**\n * The response payload for the catalog request method.\n */\nexport interface ICatalogRequestResponse {\n\t/**\n\t * The response payload containing the catalog with matching datasets.\n\t */\n\tbody: IDcatCatalog;\n}\n"]}
+{"version":3,"file":"ICatalogRequestResponse.js","sourceRoot":"","sources":["../../../../src/models/api/ICatalogRequestResponse.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type {\n\tIDataspaceProtocolCatalog,\n\tIDataspaceProtocolCatalogError\n} from \"@twin.org/standards-dataspace-protocol\";\nimport type { HeaderTypes, HttpStatusCode } from \"@twin.org/web\";\n\n/**\n * The response payload for the catalog request method.\n * Returns a DS Protocol compliant Catalog with participantId, or CatalogError if no datasets found.\n */\nexport interface ICatalogRequestResponse {\n\t/**\n\t * Response status code.\n\t * Per DS Protocol: Returns appropriate HTTP code (e.g., 404) when returning CatalogError.\n\t */\n\tstatusCode?: HttpStatusCode;\n\n\t/**\n\t * The response payload containing the DS Protocol compliant catalog with participantId,\n\t * or a CatalogError if no datasets are found (404).\n\t * Per DS Protocol: Single participant returns flat catalog, multiple participants return nested catalogs.\n\t */\n\tbody: IDataspaceProtocolCatalog | IDataspaceProtocolCatalogError;\n\n\t/**\n\t * Optional headers including RFC 8288 Link header for pagination.\n\t */\n\theaders?: {\n\t\t[HeaderTypes.Link]?: string | string[];\n\t};\n}\n"]}

package/dist/es/models/api/IGetDatasetResponse.js.map

@@ -1 +1 @@
-{"version":3,"file":"IGetDatasetResponse.js","sourceRoot":"","sources":["../../../../src/models/api/IGetDatasetResponse.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IDcatDataset } from \"@twin.org/standards-w3c-dcat\";\n\n/**\n * The response payload for the get dataset method.\n */\nexport interface IGetDatasetResponse {\n\t/**\n\t * The response payload containing the dataset.\n\t */\n\tbody: IDcatDataset;\n}\n"]}
+{"version":3,"file":"IGetDatasetResponse.js","sourceRoot":"","sources":["../../../../src/models/api/IGetDatasetResponse.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IDataspaceProtocolCatalogError } from \"@twin.org/standards-dataspace-protocol\";\nimport type { IDcatDataset } from \"@twin.org/standards-w3c-dcat\";\nimport type { HttpStatusCode } from \"@twin.org/web\";\n\n/**\n * The response payload for the get dataset method.\n */\nexport interface IGetDatasetResponse {\n\t/**\n\t * Response status code.\n\t */\n\tstatusCode?: HttpStatusCode;\n\n\t/**\n\t * The response payload containing the dataset or error.\n\t */\n\tbody: IDcatDataset | IDataspaceProtocolCatalogError;\n}\n"]}

package/dist/types/index.d.ts

@@ -1,9 +1,8 @@
 export * from "./factories/federatedCatalogueFilterFactory.js";
-export * from "./models/federatedCatalogueContexts.js";
-export * from "./models/filters/IBaseFilter.js";
-export * from "./models/IFederatedCatalogueComponent.js";
-export * from "./models/IFederatedCatalogueFilter.js";
 export * from "./models/api/ICatalogRequestRequest.js";
 export * from "./models/api/ICatalogRequestResponse.js";
 export * from "./models/api/IGetDatasetRequest.js";
 export * from "./models/api/IGetDatasetResponse.js";
+export * from "./models/filters/IBaseFilter.js";
+export * from "./models/IFederatedCatalogueComponent.js";
+export * from "./models/IFederatedCatalogueFilter.js";

package/dist/types/models/IFederatedCatalogueComponent.d.ts

@@ -1,5 +1,6 @@
 import type { IComponent } from "@twin.org/core";
-import type { IDcatCatalog, IDcatDataset } from "@twin.org/standards-w3c-dcat";
+import type { IDataspaceProtocolCatalog, IDataspaceProtocolCatalogError } from "@twin.org/standards-dataspace-protocol";
+import type { IDcatDataset } from "@twin.org/standards-w3c-dcat";
 /**
  * Interface describing a federated catalogue component.
  * Provides Dataspace Protocol-compliant catalog endpoints for dataset registry and query.
@@ -8,10 +9,9 @@ export interface IFederatedCatalogueComponent extends IComponent {
     /**
      * Retrieve a dataset by its unique identifier.
      * @param dataSetId The unique identifier of the dataset.
-     * @returns The dataset if found.
-     * @throws NotFoundError if the dataset does not exist.
+     * @returns The dataset if found, or a CatalogError if not found or an error occurs.
      */
-    get(dataSetId: string): Promise<IDcatDataset>;
+    get(dataSetId: string): Promise<IDcatDataset | IDataspaceProtocolCatalogError>;
     /**
      * Insert or update a dataset in the catalogue.
      * This method is internal and should not be exposed via REST endpoints.
@@ -21,16 +21,26 @@ export interface IFederatedCatalogueComponent extends IComponent {
     set(dataSet: IDcatDataset): Promise<void>;
     /**
      * Execute a query against the catalogue using registered filter plugins.
-     * Returns a complete DCAT Catalog object with proper JSON-LD context, metadata, and datasets.
-     * Filter plugins must be registered in FilterFactory before service initialization.
-     * The filter payload is evaluated by the appropriate filter plugin based on its structure.
-     * Pagination properties (cursor, limit) and filter type (@type) should be included
-     * within the filter object per Eclipse Dataspace Protocol JSON-LD extension patterns.
-     * @param filter The filter criteria containing @type, optional cursor and limit properties.
-     * @returns Complete ICatalog object with @context, @id, @type, dcat:dataset, and optional cursor.
+     * Returns a DS Protocol compliant Catalog object with participantId.
+     *
+     * The root catalog's participantId is the requesting participant (from context).
+     * Own datasets (matching requestingParticipantId) go directly in root dataset[].
+     * Other participants' datasets are grouped in nested catalog[] entries.
+     *
+     * For anonymous requests (no context), uses the first publisher found as fallback.
+     * Returns CatalogError 404 when no datasets exist.
+     *
+     * @param filter The filter criteria containing @type.
+     * @param cursor Optional cursor for pagination.
+     * @param limit Optional limit for pagination.
+     * @returns Complete IDataspaceProtocolCatalog with @context, @id, @type, participantId, dataset/catalog,
+     * or IDataspaceProtocolCatalogError if no datasets found.
      * @throws NotFoundError if the @type field is missing or if the filter type is not registered.
      */
-    query(filter?: unknown[]): Promise<IDcatCatalog>;
+    query(filter?: unknown[], cursor?: string, limit?: number): Promise<{
+        catalog: IDataspaceProtocolCatalog | IDataspaceProtocolCatalogError;
+        cursor?: string;
+    }>;
     /**
      * Remove a dataset from the catalogue by its unique identifier.
      * @param dataSetId The unique identifier of the dataset to remove.

package/dist/types/models/IFederatedCatalogueFilter.d.ts

@@ -9,11 +9,12 @@ export interface IFederatedCatalogueFilter extends IComponent {
     /**
      * Execute a filter-specific query over the catalogue.
      * Each filter interprets the payload according to its own semantics.
-     * Pagination properties (cursor, limit) are extracted from the filter object by the service layer.
      * @param filter The filter criteria (structure depends on the filter implementation).
+     * @param cursor The pagination cursor from the previous query, if any.
+     * @param limit The maximum number of results to return.
      * @returns Object containing datasets matching the filter criteria and optional cursor for next page.
      */
-    query(filter: unknown): Promise<{
+    query(filter: unknown, cursor?: string, limit?: number): Promise<{
         datasets: IDcatDataset[];
         cursor?: string;
     }>;

package/dist/types/models/api/ICatalogRequestRequest.d.ts

@@ -7,4 +7,18 @@ export interface ICatalogRequestRequest {
      * The request body containing the catalog query.
      */
     body: IDataspaceProtocolCatalogRequestMessage;
+    /**
+     * Optional query parameters for pagination.
+     * Used when following Link header URLs per DS Protocol spec.
+     */
+    query?: {
+        /**
+         * Opaque cursor token for pagination.
+         */
+        cursor?: string;
+        /**
+         * Limit for pagination.
+         */
+        limit?: string;
+    };
 }

package/dist/types/models/api/ICatalogRequestResponse.d.ts

@@ -1,10 +1,25 @@
-import type { IDcatCatalog } from "@twin.org/standards-w3c-dcat";
+import type { IDataspaceProtocolCatalog, IDataspaceProtocolCatalogError } from "@twin.org/standards-dataspace-protocol";
+import type { HeaderTypes, HttpStatusCode } from "@twin.org/web";
 /**
  * The response payload for the catalog request method.
+ * Returns a DS Protocol compliant Catalog with participantId, or CatalogError if no datasets found.
  */
 export interface ICatalogRequestResponse {
     /**
-     * The response payload containing the catalog with matching datasets.
+     * Response status code.
+     * Per DS Protocol: Returns appropriate HTTP code (e.g., 404) when returning CatalogError.
      */
-    body: IDcatCatalog;
+    statusCode?: HttpStatusCode;
+    /**
+     * The response payload containing the DS Protocol compliant catalog with participantId,
+     * or a CatalogError if no datasets are found (404).
+     * Per DS Protocol: Single participant returns flat catalog, multiple participants return nested catalogs.
+     */
+    body: IDataspaceProtocolCatalog | IDataspaceProtocolCatalogError;
+    /**
+     * Optional headers including RFC 8288 Link header for pagination.
+     */
+    headers?: {
+        [HeaderTypes.Link]?: string | string[];
+    };
 }

package/dist/types/models/api/IGetDatasetResponse.d.ts

@@ -1,10 +1,16 @@
+import type { IDataspaceProtocolCatalogError } from "@twin.org/standards-dataspace-protocol";
 import type { IDcatDataset } from "@twin.org/standards-w3c-dcat";
+import type { HttpStatusCode } from "@twin.org/web";
 /**
  * The response payload for the get dataset method.
  */
 export interface IGetDatasetResponse {
     /**
-     * The response payload containing the dataset.
+     * Response status code.
      */
-    body: IDcatDataset;
+    statusCode?: HttpStatusCode;
+    /**
+     * The response payload containing the dataset or error.
+     */
+    body: IDcatDataset | IDataspaceProtocolCatalogError;
 }

package/docs/changelog.md

@@ -1,5 +1,12 @@
 # @twin.org/federated-catalogue-models - Changelog
 
+## [0.0.3-next.5](https://github.com/twinfoundation/federated-catalogue/compare/federated-catalogue-models-v0.0.3-next.4...federated-catalogue-models-v0.0.3-next.5) (2026-01-15)
+
+
+### Bug Fixes
+
+* pagination and ld context ([#45](https://github.com/twinfoundation/federated-catalogue/issues/45)) ([e36f096](https://github.com/twinfoundation/federated-catalogue/commit/e36f096aa4fdc61eb5b929a0fc4403247dbd41ce))
+
 ## [0.0.3-next.4](https://github.com/twinfoundation/federated-catalogue/compare/federated-catalogue-models-v0.0.3-next.3...federated-catalogue-models-v0.0.3-next.4) (2026-01-06)
 
 

package/docs/reference/index.md

@@ -10,11 +10,6 @@
 - [IGetDatasetResponse](interfaces/IGetDatasetResponse.md)
 - [IBaseFilter](interfaces/IBaseFilter.md)
 
-## Type Aliases
-
-- [FederatedCatalogueContexts](type-aliases/FederatedCatalogueContexts.md)
-
 ## Variables
 
 - [FederatedCatalogueFilterFactory](variables/FederatedCatalogueFilterFactory.md)
-- [FederatedCatalogueContexts](variables/FederatedCatalogueContexts.md)

package/docs/reference/interfaces/IBaseFilter.md

@@ -17,7 +17,7 @@ to define its own filter-specific properties.
 
 ## Indexable
 
-\[`key`: `string`\]: `string` \| `number` \| `boolean` \| `IJsonLdNodeObject` \| `IJsonLdGraphObject` \| `object` & `object` \| `object` & `object` \| `object` & `object` \| `IJsonLdListObject` \| `IJsonLdSetObject` \| `IJsonLdNodePrimitive`[] \| `IJsonLdLanguageMap` \| `IJsonLdIndexMap` \| `IJsonLdNodeObject`[] \| `IJsonLdIdMap` \| `IJsonLdTypeMap` \| `IJsonLdContextDefinition` \| `IJsonLdContextDefinitionElement`[] \| `string`[] \| `IJsonLdJsonObject` \| `IJsonLdJsonObject`[] \| \{\[`key`: `string`\]: `string`; \} \| `null` \| `undefined`
+\[`key`: `string`\]: `string` \| `number` \| `boolean` \| `IJsonLdNodeObject` \| `string`[] \| `IJsonLdGraphObject` \| `object` & `object` \| `object` & `object` \| `object` & `object` \| `IJsonLdListObject` \| `IJsonLdSetObject` \| `IJsonLdNodePrimitive`[] \| `IJsonLdLanguageMap` \| `IJsonLdIndexMap` \| `IJsonLdNodeObject`[] \| `IJsonLdIdMap` \| `IJsonLdTypeMap` \| `IJsonLdContextDefinition` \| `IJsonLdContextDefinitionElement`[] \| `IJsonLdJsonObject` \| `IJsonLdJsonObject`[] \| \{\[`key`: `string`\]: `string`; \} \| `null` \| `undefined`
 
 ## Properties
 

package/docs/reference/interfaces/ICatalogRequestRequest.md

@@ -9,3 +9,24 @@ The request parameters for the catalog request method.
 > **body**: `IDataspaceProtocolCatalogRequestMessage`
 
 The request body containing the catalog query.
+
+***
+
+### query?
+
+> `optional` **query**: `object`
+
+Optional query parameters for pagination.
+Used when following Link header URLs per DS Protocol spec.
+
+#### cursor?
+
+> `optional` **cursor**: `string`
+
+Opaque cursor token for pagination.
+
+#### limit?
+
+> `optional` **limit**: `string`
+
+Limit for pagination.

package/docs/reference/interfaces/ICatalogRequestResponse.md

@@ -1,11 +1,35 @@
 # Interface: ICatalogRequestResponse
 
 The response payload for the catalog request method.
+Returns a DS Protocol compliant Catalog with participantId, or CatalogError if no datasets found.
 
 ## Properties
 
+### statusCode?
+
+> `optional` **statusCode**: `HttpStatusCode`
+
+Response status code.
+Per DS Protocol: Returns appropriate HTTP code (e.g., 404) when returning CatalogError.
+
+***
+
 ### body
 
-> **body**: `IDcatCatalog`
+> **body**: `IDataspaceProtocolCatalog` \| `IDataspaceProtocolCatalogError`
+
+The response payload containing the DS Protocol compliant catalog with participantId,
+or a CatalogError if no datasets are found (404).
+Per DS Protocol: Single participant returns flat catalog, multiple participants return nested catalogs.
+
+***
+
+### headers?
+
+> `optional` **headers**: `object`
+
+Optional headers including RFC 8288 Link header for pagination.
+
+#### link?
 
-The response payload containing the catalog with matching datasets.
+> `optional` **link**: `string` \| `string`[]

package/docs/reference/interfaces/IFederatedCatalogueComponent.md

@@ -11,7 +11,7 @@ Provides Dataspace Protocol-compliant catalog endpoints for dataset registry and
 
 ### get()
 
-> **get**(`dataSetId`): `Promise`\<`IDcatDataset`\>
+> **get**(`dataSetId`): `Promise`\<`IDcatDataset` \| `IDataspaceProtocolCatalogError`\>
 
 Retrieve a dataset by its unique identifier.
 
@@ -25,13 +25,9 @@ The unique identifier of the dataset.
 
 #### Returns
 
-`Promise`\<`IDcatDataset`\>
+`Promise`\<`IDcatDataset` \| `IDataspaceProtocolCatalogError`\>
 
-The dataset if found.
-
-#### Throws
-
-NotFoundError if the dataset does not exist.
+The dataset if found, or a CatalogError if not found or an error occurs.
 
 ***
 
@@ -60,14 +56,17 @@ Nothing.
 
 ### query()
 
-> **query**(`filter?`): `Promise`\<`IDcatCatalog`\>
+> **query**(`filter?`, `cursor?`, `limit?`): `Promise`\<\{ `catalog`: `IDataspaceProtocolCatalog` \| `IDataspaceProtocolCatalogError`; `cursor?`: `string`; \}\>
 
 Execute a query against the catalogue using registered filter plugins.
-Returns a complete DCAT Catalog object with proper JSON-LD context, metadata, and datasets.
-Filter plugins must be registered in FilterFactory before service initialization.
-The filter payload is evaluated by the appropriate filter plugin based on its structure.
-Pagination properties (cursor, limit) and filter type (@type) should be included
-within the filter object per Eclipse Dataspace Protocol JSON-LD extension patterns.
+Returns a DS Protocol compliant Catalog object with participantId.
+
+The root catalog's participantId is the requesting participant (from context).
+Own datasets (matching requestingParticipantId) go directly in root dataset[].
+Other participants' datasets are grouped in nested catalog[] entries.
+
+For anonymous requests (no context), uses the first publisher found as fallback.
+Returns CatalogError 404 when no datasets exist.
 
 #### Parameters
 
@@ -75,13 +74,26 @@ within the filter object per Eclipse Dataspace Protocol JSON-LD extension patter
 
 `unknown`[]
 
-The filter criteria containing @type, optional cursor and limit properties.
+The filter criteria containing @type.
+
+##### cursor?
+
+`string`
+
+Optional cursor for pagination.
+
+##### limit?
+
+`number`
+
+Optional limit for pagination.
 
 #### Returns
 
-`Promise`\<`IDcatCatalog`\>
+`Promise`\<\{ `catalog`: `IDataspaceProtocolCatalog` \| `IDataspaceProtocolCatalogError`; `cursor?`: `string`; \}\>
 
-Complete ICatalog object with @context, @id, @type, dcat:dataset, and optional cursor.
+Complete IDataspaceProtocolCatalog with @context, @id, @type, participantId, dataset/catalog,
+or IDataspaceProtocolCatalogError if no datasets found.
 
 #### Throws
 

package/docs/reference/interfaces/IFederatedCatalogueFilter.md

@@ -12,11 +12,10 @@ Filters are registered by name in the FilterFactory and do not need to self-iden
 
 ### query()
 
-> **query**(`filter`): `Promise`\<\{ `datasets`: `IDcatDataset`[]; `cursor?`: `string`; \}\>
+> **query**(`filter`, `cursor?`, `limit?`): `Promise`\<\{ `datasets`: `IDcatDataset`[]; `cursor?`: `string`; \}\>
 
 Execute a filter-specific query over the catalogue.
 Each filter interprets the payload according to its own semantics.
-Pagination properties (cursor, limit) are extracted from the filter object by the service layer.
 
 #### Parameters
 
@@ -26,6 +25,18 @@ Pagination properties (cursor, limit) are extracted from the filter object by th
 
 The filter criteria (structure depends on the filter implementation).
 
+##### cursor?
+
+`string`
+
+The pagination cursor from the previous query, if any.
+
+##### limit?
+
+`number`
+
+The maximum number of results to return.
+
 #### Returns
 
 `Promise`\<\{ `datasets`: `IDcatDataset`[]; `cursor?`: `string`; \}\>

package/docs/reference/interfaces/IGetDatasetResponse.md

@@ -4,8 +4,16 @@ The response payload for the get dataset method.
 
 ## Properties
 
+### statusCode?
+
+> `optional` **statusCode**: `HttpStatusCode`
+
+Response status code.
+
+***
+
 ### body
 
-> **body**: `IDcatDataset`
+> **body**: `IDcatDataset` \| `IDataspaceProtocolCatalogError`
 
-The response payload containing the dataset.
+The response payload containing the dataset or error.

package/package.json

@@ -1,13 +1,13 @@
 {
 	"name": "@twin.org/federated-catalogue-models",
-	"version": "0.0.3-next.4",
+	"version": "0.0.3-next.5",
 	"description": "Models which define the structure of the Federated Catalogue Service",
 	"repository": {
 		"type": "git",
 		"url": "https://github.com/twinfoundation/federated-catalogue.git",
 		"directory": "packages/federated-catalogue-models"
 	},
-	"author": "jose.cantera@iota.org",
+	"author": "cornel.filip@iota.org",
 	"license": "Apache-2.0",
 	"type": "module",
 	"engines": {
@@ -20,7 +20,8 @@
 		"@twin.org/entity": "next",
 		"@twin.org/nameof": "next",
 		"@twin.org/standards-dataspace-protocol": "next",
-		"@twin.org/standards-w3c-dcat": "next"
+		"@twin.org/standards-w3c-dcat": "next",
+		"@twin.org/web": "next"
 	},
 	"main": "./dist/es/index.js",
 	"types": "./dist/types/index.d.ts",

package/dist/es/models/federatedCatalogueContexts.js

@@ -1,13 +0,0 @@
-// Copyright 2024 IOTA Stiftung.
-// SPDX-License-Identifier: Apache-2.0.
-/**
- * The contexts of federated catalogue data.
- */
-// eslint-disable-next-line @typescript-eslint/naming-convention
-export const FederatedCatalogueContexts = {
-    /**
-     * The context root for the federated catalogue types.
-     */
-    ContextRoot: "https://schema.twindev.org/federated-catalogue/"
-};
-//# sourceMappingURL=federatedCatalogueContexts.js.map

package/dist/es/models/federatedCatalogueContexts.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"federatedCatalogueContexts.js","sourceRoot":"","sources":["../../../src/models/federatedCatalogueContexts.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AAEvC;;GAEG;AACH,gEAAgE;AAChE,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACzC;;OAEG;IACH,WAAW,EAAE,iDAAiD;CACrD,CAAC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * The contexts of federated catalogue data.\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport const FederatedCatalogueContexts = {\n\t/**\n\t * The context root for the federated catalogue types.\n\t */\n\tContextRoot: \"https://schema.twindev.org/federated-catalogue/\"\n} as const;\n\n/**\n * The contexts of federated catalogue data.\n */\nexport type FederatedCatalogueContexts =\n\t(typeof FederatedCatalogueContexts)[keyof typeof FederatedCatalogueContexts];\n"]}

package/dist/types/models/federatedCatalogueContexts.d.ts

@@ -1,13 +0,0 @@
-/**
- * The contexts of federated catalogue data.
- */
-export declare const FederatedCatalogueContexts: {
-    /**
-     * The context root for the federated catalogue types.
-     */
-    readonly ContextRoot: "https://schema.twindev.org/federated-catalogue/";
-};
-/**
- * The contexts of federated catalogue data.
- */
-export type FederatedCatalogueContexts = (typeof FederatedCatalogueContexts)[keyof typeof FederatedCatalogueContexts];

package/docs/reference/type-aliases/FederatedCatalogueContexts.md

@@ -1,5 +0,0 @@
-# Type Alias: FederatedCatalogueContexts
-
-> **FederatedCatalogueContexts** = *typeof* [`FederatedCatalogueContexts`](../variables/FederatedCatalogueContexts.md)\[keyof *typeof* [`FederatedCatalogueContexts`](../variables/FederatedCatalogueContexts.md)\]
-
-The contexts of federated catalogue data.

package/docs/reference/variables/FederatedCatalogueContexts.md

@@ -1,13 +0,0 @@
-# Variable: FederatedCatalogueContexts
-
-> `const` **FederatedCatalogueContexts**: `object`
-
-The contexts of federated catalogue data.
-
-## Type Declaration
-
-### ContextRoot
-
-> `readonly` **ContextRoot**: `"https://schema.twindev.org/federated-catalogue/"` = `"https://schema.twindev.org/federated-catalogue/"`
-
-The context root for the federated catalogue types.