@twin.org/standards-dataspace-protocol 0.0.3-next.2 → 0.0.3-next.20

package/dist/es/schemas/DataspaceProtocolTransferError.json

@@ -0,0 +1,87 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schema.twindev.org/dataspace-protocol/DataspaceProtocolTransferError",
+    "description": "Interface for Dataspace Protocol Transfer Messages. https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol#error-transfer-error",
+    "type": "object",
+    "properties": {
+        "@context": {
+            "description": "The Dataspace Protocol JSON-LD context type.",
+            "anyOf": [
+                {
+                    "type": "string",
+                    "const": "https://w3id.org/dspace/2025/1/context.jsonld"
+                },
+                {
+                    "type": "array",
+                    "items": {
+                        "type": "string",
+                        "const": "https://w3id.org/dspace/2025/1/context.jsonld"
+                    },
+                    "minItems": 1,
+                    "maxItems": 1
+                },
+                {
+                    "type": "array",
+                    "minItems": 2,
+                    "prefixItems": [
+                        {
+                            "type": "string",
+                            "const": "https://w3id.org/dspace/2025/1/context.jsonld"
+                        },
+                        {
+                            "$ref": "https://schema.twindev.org/json-ld/JsonLdContextDefinitionElement"
+                        }
+                    ],
+                    "items": {
+                        "$ref": "https://schema.twindev.org/json-ld/JsonLdContextDefinitionElement"
+                    }
+                },
+                {
+                    "type": "array",
+                    "minItems": 2,
+                    "prefixItems": [
+                        {
+                            "$ref": "https://schema.twindev.org/json-ld/JsonLdContextDefinitionElement"
+                        },
+                        {
+                            "type": "string",
+                            "const": "https://w3id.org/dspace/2025/1/context.jsonld"
+                        }
+                    ],
+                    "items": {
+                        "$ref": "https://schema.twindev.org/json-ld/JsonLdContextDefinitionElement"
+                    }
+                }
+            ]
+        },
+        "@type": {
+            "type": "string",
+            "const": "TransferError",
+            "description": "LD Type"
+        },
+        "consumerPid": {
+            "type": "string",
+            "description": "MUST refer to the transfer identifier of the Consumer side."
+        },
+        "providerPid": {
+            "type": "string",
+            "description": "MUST refer to the transfer identifier of the Provider side."
+        },
+        "code": {
+            "type": "string",
+            "description": "The error code."
+        },
+        "reason": {
+            "type": "array",
+            "items": {},
+            "description": "The error reason(s)."
+        }
+    },
+    "required": [
+        "@context",
+        "@type",
+        "consumerPid",
+        "providerPid"
+    ],
+    "additionalProperties": false
+}

package/dist/es/schemas/DataspaceProtocolTransferProcess.json

@@ -0,0 +1,83 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schema.twindev.org/dataspace-protocol/DataspaceProtocolTransferProcess",
+    "description": "Interface for Dataspace Protocol Transfer Messages. https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#ack-transfer-process",
+    "type": "object",
+    "properties": {
+        "@context": {
+            "description": "The Dataspace Protocol JSON-LD context type.",
+            "anyOf": [
+                {
+                    "type": "string",
+                    "const": "https://w3id.org/dspace/2025/1/context.jsonld"
+                },
+                {
+                    "type": "array",
+                    "items": {
+                        "type": "string",
+                        "const": "https://w3id.org/dspace/2025/1/context.jsonld"
+                    },
+                    "minItems": 1,
+                    "maxItems": 1
+                },
+                {
+                    "type": "array",
+                    "minItems": 2,
+                    "prefixItems": [
+                        {
+                            "type": "string",
+                            "const": "https://w3id.org/dspace/2025/1/context.jsonld"
+                        },
+                        {
+                            "$ref": "https://schema.twindev.org/json-ld/JsonLdContextDefinitionElement"
+                        }
+                    ],
+                    "items": {
+                        "$ref": "https://schema.twindev.org/json-ld/JsonLdContextDefinitionElement"
+                    }
+                },
+                {
+                    "type": "array",
+                    "minItems": 2,
+                    "prefixItems": [
+                        {
+                            "$ref": "https://schema.twindev.org/json-ld/JsonLdContextDefinitionElement"
+                        },
+                        {
+                            "type": "string",
+                            "const": "https://w3id.org/dspace/2025/1/context.jsonld"
+                        }
+                    ],
+                    "items": {
+                        "$ref": "https://schema.twindev.org/json-ld/JsonLdContextDefinitionElement"
+                    }
+                }
+            ]
+        },
+        "@type": {
+            "type": "string",
+            "const": "TransferProcess",
+            "description": "LD Type"
+        },
+        "consumerPid": {
+            "type": "string",
+            "description": "MUST refer to the transfer identifier of the Consumer side."
+        },
+        "providerPid": {
+            "type": "string",
+            "description": "MUST refer to the transfer identifier of the Provider side."
+        },
+        "state": {
+            "$ref": "https://schema.twindev.org/dataspace-protocol/DataspaceProtocolTransferProcessStateType",
+            "description": "The transfer process state."
+        }
+    },
+    "required": [
+        "@context",
+        "@type",
+        "consumerPid",
+        "providerPid",
+        "state"
+    ],
+    "additionalProperties": false
+}

