Ontology SDK

Add the SDK to a repository

Registry settings for npm, pip, conda and Maven in an existing project.

Converge serves npm, pip, conda and Maven registries. Point your project at them once and install the SDK like any other package. Keep the token in an environment variable and never commit it.

npm

Add these lines to .npmrc at the repository root:

@convergehq:registry=https://cnvrg.si/api/v2/osdk/npm/
//cnvrg.si/api/v2/osdk/npm/:_authToken=${FOUNDRY_TOKEN}

npm install @convergehq/osdk-<ontology>

Only @convergehq packages come from Converge. Everything else still comes from the public registry.

Always install with the @convergehq:registry= line in .npmrc, including in CI and with npx. Your ontology package is only on Converge, so without that line npm looks for it on the public registry and fails.

Packages generated before 2026-11 were named @converge/osdk-<ontology>. To move, change the .npmrc line to @convergehq:registry=, rename the dependency and its imports to @convergehq/osdk-<ontology>, and run npm install. The old name keeps working, with a deprecation notice, until 2027-01-31.

When npm install fails

  • 401 or 403: the token line is wrong or the token has expired. Write it exactly as above, with no spaces around = and nothing after ${FOUNDRY_TOKEN}, and check that FOUNDRY_TOKEN is set in the shell that runs npm.
  • 404 for @convergehq/osdk-<ontology>: npm did not use the Converge registry. Run npm config get @convergehq:registry in the project directory. If it is empty, the .npmrc with the scope line is not the one npm reads; a .npmrc in a parent directory or in your home directory can win.
  • 404 for a type you expected: the package holds only the types your token can see. Ask for access to the type, then install again: the version changes when the types you can see change.
  • 404 with "versi paket sudah berganti; jalankan npm install lagi" (the package version has changed; run npm install again): the version in your lockfile is no longer served. See Versions and lockfiles.

Vite and other browser apps

To build one app for several ontologies, give it the ontology at build time instead of in code. In Vite, set VITE_ONTOLOGY_RID in .env.production (and .env.development) and put it in the page's meta tag:

<meta name="osdk-ontologyRid" content="%VITE_ONTOLOGY_RID%" />

The client reads that tag, as described in One build, several ontologies. Never put a token in a VITE_ variable: those are built into the JavaScript that every visitor downloads.

pip

Put your token in ~/.netrc once, so it never appears in a URL or in your shell history:

machine cnvrg.si login __token__ password <your token>

The login is always __token__. Then install, or put --index-url https://cnvrg.si/api/v2/osdk/pypi/simple/ as the first line of a separate requirements-converge.txt:

pip install --index-url https://cnvrg.si/api/v2/osdk/pypi/simple/ converge-osdk-<ontology>

Use --index-url, never --extra-index-url, for the Converge index. With --extra-index-url, pip also asks public PyPI for converge-sdk and converge-osdk-<ontology>, and whoever registered those names there would run code on your machine at install time. The Converge index serves everything the package needs.

In CI, write that .netrc line from a secret before you run pip install. Don't pin the package to a full version (==1.0.0+h…): see Versions and lockfiles.

conda

The same client is a conda package in a noarch channel at https://cnvrg.si/api/v2/osdk/conda/, next to the converge-sdk package it depends on. Give conda the token once in ~/.condarc, and keep that file readable by you only (chmod 600 ~/.condarc):

custom_channels:
  conda: https://__token__:${FOUNDRY_TOKEN}@cnvrg.si/api/v2/osdk
channel_priority: strict

custom_channels names the channel conda at that location, so its URL is https://cnvrg.si/api/v2/osdk/conda/. conda attaches these credentials to any channel URL under it. Then install with the plain URL, or with the name:

conda install -c https://cnvrg.si/api/v2/osdk/conda/ -c conda-forge converge-osdk-<ontology>
  • conda expands ${FOUNDRY_TOKEN} when it reads .condarc, so the file never holds the token itself.
  • Never put the token on the command line. conda writes every command line, verbatim, to conda-meta/history in the environment. It removes credentials from the package URLs it records in conda-meta/<package>.json. The command line is not cleaned.
  • The channel reads HTTP Basic, like the pip index: the login is always __token__ and the password is your token. conda sends it in the Authorization header. Converge doesn't accept conda's other token form, https://cnvrg.si/t/<token>/…: it puts the token in the URL path, and so in proxy and server access logs.
  • List the Converge channel first and keep channel_priority: strict. Then conda takes converge-sdk and converge-osdk-<ontology> only from Converge, even if someone registers those names on a public channel. Python itself comes from the next channel.
  • Like the pip package, the conda package is built for the token that asks (see Versions and lockfiles). Its build string is the hash: converge-osdk-<ontology>-1.0.0-h…_0. Don't pin the build.
  • Every client installs as the package ontology_sdk, so two ontologies in one environment overwrite each other. Use one environment per ontology.

Maven

Use the settings.xml and pom.xml entries from Java and other languages.

One build, several ontologies

A browser app can read the ontology from a meta tag instead of the one it was generated for:

<meta name="osdk-ontologyRid" content="<ontology rid>">

CI

In CI, set FOUNDRY_TOKEN from a secret that belongs to a service app, not to a person. The token can only read the types that the service app can see. When the service app is disabled, its token stops working.

Versions and lockfiles

The registry serves only the newest version of the package, built for the token that asks. The version is a hash of the types that token can see. Two things make an installed version disappear:

  • The types you can see change, because someone edits the ontology or your access changes.
  • CI's service-app token sees different types than your own token, so it gets a different version.

So an installed version can stop installing:

  • npm: package-lock.json records the version and its tarball URL, and both npm install and npm ci fetch it, which answers 404. In CI, refresh it first with npm install @convergehq/osdk-<ontology>@latest.
  • pip: ==1.0.0+h… fails with "No matching distribution found", and a lock that records the file URL gets the 404 "versi paket sudah berganti; jalankan pip install lagi". Install the Python package with no version pin.
  • conda: an explicit or locked file (…-1.0.0-h…_0.tar.bz2) gets the 404 "versi paket sudah berganti; jalankan conda install lagi". Install converge-osdk-<ontology> without a build string.

If a build must not change, download the client once from the download endpoints and commit it to the repository.

Converge