`digital-twin-registry/consumer/dataplane`

Step	Summary
`digital-twin-registry/consumer/dataplane/get_shell_descriptor`	Retrieve one of a counterparty's shell descriptors by ID.
`digital-twin-registry/consumer/dataplane/get_shell_descriptors`	List a counterparty's shell descriptors over a negotiated data plane.
`digital-twin-registry/consumer/dataplane/lookup_shell`	Search a counterparty's registry for shells matching specific asset IDs.
`digital-twin-registry/consumer/dataplane/lookup_shells_by_asset_link`	Search a counterparty's registry through `POST /lookup/shellsByAssetLink`.

`digital-twin-registry/consumer/dataplane/get_shell_descriptor`

Retrieve one of a counterparty's shell descriptors by ID.

The consumer-side reading of digital-twin-registry/provider/get_shell_descriptor: the same registry document, reached through the data-plane URL and EDR token a transfer published instead of the registry the run was seeded with. A registry that answers anything but 200 yields an empty descriptor; the status code stays on the response for a test to assert on.

Inputs

Parameter	Type	Required	Default	Also accepts	Description
`headers`	object	no	`{}`	—	Extra HTTP headers merged into the request.
`timeout`	number	no	`None`	—	Request timeout in seconds; the test's default is used when omitted.
`dataplane_url`	string	no	`''`	—	Data-plane URL of the counterparty's registry; falls back to the 'dataplane_url' context variable.
`edr_token`	string	no	`''`	—	EDR authorization token; falls back to the 'edr_token' context variable.
`aas_identifier`	string	yes	—	—	Identifier of the AAS shell descriptor.

Output — the value assertions and returns: read

An AAS descriptor as the registry returned it.

Field	Type	Description
`id`	string	Identifier of the descriptor.
`idShort`	string	Short, human-readable name.

Additional keys sent by the counterpart are passed through unchanged.

`digital-twin-registry/consumer/dataplane/get_shell_descriptors`

List a counterparty's shell descriptors over a negotiated data plane.

The consumer-side reading of the registry's GET /shell-descriptors — the same collection a provider populates with digital-twin-registry/provider/create_shell_descriptor, reached through the data-plane URL and EDR token a transfer published. The registry answers with whatever the counterparty's access rules let this consumer see; the answer is paged, so the cursor is returned alongside the descriptors.

Inputs

Parameter	Type	Required	Default	Also accepts	Description
`headers`	object	no	`{}`	—	Extra HTTP headers merged into the request.
`timeout`	number	no	`None`	—	Request timeout in seconds; the test's default is used when omitted.
`dataplane_url`	string	no	`''`	—	Data-plane URL of the counterparty's registry; falls back to the 'dataplane_url' context variable.
`edr_token`	string	no	`''`	—	EDR authorization token; falls back to the 'edr_token' context variable.
`limit`	integer	no	`None`	—	Maximum number of entries the registry may return in one page; its own default applies when omitted.
`cursor`	string	no	`None`	—	Cursor a previous page returned, to read the page after it.

Output — the value assertions and returns: read

One page of a shell lookup.

Field	Type	Description
`shell_ids`	list of string	Identifiers of the shells that matched.
`shell_descriptors`	list of object	The descriptor document of each matching shell.
`cursor`	string	Cursor of the next page, or null when this was the last one.

`digital-twin-registry/consumer/dataplane/lookup_shell`

Search a counterparty's registry for shells matching specific asset IDs.

This is the consumer's half of the DTR contract, and it is a different thing from digital-twin-registry/provider/get_shell_descriptor: that one reads a known shell out of the registry the run was seeded with, this one searches somebody else's over a negotiated data plane. The lookup returns identifiers, so each one is then read back as a descriptor — a test that only needs the identifiers reads shell_ids and ignores the rest.

Inputs

Parameter	Type	Required	Default	Also accepts	Description
`headers`	object	no	`{}`	—	Extra HTTP headers merged into the request.
`timeout`	number	no	`None`	—	Request timeout in seconds; the test's default is used when omitted.
`dataplane_url`	string	no	`''`	—	Data-plane URL of the counterparty's registry; falls back to the 'dataplane_url' context variable.
`edr_token`	string	no	`''`	—	EDR authorization token; falls back to the 'edr_token' context variable.
`specific_asset_ids`	list of SpecificAssetId	yes	—	—	Criteria the shell must match; all of them have to.

Output — the value assertions and returns: read

Shells a registry read returned.

Field	Type	Description
`shell_ids`	list of string	Identifiers of the shells that matched.
`shell_descriptors`	list of object	The descriptor document of each matching shell.

`digital-twin-registry/consumer/dataplane/lookup_shells_by_asset_link`

Search a counterparty's registry through POST /lookup/shellsByAssetLink.

The same search digital-twin-registry/consumer/dataplane/lookup_shell performs, addressed to the endpoint that carries the criteria in the request body instead of in base64url-encoded assetIds query values. That is what it is for: a query string has a length limit and a body does not, so a lookup with many criteria — or with long externalSubjectId scopes on them — is the case GET /lookup/shells cannot serve. The answer is paged, so the cursor is returned alongside the identifiers and their descriptors.

Inputs

Parameter	Type	Required	Default	Also accepts	Description
`headers`	object	no	`{}`	—	Extra HTTP headers merged into the request.
`timeout`	number	no	`None`	—	Request timeout in seconds; the test's default is used when omitted.
`dataplane_url`	string	no	`''`	—	Data-plane URL of the counterparty's registry; falls back to the 'dataplane_url' context variable.
`edr_token`	string	no	`''`	—	EDR authorization token; falls back to the 'edr_token' context variable.
`limit`	integer	no	`None`	—	Maximum number of entries the registry may return in one page; its own default applies when omitted.
`cursor`	string	no	`None`	—	Cursor a previous page returned, to read the page after it.
`specific_asset_ids`	list of SpecificAssetId	yes	—	—	Criteria the shell must match; all of them have to.

Output — the value assertions and returns: read

One page of a shell lookup.

Field	Type	Description
`shell_ids`	list of string	Identifiers of the shells that matched.
`shell_descriptors`	list of object	The descriptor document of each matching shell.
`cursor`	string	Cursor of the next page, or null when this was the last one.

Nested objects

SpecificAssetId

One specificAssetIds criterion a shell is searched by.

Field	Type	Required	Default	Also accepts	Description
`name`	string	yes	—	—	Name of the asset identifier, e.g. 'partInstanceId'.
`value`	string	yes	—	—	Value that identifier must have.

Additional keys sent by the counterpart are passed through unchanged.