package/dist/es/schemas/DataspaceProtocolTransferRequestMessage.json

@@ -0,0 +1,92 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schema.twindev.org/dataspace-protocol/DataspaceProtocolTransferRequestMessage",
+    "description": "Interface for Dataspace Protocol Transfer Messages. https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#transfer-request-message",
+    "type": "object",
+    "properties": {
+        "@context": {
+            "description": "The Dataspace Protocol JSON-LD context type.",
+            "anyOf": [
+                {
+                    "type": "string",
+                    "const": "https://w3id.org/dspace/2025/1/context.jsonld"
+                },
+                {
+                    "type": "array",
+                    "items": {
+                        "type": "string",
+                        "const": "https://w3id.org/dspace/2025/1/context.jsonld"
+                    },
+                    "minItems": 1,
+                    "maxItems": 1
+                },
+                {
+                    "type": "array",
+                    "minItems": 2,
+                    "prefixItems": [
+                        {
+                            "type": "string",
+                            "const": "https://w3id.org/dspace/2025/1/context.jsonld"
+                        },
+                        {
+                            "$ref": "https://schema.twindev.org/json-ld/JsonLdContextDefinitionElement"
+                        }
+                    ],
+                    "items": {
+                        "$ref": "https://schema.twindev.org/json-ld/JsonLdContextDefinitionElement"
+                    }
+                },
+                {
+                    "type": "array",
+                    "minItems": 2,
+                    "prefixItems": [
+                        {
+                            "$ref": "https://schema.twindev.org/json-ld/JsonLdContextDefinitionElement"
+                        },
+                        {
+                            "type": "string",
+                            "const": "https://w3id.org/dspace/2025/1/context.jsonld"
+                        }
+                    ],
+                    "items": {
+                        "$ref": "https://schema.twindev.org/json-ld/JsonLdContextDefinitionElement"
+                    }
+                }
+            ]
+        },
+        "@type": {
+            "type": "string",
+            "const": "TransferRequestMessage",
+            "description": "LD Type"
+        },
+        "agreementId": {
+            "type": "string",
+            "description": "MUST refer to an existing Agreement between the Consumer and Provider."
+        },
+        "callbackAddress": {
+            "type": "string",
+            "description": "MUST be a URI indicating where messages to the Consumer SHOULD be sent."
+        },
+        "consumerPid": {
+            "type": "string",
+            "description": "MUST refer to the transfer identifier of the Consumer side."
+        },
+        "format": {
+            "type": "string",
+            "description": "The format property is a format specified by a Distribution for the Dataset associated with the Agreement. This is generally obtained from the Provider's Catalog."
+        },
+        "dataAddress": {
+            "$ref": "https://schema.twindev.org/dataspace-protocol/DataspaceProtocolDataAddress",
+            "description": "If defined MUST contain a transport-specific set of properties for pushing the data. It MAY include an endpoint, a temporary authorization via the endpointProperties property - depending on the endpointType."
+        }
+    },
+    "required": [
+        "@context",
+        "@type",
+        "agreementId",
+        "callbackAddress",
+        "consumerPid",
+        "format"
+    ],
+    "additionalProperties": false
+}

package/dist/es/schemas/DataspaceProtocolTransferStartMessage.json

