Skip to content

Conceptual Differences Between B2INST v2 and v3#

Introduction#

This document provides a conceptual overview of how the legacy B2INST v2 model differs from B2INST v3 (customized InvenioRDM v13). It is intended for data managers, community coordinators, and stakeholders who need to understand the model evolution (not low-level JSON details).

All examples below use fictional data for demonstration only.

General Model Evolution#

Topic B2INST v2 (legacy) B2INST v3
Foundation Legacy B2INST/B2SHARE codebase Customized InvenioRDM v13
Primary focus Instrument records with community-specific draft schemas PIDINST-aligned instrument registry with stronger service-layer validation
Metadata style Mixed/legacy field names (name, Instrument_Identifier, InstrumentTypes, …) Canonical B2INST root schema (Name, Identifier, InstrumentType, …)
Access model open_access + optional embargo_date Structured access object (record, files, embargo)
Community linkage Single community UUID in legacy JSON Structured parent/community model in record responses
PID handling API commonly used Identifier + ePIC_PID in metadata (some internal exports had _pid) Structured top-level pids object
Files Legacy file bucket references/flat legacy structures files object with enabled, entries, links and access metadata

Metadata Model Changes#

Key changes in B2INST v3#

  • A single canonical instrument schema is used in metadata (Name, Identifier, InstrumentType, etc.).
  • Legacy aliases are normalized during migration (e.g. name -> Name, Instrument_Identifier -> Identifier).
  • The metadata is clearly instrument-centric (PIDINST profile), not generic dataset metadata.
  • SchemaVersion is standardized (1.0 in the current implementation).
  • PIDINST compliance checks are enforced at publish time (e.g., landing page and core provenance/manufacturer/owner/model information).

Example (fictional)#

// v2 style (legacy API payload fragment)
{
  "id": "14c4e9fdbd5f41a7af62048d6a6cbd7e",
  "metadata": {
    "community": "65084a2d-7819-4b0b-a250-0f48002792b5",
    "Name": "TS-1000 Turbidity Sensor",
    "open_access": true,
    "Identifier": {
      "identifierValue": "21.T11975/ts-1000",
      "identifierType": "Handle"
    },
    "ePIC_PID": "http://hdl.handle.net/21.T11975/ts-1000",
    "InstrumentType": [{"instrumentTypeName": "Turbidity Sensor"}],
    "Manufacturer": [{"manufacturerName": "ClearWater Instruments"}],
    "Owner": [{"ownerName": "River Research Institute"}]
  }
}

// v2 legacy source payloads could also contain older aliases:
{
  "name": "TS-1000 Turbidity Sensor",
  "Instrument_Identifier": {
    "Identifier": "21.T11975/ts-1000",
    "identifierType": "Handle"
  },
  "InstrumentTypes": [{"instrumentTypeName": "Turbidity Sensor"}],
  "Manufacturers": [{"manufacturerName": "ClearWater Instruments"}],
  "Owners": [{"ownerName": "River Research Institute"}]
}

// v3 style (current B2INST payload)
{
  "access": {
    "record": "public",
    "files": "public"
  },
  "files": {
    "enabled": false
  },
  "metadata": {
    "Name": "TS-1000 Turbidity Sensor",
    "Identifier": {
      "identifierType": "Handle",
      "identifierValue": "21.T11975/ts-1000"
    },
    "InstrumentType": [{"instrumentTypeName": "Turbidity Sensor"}],
    "Manufacturer": [{"manufacturerName": "ClearWater Instruments"}],
    "Owner": [{"ownerName": "River Research Institute"}],
    "Model": {"modelName": "TS-1000"},
    "LandingPage": "https://example.org/instruments/ts-1000",
    "SchemaVersion": "1.0"
  }
}

Community and Extension Handling#

  • v2: community was represented as a single UUID (community) and legacy custom metadata could appear in community_specific.
  • v3: community relation is represented in the structured record model; extension fields are handled through the extension/custom-field mechanism (instead of embedding arbitrary legacy community objects in core metadata).

File and Access Handling#

  • v2: access was mostly derived from open_access and embargo_date; file references were tied to legacy bucket/file structures.
  • v3: access is explicit via access.record, access.files, and optional access.embargo; files are represented in the modern files section with richer links/metadata.

Persistent Identifiers#

  • v2: identifiers were mostly represented in API metadata fields (Identifier, ePIC_PID), while some internal legacy exports also had _pid.
  • v3: persistent identifiers are exposed through a structured top-level pids section (provider/client/identifier fields), separate from instrument metadata fields.

Summary#

  • B2INST v3 keeps the instrument-registry focus but moves to a cleaner, canonical schema and service model.
  • Legacy naming and access patterns from v2 are normalized into explicit, structured objects.
  • The v3 model is easier to validate, extend, and integrate via API workflows.

  Last update : 02.02.2026

Last review : 02.02.2026