Skip to main content

The ingest model

Vista Gateway accepts ISO 19848 data, other registered JSON data types, and attachments. They share the same concepts for identifying who sends the data, which customer it is for, and which asset it concerns.

Core concepts​

ConceptMeaning
Customer (tenant)The customer on whose behalf data is sent. This is separate from the asset identifier.
Data providerThe party sending data on behalf of a customer. When sending your own data, you are both customer and provider.
ConnectionThe relationship between one customer and one data provider, authenticated by its API key.
Data governance policyDefines the rights and restrictions governing how submitted data may be used and shared on behalf of a customer.
AssetThe ship or other unit the data concerns, identified by an asset ID.
Data typeA versioned definition of a JSON payload, such as a checklist or an ISO 19848 package type.
PackageAn individual JSON submission. Successful ingest returns a Gateway-assigned packageId.
AttachmentA file uploaded separately and linked to an existing package.

Customers, connections, and assets​

The API key identifies the connection between a customer and a data provider. That connection is not scoped to a ship or a data type. The same connection can send different data types for multiple assets belonging to that customer. A provider serving another customer uses that customer's separate key, even if the payload structure is identical.

The asset ID describes which asset the data concerns; it does not determine which customer the data is sent for. ISO 19848 packages carry the asset ID in Package.Header.ShipID. The experimental data-type route carries it in the URL as {assetId}.

For example, a provider can send measurements and checklists for several ships belonging to customer A through A's connection. Data for customer B must use B's connection instead. Both connections use keys issued for the target environment. See authentication for selecting and storing keys.

Data governance policies​

Authentication and data governance answer different questions. The connection identifies who is sending data and which customer it is for. A data governance policy defines who may use that data and under what conditions. The API key remains scoped to the customer + data provider connection, not to the policy.

Each ingested package is associated with a data governance policy managed on behalf of the customer. Depending on the agreed rights, a policy can restrict access to specified applications, permit broader use within DNV with only anonymized and aggregated use externally, or allow unrestricted use and sharing. Sending data to the Gateway does not automatically make it available to every DNV service.

The Gateway uses these policies to control access to submitted data. Services that receive the data must also respect its usage and onward-sharing restrictions. Contact your DNV representative to clarify the rights that apply to your data or to arrange changes to them.

Data types and packages​

A data type defines the format; a package is one submission in that format. Many packages can use the same data type and version. Registered types can have a JSON schema and additional validation rules that apply to incoming payloads.

An experimental data type supports an agreed format while it is being developed. The type must be registered before packages can be submitted. Its version identifies the payload contract, not an individual submission or an asset.

The Gateway's packageId identifies the accepted submission. Your optional external ID connects it to a source-system record, while a correlation ID can connect related requests. Those metadata fields are not a deduplication contract; see delivery and batching.

Packages and attachments​

A report, image, or raw export can be uploaded as an attachment after its parent JSON package has been ingested. The parent package supplies the context, and its Gateway-assigned packageId links the file to that submission.

The parent and attachment use the same connection. An attachment has its own attachmentPackageId, separate from the parentPackageId. Accepting the parent does not mean the file has also been uploaded: these are separate requests.

Why ISO 19848 uses two package types​

ISO 19848 separates channel definitions from measurements. Vista Gateway accepts both as JSON packages through POST /ISO19848/.

The DataChannelList describes what a measurement means: its identifier, format, units, and other metadata. TimeSeriesData carries the measurements or events themselves. Keeping the description separate avoids repeating that metadata in every measurement package.

PackageContents
DataChannelListChannel identifiers, mappings, and properties such as format, units, and range
TimeSeriesDataTimestamped measurement rows (TabularData) or individual events (EventData)

A channel's ShortID connects a source-system identifier to its standardized LocalID. TimeSeriesData can therefore use source identifiers while retaining the context supplied by the channel list.

Configuration references​

The configuration reference (ID and TimeStamp) connects measurements to a particular DataChannelList revision. Sending the list before the measurements allows the Gateway to interpret the referenced channels. An explicit reference also avoids ambiguity when channel definitions change.

The reference is defined in Package.Header.DataChannelListID in the DataChannelList and repeated in DataConfiguration in the corresponding TimeSeriesData entry. It is not the Gateway's packageId, which identifies an individual submission.

The channel list and measurements referencing it are sent through the same connection.