@@ -0,0 +1,82 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schema.twindev.org/dataspace-protocol/DataspaceProtocolTransferStartMessage",
+    "description": "Interface for Dataspace Protocol Transfer Messages. https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#transfer-start-message",
+    "type": "object",
+    "properties": {
+        "@context": {
+            "description": "The Dataspace Protocol JSON-LD context type.",
+            "anyOf": [
+                {
+                    "type": "string",
+                    "const": "https://w3id.org/dspace/2025/1/context.jsonld"
+                },
+                {
+                    "type": "array",
+                    "items": {
+                        "type": "string",
+                        "const": "https://w3id.org/dspace/2025/1/context.jsonld"
+                    },
+                    "minItems": 1,
+                    "maxItems": 1
+                },
+                {
+                    "type": "array",
+                    "minItems": 2,
+                    "prefixItems": [
+                        {
+                            "type": "string",
+                            "const": "https://w3id.org/dspace/2025/1/context.jsonld"
+                        },
+                        {
+                            "$ref": "https://schema.twindev.org/json-ld/JsonLdContextDefinitionElement"
+                        }
+                    ],
+                    "items": {
+                        "$ref": "https://schema.twindev.org/json-ld/JsonLdContextDefinitionElement"
+                    }
+                },
+                {
+                    "type": "array",
+                    "minItems": 2,
+                    "prefixItems": [
+                        {
+                            "$ref": "https://schema.twindev.org/json-ld/JsonLdContextDefinitionElement"
+                        },
+                        {
+                            "type": "string",
+                            "const": "https://w3id.org/dspace/2025/1/context.jsonld"
+                        }
+                    ],
+                    "items": {
+                        "$ref": "https://schema.twindev.org/json-ld/JsonLdContextDefinitionElement"
+                    }
+                }
+            ]
+        },
+        "@type": {
+            "type": "string",
+            "const": "TransferStartMessage",
+            "description": "LD Type"
+        },
+        "consumerPid": {
+            "type": "string",
+            "description": "MUST refer to the transfer identifier of the Consumer side."
+        },
+        "providerPid": {
+            "type": "string",
+            "description": "MUST refer to the transfer identifier of the Provider side."
+        },
+        "dataAddress": {
+            "$ref": "https://schema.twindev.org/dataspace-protocol/DataspaceProtocolDataAddress",
+            "description": "MUST be provided if the current transfer is a pull transfer and contains a transport-specific endpoint address for obtaining the data."
+        }
+    },
+    "required": [
+        "@context",
+        "@type",
+        "consumerPid",
+        "providerPid"
+    ],
+    "additionalProperties": false
+}

package/dist/es/schemas/DataspaceProtocolTransferSuspensionMessage.json

@@ -0,0 +1,87 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schema.twindev.org/dataspace-protocol/DataspaceProtocolTransferSuspensionMessage",
+    "description": "Interface for Dataspace Protocol Transfer Messages. https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#transfer-suspension-message",
+    "type": "object",
+    "properties": {
+        "@context": {
+            "description": "The Dataspace Protocol JSON-LD context type.",
+            "anyOf": [
+                {
+                    "type": "string",
+                    "const": "https://w3id.org/dspace/2025/1/context.jsonld"
+                },
+                {
+                    "type": "array",
+                    "items": {
+                        "type": "string",
+                        "const": "https://w3id.org/dspace/2025/1/context.jsonld"
+                    },
+                    "minItems": 1,
+                    "maxItems": 1
+                },
+                {
+                    "type": "array",
+                    "minItems": 2,
+                    "prefixItems": [
+                        {
+                            "type": "string",
+                            "const": "https://w3id.org/dspace/2025/1/context.jsonld"
+                        },
+                        {
+                            "$ref": "https://schema.twindev.org/json-ld/JsonLdContextDefinitionElement"
+                        }
+                    ],
+                    "items": {
+                        "$ref": "https://schema.twindev.org/json-ld/JsonLdContextDefinitionElement"
+                    }
+                },
+                {
+                    "type": "array",
+                    "minItems": 2,
+                    "prefixItems": [
+                        {
+                            "$ref": "https://schema.twindev.org/json-ld/JsonLdContextDefinitionElement"
+                        },
+                        {
+                            "type": "string",
+                            "const": "https://w3id.org/dspace/2025/1/context.jsonld"
+                        }
+                    ],
+                    "items": {
+                        "$ref": "https://schema.twindev.org/json-ld/JsonLdContextDefinitionElement"
+                    }
+                }
+            ]
+        },
+        "@type": {
+            "type": "string",
+            "const": "TransferSuspensionMessage",
+            "description": "LD Type"
+        },
+        "consumerPid": {
+            "type": "string",
+            "description": "MUST refer to the transfer identifier of the Consumer side."
+        },
+        "providerPid": {
+            "type": "string",
+            "description": "MUST refer to the transfer identifier of the Provider side."
+        },
+        "code": {
+            "type": "string",
+            "description": "The suspension code."
+        },
+        "reason": {
+            "type": "array",
+            "items": {},
+            "description": "The suspension reason(s)."
+        }
+    },
+    "required": [
+        "@context",
+        "@type",
+        "consumerPid",
+        "providerPid"
+    ],
+    "additionalProperties": false
+}

