B2INST v2 vs v3 JSON Structural Differences#

Overview#

This document provides a technical comparison of legacy B2INST v2 record JSON and current B2INST v3 JSON. B2INST v3 is based on InvenioRDM v13 with a customized instrument (PIDINST) metadata schema.

All examples below use fictional data for demonstration only.

Structural Overview#

Aspect	B2INST v2 (legacy)	B2INST v3
Base system	Legacy B2INST/B2SHARE stack	Customized InvenioRDM v13
Record ID	UUID-like IDs in legacy storage	Short record IDs in API (`abc12-def34`) + internal parent/version model
Record model	API response with `created/updated/links/metadata/files` and legacy flags inside `metadata`	Structured record object (`metadata`, `access`, `files`, `pids`, `parent`, etc.)
Metadata field naming	Mixed naming/casing (`name`, `Instrument_Identifier`, `InstrumentTypes`)	Canonical B2INST schema (`Name`, `Identifier`, `InstrumentType`)
Access control	`open_access` + `embargo_date`	`access.record`, `access.files`, optional `access.embargo`
PID representation	API commonly used `metadata.Identifier` + `metadata.ePIC_PID` (internal exports may contain `_pid`)	Top-level `pids` object with provider/client details
Community reference	`community` UUID	Structured parent/community representation in API records
Custom community fields	`community_specific` legacy object	Extension/custom-field model

Top-level Shape#

v2 example (API response style, simplified)

{
  "created": "2025-09-24T09:03:52.124298+00:00",
  "updated": "2025-09-24T09:22:33.111228+00:00",
  "id": "14c4e9fdbd5f41a7af62048d6a6cbd7e",
  "files": [],
  "links": {
    "self": "https://b2inst.gwdg.de/api/records/14c4e9fdbd5f41a7af62048d6a6cbd7e"
  },
  "metadata": {
    "Name": "SMT100 - TRUEBNER GmbH - SMT100 - emiliaengelhardt",
    "Identifier": {
      "identifierType": "Handle",
      "identifierValue": "21.11157/14c4e9fd-bd5f-41a7-af62-048d6a6cbd7e"
    },
    "InstrumentType": [{"instrumentTypeName": "Soil moisture and temperature sensor"}],
    "community": "65084a2d-7819-4b0b-a250-0f48002792b5",
    "open_access": true,
    "ePIC_PID": "http://hdl.handle.net/21.11157/14c4e9fd-bd5f-41a7-af62-048d6a6cbd7e",
    "owners": [35],
    "publication_state": "published"
  }
}

v3 example (API-style)

{
  "id": "abc12-def34",
  "metadata": {
    "Name": "Sensor-Test",
    "Identifier": {
      "identifierType": "Handle",
      "identifierValue": "21.T11975/abc12-def34"
    },
    "InstrumentType": [{"instrumentTypeName": "Sensor"}]
  },
  "access": {
    "record": "public",
    "files": "public"
  },
  "files": {
    "enabled": false
  },
  "pids": {
    "oai": {"identifier": "oai:...", "provider": "oai"}
  }
}

Metadata Field Mapping (Legacy -> v3)#

Legacy field (v2)	B2INST v3 field	Notes
`name` or `Name`	`metadata.Name`	Canonical field in v3
`Instrument_Identifier.Identifier`	`metadata.Identifier.identifierValue`	Identifier value normalized
`Instrument_Identifier.identifierType`	`metadata.Identifier.identifierType`	Type normalized
`InstrumentType[]` / `InstrumentTypes[]`	`metadata.InstrumentType[]`	Canonical instrument type list
`Manufacturer[]` / `Manufacturers[]`	`metadata.Manufacturer[]`	Canonical manufacturer list
`MeasuredVariable[]` / `MeasuredVariables[]`	`metadata.MeasuredVariable[]`	Canonical measured variable list
`Models` / `Model`	`metadata.Model`	Canonical model object
`Owners[]` / `owners[]`	`metadata.Owner[]` (+ ownership in parent model)	Metadata owner details + system ownership model
`schemaVersion` / `SchemaVersion`	`metadata.SchemaVersion`	Canonical schema version
`AlternateIdentifier[]` / `AlternateIdentifiers[]`	`metadata.AlternateIdentifier[]`	Canonical alternate identifier list
`RelatedIdentifier[]` / `RelatedIdentifiers[]`	`metadata.RelatedIdentifier[]`	Canonical related identifier list
`Description` / `description`	`metadata.Description`	Canonical description
`Date` / `Dates`	`metadata.Date[]`	Canonical date list
`community`	Structured community relation in API record	In v2 it lived inside `metadata`; in v3 it moves to the parent/community model
`ePIC_PID`	`pids.epic.identifier` (when enabled)	Moves out of metadata to top-level PID object
`community_specific`	Extension/custom-fields model	Legacy key not used as core metadata field

Metadata Example in v3 (B2INST Schema)#

"metadata": {
  "Name": "TS-1000 Turbidity Sensor #42",
  "Identifier": {
    "identifierType": "SerialNumber",
    "identifierValue": "SN-00042"
  },
  "InstrumentType": [
    {
      "instrumentTypeName": "Turbidity Sensor",
      "instrumentTypeIdentifier": {
        "instrumentTypeIdentifierType": "URL",
        "instrumentTypeIdentifierValue": "https://vocab.gwdg.de/instrument-types/turbidity-sensor"
      }
    }
  ],
  "Manufacturer": [{"manufacturerName": "ClearWater Instruments Ltd."}],
  "Owner": [{"ownerName": "River Research Institute"}],
  "Model": {"modelName": "TS-1000"},
  "LandingPage": "https://instruments.gwdg.de/ts-1000",
  "MeasuredVariable": ["Water turbidity (NTU)"],
  "SchemaVersion": "1.0"
}

Access Model Mapping#

v2	v3
`open_access: true`	`"access": {"record": "public", "files": "public"}`
`open_access: false`	`"access": {"record": "restricted", "files": "restricted"}`
`embargo_date`	`"access": {"embargo": {"active": true/false, "until": "YYYY-MM-DD"}}`

PID and File Structures#

PID differences#

v2: API records typically exposed metadata.Identifier and metadata.ePIC_PID (some internal exports/dumps also contained legacy _pid arrays).
v3: top-level pids object keyed by pid type (doi, oai, etc. when enabled/configured).

File differences#

v2: legacy bucket/file references.
v3: normalized files object:

"files": {
  "enabled": true,
  "entries": {
    "data.csv": {
      "size": 12345,
      "checksum": "md5:...",
      "mimetype": "text/csv",
      "links": {"content": "https://.../api/records/<id>/files/data.csv/content"}
    }
  }
}

Summary#

B2INST v3 standardizes legacy field variants into a single canonical instrument schema.
Access, files, PIDs, and community relations are now explicit structured sections.
Legacy v2 keys can still appear in historical exports, but v3 API payloads should follow the canonical B2INST metadata model.

Last update : 02.02.2026

Last review : 02.02.2026