1. Overview

An AIVA Package is a single distributable .aivapkg file containing the files required to import a log visualisation project into AIVA. The package bundles a manifest, a Blueprint, and the data files referenced by that Blueprint.

The package is a ZIP archive that uses the .aivapkg extension. It is intended to be self-contained: data files referenced by the Blueprint should be included in the package rather than resolved from external locations at import time.

This document describes the package contract: archive structure, manifest.json structure, property names, data types, defaults, validation constraints, examples, and how packaged Blueprint paths should reference data files.

2. Package Archive Structure

A valid Blueprint package has a root-level manifest, a root-level Blueprint file, and one or more data files under data/.

Only manifest.json and blueprint.json should be placed at the archive root. Data files should be placed inside data/, including any nested data folders.

Path rule: Blueprint data source paths in an .aivapkg should be relative paths from the archive root, for example data/well_001.las.

3. manifest.json

The manifest.json file sits at the root of every .aivapkg archive. It identifies the package manifest version and the type of content contained in the package.

The manifest object has two required top-level properties and one optional metadata object.

{
  "Version": "1",
  "PackageType": "Blueprint",
  "Metadata": {}
}

{
  "Version": "1",
  "PackageType": "Blueprint",
  "Metadata": {
    "Build-Number": "2026.04.01",
    "Depth": "3450"
  }
}

^[A-Za-z0-9._-]+$

{
  "Version": "1",
  "PackageType": "Blueprint",
  "Metadata": {
    "Build Number": "2026.04.01",
    "Depth": 3450
  }
}

4. blueprint.json

The blueprint.json file defines the visualisation project: project identity, source data files, colour maps, scenes, 2D tracks, optional 3D view configuration, scalar curves, array curves, synthetic curves, regions, statistics, and cross-sections.

For PackageType: "Blueprint", blueprint.json must be present at the archive root and must conform to the Blueprint Developer Contract.

Within an .aivapkg, data source paths in the Blueprint should resolve to files contained inside the package, normally under data/.

Important: Standalone Blueprint files may be authored independently, but packaged Blueprint files should not depend on absolute paths, UNC paths, local drive paths, or files outside the package archive.

5. Data Files

Data files are the physical source files referenced by blueprint.json. For LAS2 data sources, these are .las files referenced by the Blueprint data source configuration.

Example valid package data paths:

data/well_001.las
data/repeat_run.las
data/run-01/main.las

Example invalid package paths:

Invalid package paths:
/data/well_001.las
C:\data\well_001.las
\\server\share\well_001.las
../external/well_001.las

6. Import Validation Rules

The package importer validates both the manifest and the packaged project structure. The manifest schema is strict and does not allow unknown top-level manifest properties.

7. JSON Schema

The following schema defines the manifest.json contract for an AIVA package manifest.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://aiva-data.com/schemas/2026/04/aivapkg-manifest.json",
  "title": "AIVA Package Manifest",
  "description": "Defines the manifest file used to describe an AIVA package.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "Version",
    "PackageType"
  ],
  "properties": {
    "Version": {
      "title": "Version",
      "type": "string",
      "const": "1",
      "description": "Required. The manifest schema version. Must be the string value \"1\"."
    },
    "PackageType": {
      "title": "Package Type",
      "type": "string",
      "enum": [
        "Blueprint"
      ],
      "description": "Required. The type of package being described. Only \"Blueprint\" is currently supported."
    },
    "Metadata": {
      "title": "Metadata",
      "description": "Optional arbitrary metadata for the package. Keys are user-defined. All values must be strings.",
      "type": "object",
      "default": {},
      "propertyNames": {
        "type": "string",
        "minLength": 1,
        "pattern": "^[A-Za-z0-9._-]+$",
        "description": "Metadata key. Must be a non-empty string using letters, digits, dot, underscore, or hyphen."
      },
      "additionalProperties": {
        "type": "string",
        "description": "Metadata value. Must be a string."
      },
      "examples": [
        {
          "Author": "EV Offshore Ltd",
          "Environment": "Production",
          "Build": "2026.04.01"
        }
      ]
    }
  },
  "examples": [
    {
      "Version": "1",
      "PackageType": "Blueprint",
      "Metadata": {
        "Author": "EV Offshore Ltd",
        "Environment": "Production",
        "Build": "2026.04.01"
      }
    }
  ]
}

8. Minimum Usable Example

The smallest valid manifest for a Blueprint package contains only the required fields.

{
  "Version": "1",
  "PackageType": "Blueprint"
}

A package using this minimum manifest still requires a root-level blueprint.json and at least one referenced data file under data/.

9. Rich Example

The following example uses all currently supported manifest properties and mirrors the schema example.

{
  "Version": "1",
  "PackageType": "Blueprint",
  "Metadata": {
    "Author": "EV Offshore Ltd",
    "Environment": "Production",
    "Build": "2026.04.01"
  }
}

The corresponding archive layout could be:

10. Empty Template JSON

The following template can be used as a starting point when authoring a new package manifest. Replace placeholder metadata keys and values, or omit Metadata entirely if no annotations are needed.

{
  "Version": "1",
  "PackageType": "Blueprint",
  "Metadata": {
    "<KEY>": "<VALUE>"
  }
}