package/dist/es/schemas/DataspaceProtocolTransferTerminationMessage.json

@@ -0,0 +1,87 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schema.twindev.org/dataspace-protocol/DataspaceProtocolTransferTerminationMessage",
+    "description": "Interface for Dataspace Protocol Transfer Messages. https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#transfer-termination-message",
+    "type": "object",
+    "properties": {
+        "@context": {
+            "description": "The Dataspace Protocol JSON-LD context type.",
+            "anyOf": [
+                {
+                    "type": "string",
+                    "const": "https://w3id.org/dspace/2025/1/context.jsonld"
+                },
+                {
+                    "type": "array",
+                    "items": {
+                        "type": "string",
+                        "const": "https://w3id.org/dspace/2025/1/context.jsonld"
+                    },
+                    "minItems": 1,
+                    "maxItems": 1
+                },
+                {
+                    "type": "array",
+                    "minItems": 2,
+                    "prefixItems": [
+                        {
+                            "type": "string",
+                            "const": "https://w3id.org/dspace/2025/1/context.jsonld"
+                        },
+                        {
+                            "$ref": "https://schema.twindev.org/json-ld/JsonLdContextDefinitionElement"
+                        }
+                    ],
+                    "items": {
+                        "$ref": "https://schema.twindev.org/json-ld/JsonLdContextDefinitionElement"
+                    }
+                },
+                {
+                    "type": "array",
+                    "minItems": 2,
+                    "prefixItems": [
+                        {
+                            "$ref": "https://schema.twindev.org/json-ld/JsonLdContextDefinitionElement"
+                        },
+                        {
+                            "type": "string",
+                            "const": "https://w3id.org/dspace/2025/1/context.jsonld"
+                        }
+                    ],
+                    "items": {
+                        "$ref": "https://schema.twindev.org/json-ld/JsonLdContextDefinitionElement"
+                    }
+                }
+            ]
+        },
+        "@type": {
+            "type": "string",
+            "const": "TransferTerminationMessage",
+            "description": "LD Type"
+        },
+        "consumerPid": {
+            "type": "string",
+            "description": "MUST refer to the transfer identifier of the Consumer side."
+        },
+        "providerPid": {
+            "type": "string",
+            "description": "MUST refer to the transfer identifier of the Provider side."
+        },
+        "code": {
+            "type": "string",
+            "description": "The termination code."
+        },
+        "reason": {
+            "type": "array",
+            "items": {},
+            "description": "The termination reason(s)."
+        }
+    },
+    "required": [
+        "@context",
+        "@type",
+        "consumerPid",
+        "providerPid"
+    ],
+    "additionalProperties": false
+}

package/dist/es/schemas-src/DataspaceProtocolDataService.json

@@ -0,0 +1,11 @@
+{
+    "$schema": "https://json-schema.org/draft/2019-09/schema",
+    "$id": "https://schema.twindev.org/dataspace-protocol/DsProtocolDataService",
+    "description": "DataService compliant with Eclipse Data Space Protocol. Validates only DS Protocol-specific requirements while allowing all optional DCAT properties.",
+    "title": "DataspaceProtocolDataService",
+    "allOf": [
+        {
+            "$ref": "https://w3id.org/dspace/2025/1/catalog/dataset-schema.json#/definitions/DataService"
+        }
+    ]
+}

package/dist/es/schemas-src/DataspaceProtocolDistribution.json

@@ -0,0 +1,11 @@
+{
+    "$schema": "https://json-schema.org/draft/2019-09/schema",
+    "$id": "https://schema.twindev.org/dataspace-protocol/DsProtocolDistribution",
+    "description": "Distribution compliant with Eclipse Data Space Protocol. Validates only DS Protocol-specific requirements while allowing all optional DCAT properties.",
+    "title": "DataspaceProtocolDistribution",
+    "allOf": [
+        {
+            "$ref": "https://w3id.org/dspace/2025/1/catalog/dataset-schema.json#/definitions/Distribution"
+        }
+    ]
+}

package/dist/es/utils/dataspaceProtocolHelper.js

