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).
  • Publish-time checks require a valid landing page, at least one named manufacturer, and at least one named owner, in addition to Name. Model is recommended rather than mandatory.

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",
    "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: assigned communities appear in parent.communities.ids. Adding communities or parent.communities to the draft creation body does not assign membership. Use the separate record-community endpoint for permitted direct association, or the draft review workflow. Extension fields are handled through the extension/custom-field mechanism.

See direct publication and community review for complete examples.

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. Set files.enabled: false for metadata-only records; access.status is calculated by the service. With files enabled, register entries, upload each file with PUT .../content, then commit each file with POST .../commit before publication.

Persistent Identifiers#

  • v2: identifiers were mostly represented in API metadata fields (Identifier, ePIC_PID), while some internal legacy exports also had _pid.
  • v3: metadata.Identifier is an object assigned by the service, containing a bare Handle such as 21.T11975/2qzkm-nzp30. Omit it from creation payloads; a caller-supplied value is replaced. The corresponding pids.epic.identifier, when present, contains the resolver URL, such as http://hdl.handle.net/21.T11975/2qzkm-nzp30. Handle registration depends on publication, configuration, and access settings; the metadata identifier alone does not prove registration.

Updating Published Records#

The v2 JSON Patch workflow is not supported for v3 draft metadata. Use POST /api/records/{id}/draft to edit metadata in the same version, or POST /api/records/{id}/versions to create a new version draft with a new ID. Neither action applies metadata from its POST body. Update the returned draft with a complete metadata object using PUT, then publish it. See the update examples.

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 : 22.09.2026

Last review : 22.09.2026