Propose a profile

Propose a profile when two real models need to exchange data and the active catalogue does not describe that connection. You can email the mapping to Biosimulant or add one YAML file in a pull request.

Prepare the scientific mapping

Use the repository’s proposal template. Provide:

• the producing model, version and output port;
• the receiving model, version and input port;
• a small real, synthetic or redacted example from each side;
• the workflow and intended use;
• every scientific fact needed to interpret and compare the data;
• expected direct, incompatible and unknown outcomes;
• every permitted conversion or inference; and
• authoritative sources for the scientific decisions.

Do not submit credentials, patient data or confidential datasets.

For each possible field, choose one disposition:

• required — the comparison cannot be decided without it;
• conditional — required only in a stated situation;
• recommended — useful but not a compatibility gate;
• excluded — deliberately outside the profile; or
• under-review — the draft leaves the decision to the scientific reviewer.

The generated review packet shows this full mapping. It does not hide fields that are not yet required.

Option 1: send it by email

Email demi@biosimulant.com with the subject Model compatibility profile proposal: <profile name>.

Attach:

1. The completed proposal template, or a Word/PDF copy with the same content.
2. A small source-port example in YAML or JSON.
3. A small target-port example in YAML or JSON.
4. Examples of a direct match, contradiction, missing information and each allowed conversion or inference.
5. Links, DOIs or versioned references supporting the decisions.

If YAML or JSON is unfamiliar, put the declarations in the template’s mapping table. The team can translate them into repository format. Submission is not independent approval.

Option 2: open a pull request

Create a branch

git clone https://github.com/<your-account>/model-compatibility-standard.git
cd model-compatibility-standard
git remote add upstream https://github.com/Biosimulant/model-compatibility-standard.git
git fetch upstream
git switch -c profile/<domain>-<profile-name> upstream/scientific-review/v0-catalogue-reset
 
python3 -m venv .venv
.venv/bin/pip install -e '.[test]'
npm install

After the v0 reset is merged, branch from upstream/main instead.

Add one profile file

Create:

source/profiles/<domain>/<profile-name>.yaml

The path supplies the profile ID. For example, source/profiles/proteome/protein-sequence.yaml becomes proteome/protein-sequence@0.1.

Copy the closest current profile and edit its meaning, intended use, limitations, representations, complete field list and examples. A shortened example is:

schema_version: "0.1"
label: Example Measurement
domain_label: Example domain
description: A precise description of the data represented by this profile.
status: draft
representations: [scalar, record]
intended_use: Connecting an output and input that exchange this measurement.
limitations:
  - It does not establish that the value or producing model is scientifically valid.
 
fields:
  semantic.concept: required
  representation.kind: required
  measurement.quantity: required
  measurement.unit: required
  biological_context.species: under-review
  origin.method: under-review
 
examples:
  - id: BMCS-EXAMPLE-001
    title: Identical declarations are an exact match
    check: compare
    expect: {status: EXACT}
    why: No conversion or inference is needed.
    conditions: Both ports provide the same complete declarations.
    decision: Example profile draft
    report_finding: Positive baseline

This is the only profile source file. There is no field pack or central profile entry to update.

Add a field only if it is genuinely new

Reuse a path from source/fields.yaml whenever it already expresses the same scientific fact. If the concept is missing, add one shared field with an explicit value schema and comparison rule. Do not add a near-duplicate field for one profile.

Add worked examples in the same YAML

Each example states the expected result and scientific reason. Use UNKNOWN for missing evidence and INCOMPATIBLE only for a known contradiction. A conversion or inference must be visible and versioned.

The current profiles show how to use source_patch, target_patch, source_remove and target_remove. The build collects these examples into the shared Python and TypeScript scientific checks.

Generate and test

.venv/bin/python scripts/build_standard.py
.venv/bin/python scripts/build_standard.py --check
.venv/bin/pytest -p no:cacheprovider
PATH="$PWD/.venv/bin:$PATH" npm test

Inspect these generated files:

• spec/v0.1/profiles/<domain>/<profile-name>/v0.1.json;
• spec/v0.1/fixtures/profiles/<domain>/<profile-name>.json; and
• spec/v0.1/review-packets/<domain>/<profile-name>.json.

The review packet contains every field from the profile YAML and the worked examples. If it is wrong, change the YAML and rebuild; do not edit generated JSON.

Open the pull request

Use a title such as Profile: add <profile name> for <source model> to <target model>. Include the mapping, examples, intended use, limitations, sources, generated files, test results and unresolved questions. Keep the pull request to one profile unless a small related set has the same scientific boundary.

Do not approve your own proposal. When the mapping is stable, an independent scientist, a different schema reviewer and a domain owner complete:

source/reviews/<domain>/<profile-name>.yaml

using source/reviews/profile-review.template.yaml.

Files changed in the usual case

Normally:

1. one source/profiles/<domain>/<name>.yaml file; and
2. the generated files under spec/v0.1/.

Only when necessary:

3. source/fields.yaml for a genuinely new field;
4. source/quantity-kinds.yaml for a new measurement meaning; and
5. a review YAML later, after independent review.

The repository’s full proposal guide has the pull-request checklist.