httk.serve.dsp.models

Immutable records and protocol errors for the Data Space Protocol provider.

Attributes

FrozenJsonValue	An immutable JSON value snapshot.
JsonScalar	A JSON scalar -- string, number, boolean, or null.
JsonValue	An arbitrary JSON value modelled with ordinary mutable containers.
ErrorKind

Exceptions

DspProtocolError	Represent a protocol failure that an HTTP adapter can serialize directly.
DspTransitionSuperseded	Report that a callback was delivered but a concurrent transition won the commit.

Classes

DeliveryStatus	Describe delivery health without claiming an unacknowledged DSP transition.
OfferProfile	Describe the one static, unconditional offer exposed by the provider.
DataServiceProfile	Describe the single service through which the dataset is delivered.
DcatDataServiceProfile	Describe a public API included only in the owned DCAT projection.
DistributionProfile	Describe the one pull distribution for the provider dataset.
DatasetProfile	Group one dataset with its DSP offer, distribution, and data address.
CatalogueProfile	Describe the immutable multi-dataset catalogue served by this provider.
AgreementRecord	Record the provider-created agreement associated with a negotiation.
NegotiationRecord	Record an in-memory contract negotiation and its acknowledged state.
TransferRecord	Record an in-memory transfer process and its acknowledged state.

Functions

freeze_json(value)	Freeze a JSON-compatible value without retaining caller-owned containers.
thaw_json(value)	Return an independent ordinary JSON value from an immutable snapshot.

Module Contents

type httk.serve.dsp.models.FrozenJsonValue = JsonScalar | tuple['FrozenJsonValue', ...] | Mapping[str, 'FrozenJsonValue']

An immutable JSON value snapshot.

The mapping arm is typed as Mapping so a plain mutable dict satisfies it statically, while freeze_json() guarantees a MappingProxyType at runtime. This static/runtime gap is intentional and is not closed here.

type httk.serve.dsp.models.JsonScalar = str | int | float | bool | None

A JSON scalar – string, number, boolean, or null.

type httk.serve.dsp.models.JsonValue = JsonScalar | list['JsonValue'] | dict[str, 'JsonValue']

An arbitrary JSON value modelled with ordinary mutable containers.

httk.serve.dsp.models.freeze_json(value)

Freeze a JSON-compatible value without retaining caller-owned containers.

Parameters:

value (object) – JSON-compatible value to copy into an immutable representation.

Returns:

An immutable JSON-compatible value.

Raises:

• TypeError – If value is not JSON-compatible.

• ValueError – If a floating-point value is non-finite.

Return type:

FrozenJsonValue

httk.serve.dsp.models.thaw_json(value)

Return an independent ordinary JSON value from an immutable snapshot.

Parameters:

value (FrozenJsonValue) – Immutable JSON-compatible value to copy.

Returns:

Plain JSON-compatible lists and dictionaries.

Return type:

JsonValue

type httk.serve.dsp.models.ErrorKind = Literal['catalog', 'negotiation', 'transfer']

class httk.serve.dsp.models.DeliveryStatus

Describe delivery health without claiming an unacknowledged DSP transition.

Parameters:

• last_error – Most recent callback failure, if any.

• retry_count – Number of delivery attempts made for the last callback.

• out_of_sync – Whether the remote peer may not have the acknowledged local state.

last_error: str | None = None

retry_count: int = 0

out_of_sync: bool = False

class httk.serve.dsp.models.OfferProfile

Describe the one static, unconditional offer exposed by the provider.

Parameters:

• id – Stable offer identifier.

• target – Dataset identifier to which a message offer must refer.

id: str

target: str

class httk.serve.dsp.models.DataServiceProfile

Describe the single service through which the dataset is delivered.

Parameters:

• id – Stable data-service identifier.

• title – Human-readable service title.

• endpoint_url – HTTPS endpoint used for data delivery.

id: str

title: str

endpoint_url: str

conforms_to: tuple[str, Ellipsis]

serves_dataset_ids: tuple[str, Ellipsis]

class httk.serve.dsp.models.DcatDataServiceProfile

Describe a public API included only in the owned DCAT projection.

Parameters:

• id – Stable service identifier.

• title – Human-readable service title.

• endpoint_url – Public HTTPS API endpoint.

• conforms_to – Technical standards implemented by the service.

• serves_dataset_ids – Catalogue dataset identifiers served by the API.

• endpoint_description – Optional IRI describing the API interface.

id: str

title: str

endpoint_url: str

conforms_to: tuple[str, Ellipsis]

serves_dataset_ids: tuple[str, Ellipsis]

endpoint_description: str | None

class httk.serve.dsp.models.DistributionProfile

Describe the one pull distribution for the provider dataset.

Parameters:

• id – Stable distribution identifier.

• format – DSP transfer format advertised for the distribution.

• access_url – HTTPS URL from which data are pulled.

