# 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. **Warning:** 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](/standards/model-compatibility/catalogue#review). ## 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: ```json { "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](/standards/model-compatibility/rules). - **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](/standards/model-compatibility/adapters-and-inference). ## 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 | Question | Answered by | Possible answers | |---|---|---| | Can these two ports connect, and does the data need converting? | Comparison status | `EXACT`, `DIRECT_COMPATIBLE`, a conversion or inference status, `CONDITIONAL`, `INCOMPATIBLE`, `UNKNOWN` | | Is this workspace allowed to use that connection? | Policy decision | `ALLOW`, `APPROVAL_REQUIRED`, `BLOCK` | | Is the scientific record good enough for the intended use? | Passport quality | `READY`, `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](https://github.com/Biosimulant/model-compatibility-standard) ## Where to start - [Add compatibility to a `model.yaml`](/standards/model-compatibility/model-yaml), with a before-and-after example. - [Browse the profile catalogue](/standards/model-compatibility/catalogue) to find a profile for your data. - [Run checks from the CLI or the API](/standards/model-compatibility/api-and-cli). - Read the [specification](/standards/model-compatibility/specification) if you're building a tool that reads or writes contracts.