StandardsModel CompatibilityOverview

Biosimulant Model Compatibility Standard

The Biosimulant Model Compatibility Standard lets a model describe what its inputs and outputs mean: units, identifiers, species, data format and so on. Tools can then check whether two models can be connected before you run them.

It’s optional. You add it to an existing model.yaml, and models without it work as before.

Compatibility checks whether two model interfaces fit together. It doesn’t show that a model is scientifically valid or clinically safe.

⚠️

This is an early release, version 0.1.0-alpha.5. The files and tools work, but they may change before a stable release. None of the 650 profiles has been scientifically reviewed yet. See review status.

Why use it

Two models can agree on structure and still disagree on meaning. Say an upstream model outputs gene expression counts from mouse samples, and a downstream model expects human data. Both ports are float arrays, so a structural check passes and the run goes ahead with the wrong input.

If both ports describe their data, biosimulant compatibility compare catches the mismatch. It returns INCOMPATIBLE and points to the species field:

{
  "dimension": "biological_context",
  "state": "INCOMPATIBLE",
  "reason_code": "BMCS_VALUE_MISMATCH",
  "evidence": { "source": "NCBITaxon:10090", "target": "NCBITaxon:9606" }
}

Key terms

  • Port contract: a description of what a port’s data means: units, identifiers, species, format and so on. You write it under contract on an input or output in model.yaml.
  • Profile: a reusable set of rules for one kind of data, for example gene expression counts. A profile says which contract fields are required and how to compare them.
  • Source and target: the output port that sends data, and the input port that receives it.
  • Comparison status: the result of comparing a source with a target, such as EXACT, INCOMPATIBLE, or UNKNOWN (not enough information to decide). See Rules and statuses.
  • Lock: compatibility.lock.json, a file in a built model package that pins the exact profiles and contracts it was built with.
  • Plan: a chain of adapters or inference models that connects a source to a target, for example a unit conversion from nM to µM. See Adapters and inference models.

What you add to a model

You can add two things, both optional:

  1. A top-level compatibility block that lists the profiles the model uses.
  2. A contract on each input or output port you want to describe.

schema_version stays "2.0". Entrypoints, package formats and the way models run don’t change. If a port has no contract, comparing it returns UNKNOWN, and the manifest is still valid.

Three separate questions

QuestionAnswered byPossible answers
Can these two ports connect, and does the data need converting?Comparison statusEXACT, DIRECT_COMPATIBLE, a conversion or inference status, CONDITIONAL, INCOMPATIBLE, UNKNOWN
Is this workspace allowed to use that connection?Policy decisionALLOW, APPROVAL_REQUIRED, BLOCK
Is the scientific record good enough for the intended use?Passport qualityREADY, REVIEW, BLOCKED

A connection can be compatible and still be blocked by policy. A compatibility report never replaces the Passport quality decision.

This release

  • Version: 0.1.0-alpha.5
  • Bundle sha256: sha256:6d0d9305eb16cf05749c94c04c16fb1ee9b8213957ef19cddaa95a961f665521
  • Profiles: 650
  • Contract items (fields a contract can set): 266
  • Item packs (groups of fields that profiles share): 30
  • Source repository: Biosimulant/model-compatibility-standard

Where to start

Studio QuickstartSpecification