Importing a Bill of Materials from a JSON File

Import replaces the contents of an existing Bill of Materials (BOM) with the contents of a JSON file. Use it when you or a vendor have built or corrected a BOM outside the platform and need to load that version into an existing BOM. This article describes the file the Import button accepts, what each field means and how to fix a file that fails validation. For an overview of the Bill of Materials page and its tabs, see the Bill of Materials Overview article.

An import makes the following changes:

• Every technology, model, dataset, infrastructure item and agentic system on the BOM is removed and replaced with the contents of the file.
• The BOM's name and description are replaced with the values in the file's Details object.
• The BOM's VCS integration and repository references are cleared, and the BOM becomes self-attested. A BOM created with CodeSensor can no longer be rescanned after an import.
• The import counts as a normal update. Prior versions remain in Version History, and the import becomes the newest version.
• A new vulnerability assessment starts automatically against the imported items.

Import follows these rules:

• You need permission to update BOMs.
• Import is unavailable while a scan of the BOM is queued or running. Wait for the scan to finish before you import.
• The file must be a single .json file that holds one BOM and is 5 MB or smaller.
• Validation is all or nothing. The file is checked before anything is saved. If any error is found, nothing is saved and every problem is listed with its location in the file.
• Import accepts JSON only. CycloneDX and SPDX files are not supported.
• Import works only on an existing BOM. The Bill of Materials Wizard cannot create a new BOM from a JSON file.

Building an Import File

Import reads the same format that the JSON export writes, so the simplest way to build a file is to start from an export.

1. Open any BOM and select Export to json. The export menu also lists CycloneDX, SPDX and XLSX formats, but only the JSON export can be imported.
2. Edit the file. Add, change or remove entries in Technologies, Infrastructure, Data, Models and AgenticSystems, and update Details.Name and Details.Description.
3. Open the BOM you want to replace and select Import.
4. In the Import BOM from JSON dialog, review the warning, then click or drag the file into the drop area and select Import.

The file is checked first. If it passes, the contents are replaced and the page refreshes to show the new data.

Two rules make an exported file easier to reuse:

• Field names are not case-sensitive. Technologies and technologies both work.
• Fields the import does not use can stay in the file. Ids, dates, owner, repository details and scan status are ignored.

File Structure

The file is a single JSON object with the following top-level fields.

Any list can be left out or set to []. A list set to null or to a value that is not a list is rejected.

Details and Component Fields

Details

The Details object sets the name and description of the BOM you import into.

An export also writes owner, repository, branch, statuses and dates into Details. Import ignores these fields because they describe the BOM the file came from, not the BOM you import into.

Component

Technologies, Infrastructure, Data and Models all use the same component object.

Components follow these rules:

• No duplicates within a list. Two components in the same list with the same name and version (ignoring case) are rejected. The same package at two different versions is accepted, and the same name on two different lists is accepted.
• Ids are not reused. Every imported component gets a new id, so ids in an exported file are ignored.
• Imported components are self-attested. They are treated the same as components added by hand, and their names and descriptions can be edited later in the BOM editor.
• Version wins over Attributes. If Version and Attributes.version disagree, the value in Version is used.

Agentic System Fields

Each entry in AgenticSystems describes one agentic system, the agents in it and the links between them.

Agentic System

Agent

Relation

A relation links a source node to a destination node. To link two agents, set each node's type to component_node and its content to the id of an agent in the same system.

Example Import File

The following file is a complete, valid import. It sets the BOM's name and description, adds two technologies, one infrastructure item, one dataset and one model with a system prompt, and defines an agentic system in which an intake agent hands off to a routing agent. Copy it as a starting point, edit it, then import it.

{
  "Details": {
    "Name": "Claims Triage Assistant",
    "Description": "LLM-assisted triage for inbound insurance claims."
  },
  "Technologies": [
    { "Name": "langchain", "Version": "0.3.7", "Language": ["python"],
      "FilePath": ["requirements.txt"] },
    { "Name": "transformers", "Version": "4.46.2", "Language": ["python"] }
  ],
  "Infrastructure": [
    { "Name": "Azure OpenAI", "Description": "Hosted model endpoint" }
  ],
  "Data": [
    { "Name": "Historical claims 2019-2024", "Description": "Internal, de-identified" }
  ],
  "Models": [
    { "Name": "gpt-4o", "Version": "2024-08-06",
      "SystemPrompts": [ { "systemPrompt": "You are a claims triage assistant." } ] }
  ],
  "AgenticSystems": [
    {
      "name": "Triage workflow",
      "framework": "langgraph",
      "components": [
        { "id": "6f1c2a3e-0b7d-4c55-9a51-2d8e4f6a7b10", "name": "Intake agent", "model": "gpt-4o" },
        { "id": "a9e4d2c1-5f38-4b0e-8c27-71d3b6e9f402", "name": "Routing agent", "model": "gpt-4o" }
      ],
      "relations": [
        { "type": "handoff",
          "source":      { "type": "component_node", "content": "6f1c2a3e-0b7d-4c55-9a51-2d8e4f6a7b10" },
          "destination": { "type": "component_node", "content": "a9e4d2c1-5f38-4b0e-8c27-71d3b6e9f402" } }
      ]
    }
  ]
}

Fixing Import Errors

The file is checked before anything is saved, and every problem is listed at once. If any error is found, nothing is saved. Fix every listed problem and import the file again.

Each error names its location using the file's structure. For example, Technologies[2].Name is the name of the third technology, because list positions start at 0.

[SCREENSHOT: Import BOM from JSON dialog after a failed validation, showing the list of errors with their file locations]