Skip to content

Spec 015: BioPAX's exporter work ticked; the website's BioPAX planned (2) #751

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
adamjohnwright wants to merge 2 commits into from
Closed

Spec 015: BioPAX's exporter work ticked; the website's BioPAX planned (2) #751

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
848d06b
Spec 015: BioPAX's exporter work ticked; the website's BioPAX planned
adamjohnwright Oct 29, 2026
7011973
Spec 015, from #750's review: Kotlin's version held, the worst case m…
adamjohnwright Oct 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion specs/015-graph-exports/contracts/checks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,4 +37,4 @@ A tool that canonicalises two BioPAX files to multisets of (class, property, tar

- the node endpoints route to node in each table that serves them, and the dev proxy agrees (SBML: `dev.conf` and `local.conf` only, in `NOT_YET_ROUTED` for the deployed table until T068);
- SBGN and the event PDF stay in Java, and are listed among Java's neighbours;
- the render budget covers SBML and BioPAX wherever node serves them in a deployment: SBML in beta's `dev.conf` today (`.sbml` and the `.xml` form) and in release and production at T068; BioPAX at T052, which routes it in nginx and the dev proxy alike. Until then the deployed table's `/exporter/event/` location budgets any `.sbml` or `.biopax` request, though only `.sbml` has a Java answer behind it (R6); the configuration does that, and this spec checks that location only for png, svg and pdf, and the `/exporter/sbml/{id}.xml` form is not budgeted there. `local.conf` has no budget zone.
- the render budget covers SBML and BioPAX wherever node serves them in a deployment: SBML in beta's `dev.conf` today (`.sbml` and the `.xml` form) and in release and production at T068; BioPAX at T071, which routes it in nginx and the dev proxy alike. Until then the deployed table's `/exporter/event/` location budgets any `.sbml` or `.biopax` request, though only `.sbml` has a Java answer behind it (R6); the configuration does that, and this spec checks that location only for png, svg and pdf, and the `/exporter/sbml/{id}.xml` form is not budgeted there. `local.conf` has no budget zone.
8 changes: 4 additions & 4 deletions specs/015-graph-exports/plan.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ Each format gets one implementation, reading the graph, used by both the release
- It is proven by R4's comparison by meaning:
- against the release's published `biopax.zip`, which is Pathway-Exchange's output (R9). This is the main proof;
- against the legacy service's per-event files.
- **The website** gets both from spec 010's Java library service, fronted by node at the URLs R6 decided, with no fallback (R10). That service is spec 010's to build; this spec changes its SBML operation and adds BioPAX.
- **The website** gets both from spec 010's Java library service, fronted by node at the URLs R6 decided, with no fallback (R10). That service is spec 010's to build; this spec changes its SBML operation and adds BioPAX. Both are started in this repository's `deploy/java-library/` for beta until spec 010's repository exists (R10, amended 25 and 29 Oct 2026).
- **This repository keeps the instruments:**
- the sample;
- today's answers, and the release's published bulk files;
Expand Down Expand Up @@ -105,7 +105,7 @@ _GATE: Must pass before Phase 0 research. Re-check after Phase 1 design._
- BioPAX is compared by canonical triples, because bytes differ even Java against Java (R4).
- The bulk reference's generator was checked, not assumed: release 97's `biopax.zip` carries Pathway-Exchange's form and content (R9).
- The validators' baselines come from today's files (T034).
- BioPAX3Exporter's coverage was read (R9), and is measured before any work starts (T035).
- BioPAX3Exporter's coverage was read (R9), and measured class by class in its own spec 001 (T035 withdrawn).
- **Pass.**
- **II. Measure in the thing.**
- research.md's claims come from code read or from live answers.
Expand Down Expand Up @@ -170,7 +170,7 @@ projects/…/download-tab/, …/detail-download-bar/ # the BioPAX links

**Structure Decision**:

- **Node answers the URLs** with R6's headers, errors and caching. The library service writes only the body. For SBML, node is the service's client (T065); spec 010's pass-through is not needed for it.
- **Node answers the URLs** with R6's headers, errors and caching. The library service writes only the body. For SBML and BioPAX, node is the service's client (T065, T070); spec 010's pass-through is not needed for them.
- **The comparison tools are standalone instruments**, comparing files from anywhere. The SBML one turned out to be `sbml-exporter`'s `ci/compare.py` (T030), not a tool here; BioPAX's (T031) is not written yet, so `tools/exports-compare/` does not exist.

## Order of work
Expand All @@ -192,7 +192,7 @@ projects/…/download-tab/, …/detail-download-bar/ # the BioPAX links
4. **SBML in `sbml-exporter`** (T036–T042): the fixes, the comparisons, the layout, the graph-only command line, a dry run against the published archive, and validation in its CI.
5. **The SBML switch on the website** (T062–T067), from the service started here, once the comparisons are complete and recorded (FR-009 on beta).
6. **BioPAX in `BioPAX3Exporter`** (T045–T051): the content, the comparisons against `biopax.zip` and the legacy service, validation, and its CI.
7. **The BioPAX switch on the website** (T052–T054): the endpoint, the legacy redirect and the site's links.
7. **The BioPAX switch on the website** (T052, as T069–T072, then T053–T054): the service's operation, the endpoint, the route, the check, the legacy redirect and the site's links.
8. **The release's switches**, each after a full dry run (T055, T057). Level 2 is dropped (T056, decided).
9. **Throughout:** each exporter is split into a library and a command line, and the library is published (T061), so the release and the website run one codebase.

Expand Down
12 changes: 10 additions & 2 deletions specs/015-graph-exports/research.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -354,7 +354,7 @@ So retiring `release-download-directory` is smaller than its step list suggests.
- a thin command-line module that the release's bulk run uses, depending on that library.

The library service depends on the same library at a pinned version. So the release and the website run one codebase, and keeping the website current is a version bump. Until a library is published, the service builds it from a pinned commit, as spec 010 builds every library.
- **Node** answers `/ContentService/exporter/event/{id}.sbml`, `/exporter/sbml/{id}.xml` and `/exporter/event/{id}.biopax` with R6's headers (BioPAX through spec 010's pass-through; SBML with node as the service's client, as amended on 25 Oct below) and errors, cached per release under spec 011. When the library service cannot answer, node answers 503 in the envelope, never a fallback.
- **Node** answers `/ContentService/exporter/event/{id}.sbml`, `/exporter/sbml/{id}.xml` and `/exporter/event/{id}.biopax` with R6's headers (each with node as the service's client: SBML as amended on 25 Oct, BioPAX on 29 Oct, below) and errors, cached per release under spec 011. When the library service cannot answer, node answers 503 in the envelope, never a fallback.
- **The runtime is JDK 17.** BioPAX3Exporter is built for JDK 17, so a Java 11 runtime cannot load it. The libraries built for Java 11 run on 17 unchanged, so spec 010's service runs on JDK 17. Its bytecode stays Java 11 where its libraries need that. Spec 010's T011 and T017 are amended. Kryo and interactor-core's behaviour on 17 is checked by spec 010's token parity (its T026).
- **graph-core** is aligned in both exporters to the version spec 010's service pins. BioPAX3Exporter moves up from 2.0.9, and `sbml-exporter` follows from the BOM. The pinned version is the one the deployed ContentService runs, unless spec 010 records otherwise. Each exporter's maintainers are asked to accept it (T029).