• data_service – Embedded service description for DSP catalogue output.

id: str

format: str

file_format: str

media_type: str

access_url: str

data_service: DataServiceProfile

byte_size: int | None = None

sha256: str | None = None

class httk.serve.dsp.models.DatasetProfile

Group one dataset with its DSP offer, distribution, and data address.

Parameters:

• dataset – Protocol-neutral dataset metadata.

• offer – Unconditional ODRL use offer for this dataset.

• distribution – Pull distribution advertised for this dataset.

• data_service – Service embedded in the distribution.

• data_address – Immutable pull address returned for authorized transfers.

dataset: httk.core.Dataset

offer: OfferProfile

distribution: DistributionProfile

data_service: DataServiceProfile

data_address: collections.abc.Mapping[str, httk.serve.jsondata.FrozenJsonValue]

class httk.serve.dsp.models.CatalogueProfile

Describe the immutable multi-dataset catalogue served by this provider.

Parameters:

• id – Stable catalogue identifier.

• title – Human-readable catalogue title.

• description – Human-readable catalogue description.

• participant_id – Provider participant identifier.

• dcat_ap_profile – Configured minimal DCAT-AP profile IRI.

• datasets – Dataset publication profiles in stable declaration order.

• dcat_data_services – Additional public APIs for the DCAT projection.

id: str

title: str

description: str

participant_id: str

dcat_ap_profile: str

datasets: tuple[DatasetProfile, Ellipsis]

dcat_data_services: tuple[DcatDataServiceProfile, Ellipsis]

class httk.serve.dsp.models.AgreementRecord

Record the provider-created agreement associated with a negotiation.

Parameters:

• id – Unique agreement identifier in urn:uuid: form.

• policy – Immutable agreement policy JSON.

• target – Dataset identifier covered by the agreement.

• assigner – Provider participant identifier.

• assignee – Consumer participant identifier.

• timestamp – UTC XML Schema date-time at which the agreement was created.

id: str

policy: collections.abc.Mapping[str, httk.serve.jsondata.FrozenJsonValue]

target: str

assigner: str

assignee: str

timestamp: str

class httk.serve.dsp.models.NegotiationRecord

Record an in-memory contract negotiation and its acknowledged state.

Parameters:

• provider_pid – Provider process identifier.

• consumer_pid – Consumer process identifier.

• callback_address – Consumer callback base URL.

• state – Last state acknowledged by both protocol processing and callback delivery.

• policy – Immutable message offer accepted for the negotiation.

• agreement – Created agreement after an agreement callback is acknowledged.

• pending_transition – Reserved transition token, if a callback is currently in flight.

• delivery – Local delivery health for the latest callback.

provider_pid: str

consumer_pid: str

callback_address: str

state: str

policy: collections.abc.Mapping[str, httk.serve.jsondata.FrozenJsonValue]

agreement: AgreementRecord | None = None

pending_transition: str | None = None

delivery: DeliveryStatus

class httk.serve.dsp.models.TransferRecord

Record an in-memory transfer process and its acknowledged state.

Parameters:

• provider_pid – Provider transfer-process identifier.

• consumer_pid – Consumer transfer-process identifier.

• callback_address – Consumer callback base URL.

• agreement_id – Finalized agreement authorizing this transfer.

• format – Requested transfer format.

• state – Last state acknowledged by both protocol processing and callback delivery.

• pending_transition – Reserved transition token, if a callback is currently in flight.

• delivery – Local delivery health for the latest callback.

provider_pid: str

consumer_pid: str

callback_address: str

agreement_id: str

format: str

state: str

pending_transition: str | None = None

delivery: DeliveryStatus

exception httk.serve.dsp.models.DspProtocolError(kind, status_code, detail, *, code=None, provider_pid=None, consumer_pid=None)

Bases: Exception

Represent a protocol failure that an HTTP adapter can serialize directly.

Parameters:

• kind (ErrorKind) – DSP area whose official error document must be emitted.

• status_code (int) – HTTP status suitable for the adapter response.

• detail (str) – Safe human-readable failure detail.

• code (str | None) – Optional machine-readable DSP error code.

• provider_pid (str | None) – Provider process identifier, when one is known.

• consumer_pid (str | None) – Consumer process identifier, when one is known.

kind

status_code

detail

code = None

provider_pid = None

consumer_pid = None

as_document()

Serialize this failure as the official DSP JSON error document.

Returns:

Error document for the exception’s DSP area.

Return type:

dict[str, httk.serve.jsondata.JsonValue]

exception httk.serve.dsp.models.DspTransitionSuperseded

Bases: RuntimeError

Report that a callback was delivered but a concurrent transition won the commit.

This is not a protocol error: by the time it is raised the peer callback has already been delivered successfully, and only the local commit lost a race with a concurrent state transition. There is nothing to report on the wire and no HTTP status to carry, so it deliberately does not subclass DspProtocolError.