Skip to main content

Beacon v2 Models (BFF)

BFF stands for Beacon Friendly Format. The BFF is a data exchange format composed of 7 JSON files. These files correspond to the 7 entities of the Beacon v2 Models.

RoleInput and output
Accepted inputindividuals for bff2pxf
Main outputindividuals, biosamples, datasets, cohorts
Notesinfo provenance unless --no-source-info is used
Beacon v2
Entities in Beacon v2 Models
About Beacon v2 Models' entities

Among the Beacon v2 Models entities, individuals is usually the main record-level carrier of phenotypic and clinical information. Other entities such as biosamples, datasets, and cohorts are also important, but they tend to be more focused: biosamples capture specimen-level context, while datasets and cohorts are mostly collection-level metadata. In practice, this means individuals usually drives the most complex semantic mapping, whereas the other entities are often derived, enriched, or populated with lighter transformation rules.

Convert-Pheno supports BFF in both directions.

  • As input, the current bff2pxf route reads the individuals entity, typically serialized as individuals.json.
  • As output, the CLI can emit individuals, biosamples, datasets, and cohorts.

This means BFF output is no longer only individuals. The individuals limitation applies to the current BFF input conversion route, not to BFF output.

Source provenance in info

By default, Convert-Pheno preserves raw source values in info when creating BFF from source formats such as OMOP-CDM, CSV, REDCap, and CDISC-ODM. This is deliberate: it makes converted records easier to audit against the original input and allows source-specific values to remain queryable through Beacon-style APIs.

For smaller exports, or when raw source values should not be carried forward, use --no-source-info. This removes copied source payloads such as OMOP_columns, CSV_columns, and REDCap_columns, while keeping regular mapped fields and conversion metadata such as info.convertPheno.

Browsing BFF JSON data

You can browse a public BFF v2 file with the following JSON viewers:

BFF As Input BFF​

When using the convert-pheno command-line interface, simply ensure the correct syntax is provided.

About JSON data in individuals.json

If the file individuals.json is a JSON array of objects (for which each object corresponds to an individual), the output -opxf file will also be a JSON array.

    convert-pheno -ibff individuals.json -opxf phenopacket.json

BFF As Output​

As an output format, BFF can be emitted in two modes:

  • single-file individuals mode, using -obff FILE
  • entity-aware mode, using --entities ... --out-dir DIR, which can write multiple Beacon entities

The currently supported BFF output entities are:

  • individuals
  • biosamples
  • datasets
  • cohorts

Examples:

convert-pheno -ipxf pxf.json -obff individuals.json
convert-pheno -ipxf pxf.json -obff --entities individuals biosamples --out-dir out/
convert-pheno -icsv clinical.csv --mapping-file clinical.yaml -obff --entities individuals datasets cohorts --out-dir out/

At the moment, reverse conversion from BFF input still expects individuals rather than a full multi-entity Beacon bundle. This does not limit BFF output, which can write individuals, biosamples, datasets, and cohorts.

Please find below examples of data:

    {
      "ethnicity": {
        "id": "NCIT:C42331",
        "label": "African"
      },
      "id": "HG00096",
      "info": {
        "eid": "fake1"
      },
      "interventionsOrProcedures": [
        {
          "procedureCode": {
            "id": "OPCS4:L46.3",
            "label": "OPCS(v4-0.0):Ligation of visceral branch of abdominal aorta NEC"
          }
        }
      ],
      "measures": [
        {
          "assayCode": {
            "id": "LOINC:35925-4",
            "label": "BMI"
          },
          "date": "2021-09-24",
          "measurementValue": {
            "quantity": {
              "unit": {
                "id": "NCIT:C49671",
                "label": "Kilogram per Square Meter"
              },
              "value": 26.63838307
            }
          }
        },
        {
          "assayCode": {
            "id": "LOINC:3141-9",
            "label": "Weight"
          },
          "date": "2021-09-24",
          "measurementValue": {
            "quantity": {
              "unit": {
                "id": "NCIT:C28252",
                "label": "Kilogram"
              },
              "value": 85.6358
            }
          }
        },
        {
          "assayCode": {
            "id": "LOINC:8308-9",
            "label": "Height-standing"
          },
          "date": "2021-09-24",
          "measurementValue": {
            "quantity": {
              "unit": {
                "id": "NCIT:C49668",
                "label": "Centimeter"
              },
              "value": 179.2973
            }
          }
        }
      ],
      "sex": {
        "id": "NCIT:C20197",
        "label": "male"
      }
    }