Expand All @@ -365,7 +365,15 @@ So retiring `release-download-directory` is smaller than its step list suggests.
- **The library comes from source.** Its Dockerfile builds `sbml-exporter-lib` from the `graph-only` commit pinned in `deploy/java/PINS.md`. The library is not published while it is on a branch. Once it is published, that build stage goes and the service's pom names the published version.
- **The licences.** This repository holds only the service's own code and a Dockerfile naming the pinned commit, not the libraries. The image is built only on the beta host and in CI, and never pushed to a registry. The service's own code here is this repository's; the AGPL-dependent parts of spec 010's plan (copying content-service's classes, its T012, T013 and T015; the event PDF) do not happen here. Settling the libraries' licences stays a condition for publishing the library or the image (sbml-exporter#14).
- **The diagram files** are fetched on demand from the release's download directory: the same static `diagram/{stId}.json` files the site's browser loads. One file per converted pathway that has a diagram, cached on disk per release. Beta has no local copy of the folder.
- **Moving later.** When spec 010's repository exists, the service moves there unchanged, and its BioPAX operation joins it there.
- **Moving later.** When spec 010's repository exists, the service moves there unchanged.

**Amended 29 Oct 2026 (decided with the user): BioPAX joins the service here.** `BioPAX3Exporter`'s own spec 001 has since made the exporter. Its library module converts one event or a species. Its species files compare with release 98's `biopax.zip` by meaning, and each of a 30-event sample's files is contained in its species' file. So the website's per-event BioPAX need not wait for spec 010's repository either. It joins the service in `deploy/java-library/` as a second operation, on the terms SBML set:

- **The library comes from source,** built from a commit of `BioPAX3Exporter`'s `main` pinned in `deploy/java/PINS.md`, and proven by its own comparison, not by `tools/java-parity`.
- **No release files are read:** BioPAX needs only the graph.
- **Node is the service's client,** as for SBML (T065), not spec 010's pass-through.
- **The legacy service's per-event answer is the reference** for the website: this spec's sample (T001) is compared with it by meaning before beta routes the endpoint.
- **The licences:** as for SBML, settling the library's licence stays a condition for publishing the library or the image; `BioPAX3Exporter` has no licence file either.

**Alternatives considered.**

Expand Down
4 changes: 2 additions & 2 deletions specs/015-graph-exports/spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ This version makes **one exporter per format the single implementation for both*
- the bulk files the download page offers, made at release time;
- the files the website makes on demand for one pathway or reaction.

Each exporter reads the graph and lives in its own repository: `reactome/sbml-exporter` for SBML, and `reactome/BioPAX3Exporter` for BioPAX Level 3. Both are Java-based (Java and Kotlin). The website's on-demand exports are served by the Java library service that spec 010 already plans for the operations that stay in Java, SBML among them. It is reached only through the node service. For SBML on beta it is started in this repository, in `deploy/java-library/`, and moves to spec 010's own repository once that exists (research R10, amended 25 Oct 2026).
Each exporter reads the graph and lives in its own repository: `reactome/sbml-exporter` for SBML, and `reactome/BioPAX3Exporter` for BioPAX Level 3. Both are Java-based (Java and Kotlin). The website's on-demand exports are served by the Java library service that spec 010 already plans for the operations that stay in Java, SBML among them. It is reached only through the node service. For SBML and BioPAX on beta it is started in this repository, in `deploy/java-library/`, and moves to spec 010's own repository once that exists (research R10, amended 25 Oct and 29 Oct 2026).

What the first version produced is kept and used as the instruments for proving the exporters:

Expand Down Expand Up @@ -212,7 +212,7 @@ The people who run a release can make the SBML and BioPAX bulk files without the
- BioPAX Level 3 is `reactome/BioPAX3Exporter`.
- Either moves elsewhere only if its maintainers prefer.
- **One library per format.** Each exporter's repository becomes a library module, which this stack uses, and a thin command line, which the release uses (R10).
- **The website's service** is spec 010's Java library service (R10). Its SBML operation moves from the relational converter to the graph-only one, and it gains BioPAX Level 3. It pins one graph-core version, so both exporters must work with that version. Node fronts it, so nothing routes to the Java ContentService for these formats. For SBML it is started in this repository for now (research R10, amended 25 Oct 2026).
- **The website's service** is spec 010's Java library service (R10). Its SBML operation moves from the relational converter to the graph-only one, and it gains BioPAX Level 3. It pins one graph-core version, so both exporters must work with that version. Node fronts it, so nothing routes to the Java ContentService for these formats. For SBML, and since 29 Oct BioPAX, it is started in this repository for now (research R10, amended 25 Oct 2026).
- **BioPAX's URL** is `/ContentService/exporter/event/{id}.biopax`, as the first version decided (R6). The legacy path redirects to it.
- **Order of work.**
1. SBML: the exporter's fixes and tests, then its layout, then the comparisons; then the website and the release switch, each only after the comparisons pass (FR-009).
Expand Down
Loading
Loading