@@ -0,0 +1,110 @@
+// Copyright 2025 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { GeneralError, Is, ObjectHelper } from "@twin.org/core";
+import { DataTypeHelper, JsonSchemaHelper } from "@twin.org/data-core";
+import { JsonLdHelper, JsonLdProcessor } from "@twin.org/data-json-ld";
+import { DcatContexts } from "@twin.org/standards-w3c-dcat";
+import { DataspaceProtocolContexts } from "../models/dataspaceProtocolContexts.js";
+import { DataspaceProtocolTransferProcessTypes } from "../models/transferProcess/dataspaceProtocolTransferProcessTypes.js";
+/**
+ * Dataspace protocol helper.
+ */
+export class DataspaceProtocolHelper {
+    /**
+     * The class name.
+     * @internal
+     */
+    static CLASS_NAME = "DataspaceProtocolHelper";
+    /**
+     * Checks whether the object passed as parameter is conformant to the DS Protocol definitions.
+     * @param object The object to check
+     * @param validationFailures the Validation failures obtained during the conformance checking.
+     * @returns true or false depending whether the object is conformant or not
+     */
+    static async checkConformance(object, validationFailures) {
+        let result = false;
+        const dcatNamespace = DcatContexts.Namespace;
+        const objectTypes = await JsonLdHelper.getType(object);
+        for (const type of objectTypes) {
+            let dataTypeIdentifier = type;
+            // If the DCAT3 types are used, convert to the DS Protocol equivalent
+            // which have the enhancements and constraints defined by the DS Protocol
+            if (type.startsWith(dcatNamespace)) {
+                const nonQualifiedType = type.replace(dcatNamespace, "");
+                dataTypeIdentifier = `${DataspaceProtocolContexts.Namespace}${nonQualifiedType}`;
+            }
+            const schema = await DataTypeHelper.getSchemaForType(dataTypeIdentifier);
+            if (!schema) {
+                throw new GeneralError(DataspaceProtocolHelper.CLASS_NAME, "schemaNotRegistered", {
+                    schemaId: dataTypeIdentifier
+                });
+            }
+            const normalizedObject = await DataspaceProtocolHelper.normalize(object);
+            const validationResult = await JsonSchemaHelper.validate(schema, normalizedObject);
+            result = validationResult.result;
+            if (!result && Is.array(validationResult.error)) {
+                for (const aError of validationResult.error) {
+                    const validationFailure = {
+                        property: aError.instancePath,
+                        reason: aError.message
+                    };
+                    validationFailures.push(validationFailure);
+                }
+            }
+        }
+        return result;
+    }
+    /**
+     * Normalizes the input object making it compliant with the DS Protocol specifications.
+     * @param object The input object.
+     * @returns The input object normalized.
+     */
+    static async normalize(object) {
+        const annotatedObject = DataspaceProtocolHelper.annotateLDContextForFormat(object);
+        // Determine if this is a message/transfer type (which expects Context) or a catalog type (which expects JsonLdContext)
+        const objectType = ObjectHelper.propertyGet(object, "@type");
+        const isTransferProcessType = Is.string(objectType) &&
+            (objectType.includes("Message") ||
+                objectType === DataspaceProtocolTransferProcessTypes.TransferProcess ||
+                objectType === DataspaceProtocolTransferProcessTypes.TransferError);
+        const contextToUse = isTransferProcessType
+            ? DataspaceProtocolContexts.Context
+            : DataspaceProtocolContexts.JsonLdContext;
+        const compactedObject = await JsonLdProcessor.compact(annotatedObject, [contextToUse]);
+        if (!Is.array(compactedObject["@context"])) {
+            ObjectHelper.propertySet(compactedObject, "@context", [
+                ObjectHelper.propertyGet(compactedObject, "@context")
+            ]);
+        }
+        return compactedObject;
+    }
+    /**
+     * Ensures format property has a proper LD Context.
+     * @param object The object.
+     * @returns a copy of the object annotated with the proper LD Context.
+     * @internal
+     */
+    static annotateLDContextForFormat(object) {
+        const result = ObjectHelper.clone(object);
+        // This step is needed before compaction as 'dcterms:format' is not defined originally as '@vocab'
+        // but it is in the DSP LD Context
+        const EXTRA_ANNOTATION = {
+            "dcterms:format": {
+                "@id": "dcterms:format",
+                "@type": "@vocab"
+            }
+        };
+        const ldContext = ObjectHelper.propertyGet(result, "@context");
+        if (Is.array(ldContext)) {
+            ldContext.push(EXTRA_ANNOTATION);
+        }
+        else if (Is.object(ldContext)) {
+            ObjectHelper.propertySet(result, "@context", { ...ldContext, ...EXTRA_ANNOTATION });
+        }
+        else if (Is.string(ldContext)) {
+            ObjectHelper.propertySet(result, "@context", [ldContext, EXTRA_ANNOTATION]);
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=dataspaceProtocolHelper.js.map