<!-- Source: https://docs.biosimulant.com/standards/model-compatibility/propose-profile -->

# 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.

**Info:**

  Start with one output-to-input connection. The standard grows from real uses,
  examples and evidence, not a speculative list of scientific concepts.

## Prepare the mapping

Use the repository's
[proposal template](https://github.com/Biosimulant/model-compatibility-standard/blob/main/PROFILE_PROPOSAL_TEMPLATE.md).
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, intended use and important limits;
- 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 decisions.

Do not submit credentials, patient data or confidential datasets.

For every relevant field, choose `required`, `conditional`, `recommended` or
`excluded`. The complete mapping stays in the profile; there is no separate
review packet.

## Send it by email

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

Attach the completed proposal template, or a Word/PDF with the same content,
plus small source and target examples. If YAML or JSON is unfamiliar, use the
template's mapping table. The Biosimulant team can translate it into the
repository format.

## Open a pull request

### Create a branch

```bash
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/main

python3 -m venv .venv
.venv/bin/pip install -e '.[test]'
npm install
```

### Add one profile file

Create `source/profiles/<domain>/<profile-name>.yaml`. The path supplies the
profile ID. Copy the closest current profile and edit its meaning, intended use,
limitations, sources, representations, complete field list and examples.

```yaml
schema_version: "0.1"
label: Example Measurement
domain_label: Example domain
description: A precise description of the data represented by this profile.
status: active
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.
sources:
  - title: Authoritative measurement specification
    url: https://example.org/specification

fields:
  semantic.concept: required
  representation.kind: required
  measurement.quantity: required
  measurement.unit: required
  biological_context.species: recommended
  origin.method: recommended

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 measurement profile
    report_finding: Positive baseline
```

If a question is unresolved, explain it in the pull request and resolve it
before merge. Published profiles do not carry an `under-review` field state.

If the profile itself fixes a required field to one value, declare it once in
`fixed` and keep the same field `required`:

```yaml
fixed:
  representation.structure_format: smiles

fields:
  representation.structure_format: required
```

Use this only when every port using the profile must declare that value. It is
not a default or a suggested example.

### Add a shared field only when necessary

Reuse `source/fields.yaml` whenever it already expresses the same scientific
fact. Add a field only when the concept is genuinely missing. Change
`source/quantity-kinds.yaml` only for a new or changed measurement kind.

### Generate and test

```bash
.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 the generated profile and fixtures under `spec/v0.1/`. If generated
output is wrong, change the YAML or generator and rebuild. Do not edit generated
JSON directly.

### Open the pull request

Describe the connection, intended use, limitations, full mapping, examples,
sources, unresolved questions and test results. Keep the pull request to one
profile unless a small related set shares the same scientific boundary.

The pull request is the review record. It can request scientific or technical
input appropriate to the change. Merge into `main` accepts the profile for its
stated use; there is no separate sign-off file.

## Files changed in the usual case

1. `source/profiles/<domain>/<name>.yaml`.
2. Generated files under `spec/v0.1/`.
3. Generated browser data under `typescript/dist/`.

Only when necessary, also change `source/fields.yaml` or
`source/quantity-kinds.yaml`.

The repository's
[full proposal guide](https://github.com/Biosimulant/model-compatibility-standard/blob/main/PROPOSING_A_PROFILE.md)
has the pull-request checklist.