Skip to content

Migrating from OpenMed 3.3 to 4.0

OpenMed 4.0.0 is the next breaking release and is not published yet. This guide collects each breaking change as it lands, with the migration it needs. The fixed-option decision API and local decision models pages describe the current contracts in full.

Decision schema 1.2.0

The decision request and result schemas are now version 1.2.0. Two changes landed after 1.1.0 was published without a version bump, so the 1.1.0 $id named two different documents. They now belong to 1.2.0:

  • requests may carry verified local media;
  • backend license provenance is a bounded license expression with an optional license_sha256, and may appear in results of every 1.x version.

Migrate as follows:

  • A request that omits schema_version resolves to the lowest version carrying every field it uses: 1.0.0, 1.1.0, or 1.2.0 when it carries media. Existing 1.0.0 and 1.1.0 requests decide exactly as before and keep their result version.
  • A request that declares schema_version: "1.1.0" and carries media is now refused with input_error. Declare "1.2.0" or omit the version. Code that adds media to an existing request with dataclasses.replace must also set schema_version="1.2.0" or None.
  • Validators pinned to https://openmed.dev/schemas/decision-request/1.1.0 or .../decision-result/1.1.0 should load the 1.2.0 documents, which accept every 1.0.0, 1.1.0 and 1.2.0 payload.
  • DECISION_SCHEMA_VERSION is now "1.2.0", and migrate_decision_result() migrates to 1.2.0 by default. Pass target_version="1.1.0" to keep the previous label; results have the same fields at 1.1.0 and 1.2.0.
  • The TypeScript client's schema_version fields use the new DecisionSchemaVersion union, which includes "1.2.0".

Every published version of each decision document is now pinned by fingerprint, so a future schema change fails CI until the version is bumped.

One /v1/decisions route for both request shapes

OpenMed's own DecisionServerBackend posted the OpenAI-compatible Decisions body (model, input, questions) to /v1/decisions, where the OpenMed route required mode and input_text. An OpenAI-compatible client, or one OpenMed service bridging to another, received a 422.

The route now negotiates the body. It recognises an OpenMed request by mode or input_text and an OpenAI-compatible body by model or input, and answers in the same shape. questions exists in both shapes and decides nothing. The path stays shared rather than split. Moving the OpenMed route would break every existing OpenMed client, and giving the OpenAI-compatible body its own path would leave those clients unable to call /v1/decisions unchanged. The required keys of the two shapes never overlap, so one path serves both.

What changes:

Before After Migration
An OpenAI-compatible body failed with validation_error It is decided and answered with model, answers and an openmed review object Name the served backend's model_id in model; send text only
A body with keys of both shapes failed with validation_error 422 decision_request_ambiguous, details.reason: both_shapes Send one shape
A body with keys of neither shape failed with validation_error 422 decision_request_ambiguous, details.reason: no_shape Send mode and input_text
Validation errors named fields as body.input_text They name the shape first, for example body.openmed.input_text Match on the last path segment or on error.code
— An OpenAI-compatible body with media is refused with 422 decision_media_unsupported Send media in an OpenMed 1.2.0 request
— An OpenAI-compatible model that is not the served model is refused with 422 model_not_served Name the served model

Valid OpenMed requests keep their results. Both shapes use the same decisions:write scope, request-body limit, access policy, backend and calibration profiles. The OpenAI-compatible body carries no OpenMed policy fields, so it is decided under the defaults (namespace default, purpose care_review, the default calibration, 5,000 ms and 8,192 characters); send an OpenMed request when you need other policy fields.

To bridge one OpenMed service to another, set the backend's model_id (or served_model) to the remote service's backend model_id:

# Fragment: needs a second OpenMed service listening on loopback.
from openmed.structured import decide
from openmed.structured.decision_server import DecisionServerBackend

backend = DecisionServerBackend(
    endpoint="http://127.0.0.1:8081",
    protocol="openai_decisions",
    model_id="openmed/deterministic-fixed-option",
    revision="1.0.0",
    license_id="Apache-2.0",
)
result = decide(request, backend=backend)  # route the result for human review

The typed clients add one method for the new shape: Python OpenMedClient.openai_decisions(), TypeScript openaiDecisions() and Go OpenAIDecisions(). decision() and Decision() are unchanged.

Python API

Import paths that are no longer re-exported

Several modules imported names they did not define, so the names were also importable from those modules. The v4.0 changes removed the imports, so import each name from the module that defines it:

Old import Import instead
openmed.service.app.FixedOptionDecisionRequest openmed.service.schemas.FixedOptionDecisionRequest
openmed.service.app.JourneyResourceQuery openmed.service.journey_resources.JourneyResourceQuery
openmed.service.graphql_schema.JourneyResourceQuery openmed.service.journey_resources.JourneyResourceQuery
openmed.service.app.SERVICE_CORS_HEADERS openmed.service.security_headers.SERVICE_CORS_HEADERS
openmed.service.jobs.hash_text openmed.core.audit.hash_text

The classes are unchanged, so their members move with them: openmed.service.app.FixedOptionDecisionRequest.calibration_id, openmed.service.app.FixedOptionDecisionRequest.compatibility_policy, openmed.service.app.FixedOptionDecisionRequest.input_format, openmed.service.app.FixedOptionDecisionRequest.input_text, openmed.service.app.FixedOptionDecisionRequest.instructions, openmed.service.app.FixedOptionDecisionRequest.levels, openmed.service.app.FixedOptionDecisionRequest.max_input_chars, openmed.service.app.FixedOptionDecisionRequest.media, openmed.service.app.FixedOptionDecisionRequest.mode, openmed.service.app.FixedOptionDecisionRequest.namespace, openmed.service.app.FixedOptionDecisionRequest.option_descriptions, openmed.service.app.FixedOptionDecisionRequest.options, openmed.service.app.FixedOptionDecisionRequest.purpose, openmed.service.app.FixedOptionDecisionRequest.question_id, openmed.service.app.FixedOptionDecisionRequest.questions, openmed.service.app.FixedOptionDecisionRequest.schema_version, openmed.service.app.FixedOptionDecisionRequest.timeout_ms; openmed.service.app.JourneyResourceQuery.access_request_digest, openmed.service.app.JourneyResourceQuery.after, openmed.service.app.JourneyResourceQuery.attributes, openmed.service.app.JourneyResourceQuery.consent_state, openmed.service.app.JourneyResourceQuery.export_policy, openmed.service.app.JourneyResourceQuery.fields, openmed.service.app.JourneyResourceQuery.first, openmed.service.app.JourneyResourceQuery.namespace, openmed.service.app.JourneyResourceQuery.purpose, openmed.service.app.JourneyResourceQuery.resource_type, openmed.service.app.JourneyResourceQuery.role; and openmed.service.graphql_schema.JourneyResourceQuery.access_request_digest, openmed.service.graphql_schema.JourneyResourceQuery.after, openmed.service.graphql_schema.JourneyResourceQuery.attributes, openmed.service.graphql_schema.JourneyResourceQuery.consent_state, openmed.service.graphql_schema.JourneyResourceQuery.export_policy, openmed.service.graphql_schema.JourneyResourceQuery.fields, openmed.service.graphql_schema.JourneyResourceQuery.first, openmed.service.graphql_schema.JourneyResourceQuery.namespace, openmed.service.graphql_schema.JourneyResourceQuery.purpose, openmed.service.graphql_schema.JourneyResourceQuery.resource_type, openmed.service.graphql_schema.JourneyResourceQuery.role.

openmed.service.jobs no longer hashes document text or webhook URLs with hash_text. Job records carry keyed digests instead (see the asynchronous jobs guide).

Biomedical NER datasets never run remote code

openmed.eval.datasets.BiomedicalNerSource.trust_remote_code (also openmed.eval.datasets.biomedical_ner.BiomedicalNerSource.trust_remote_code) is removed. Dataset sources never pass trust_remote_code to datasets, so a dataset repository's loading script cannot run during evaluation. Remove the argument; a source that needs a loading script has to be converted to a script-free dataset first.

OpenMedKit for Android

OpenMedKit Android 4.0 commits its public API baseline at android/openmedkit/api/openmedkit.api. The changes below break callers compiled against 3.3. Kotlin callers that use named or default arguments recompile unchanged unless a row says otherwise. Java callers and prebuilt binaries must pass the new arguments.

Keyed hashing

com.openmed.openmedkit.deid.DeidentifyEngine.<init> no longer hashes with a public built-in salt.

  • DeidentifyEngine() is now keyless. It masks, removes and replaces, omits span digests, and refuses DeidentifyMethod.HASH with OpenMedSecretException (OpenMedSecretFailure.MISSING).
  • Hold the hash key in a secret provider: DeidentifyEngine(AndroidKeystoreSecretProvider()).
  • DeidentifyEngine(hashSalt) still compiles but is deprecated, and under the default HashKeyPolicy.STRICT it refuses the old public salt with OpenMedSecretFailure.PUBLIC_DEFAULT. Pass HashKeyPolicy.ALLOW_LEGACY_PUBLIC_SALT only to reproduce pre-4.0 digests.

com.openmed.openmedkit.DeidentifyEngine.deidentify gained a trailing surrogateKey: ByteArray? = null. Without a key, replace still renders [LABEL_REPLACED]. With a 16-to-64-byte key it renders a deterministic keyed surrogate that matches the other OpenMedKit surfaces. Java callers pass null to keep the 3.3 output.

OCR without ML Kit in the core artifact

ML Kit moved out of the core openmedkit artifact into openmedkit-mlkit. Follow Migrating from the bundled ML Kit adapter for these symbols:

  • com.openmed.openmedkit.ocr.MlKitOcrAdapter, with com.openmed.openmedkit.ocr.MlKitOcrAdapter.<init>, com.openmed.openmedkit.ocr.MlKitOcrAdapter.close and com.openmed.openmedkit.ocr.MlKitOcrAdapter.recognize, now ship in openmedkit-mlkit. The package is unchanged.
  • com.openmed.openmedkit.ocr.OcrAdapter.recognize and com.openmed.openmedkit.ocr.FakeOcrAdapter.recognize take an OcrImage instead of an ML Kit InputImage.

Document intake

Symbol Change Migration
com.openmed.openmedkit.intake.DocumentIntake.<init> Adds imageSource: DocumentImageSource and limits: DocumentIntakeLimits, both defaulted; ocrAdapter has no default Pass ocrAdapter explicitly
com.openmed.openmedkit.intake.DocumentIntakeResult.<init> and com.openmed.openmedkit.intake.DocumentIntakeResult.copy Add evidence: DocumentEvidence? = null Recompile; Java callers pass null
com.openmed.openmedkit.intake.RenderedPdfPage.<init> and com.openmed.openmedkit.intake.RenderedPdfPage.copy Add geometry: DocumentPageGeometry? = null Recompile; custom PdfPageSource implementations may supply page geometry

Policy profiles

com.openmed.openmedkit.policy.PolicyProfile.<init> and com.openmed.openmedkit.policy.PolicyProfile.copy add digest, taxonomy, defaultThreshold, labelThresholds, requiredCapabilities and excludedFeatures, all with defaults. com.openmed.openmedkit.policy.PolicyProfiles.load adds expectedDigest, resources and supportedCapabilities, also defaulted. Load profiles through PolicyProfiles.load rather than constructing PolicyProfile directly, and pass expectedDigest to pin a profile's content.

OpenMedKit for Swift

OpenMedKit Swift 4.0 commits public API baselines under swift/OpenMedKit/api/. Most changes below come from the value-free error contract: errors carry stable reason codes and asset roles instead of URLs, paths, file names or descriptor strings, so they can be logged without leaking local paths.

Tokenizer identity

OpenMedKit.OpenMedBackend.coreML now takes tokenizerName: String? = nil, and OpenMedKit.OpenMed.init takes an optional tokenizerName and a new tokenizerPin. There is no default tokenizer identity any more. Ship tokenizer assets in tokenizerFolderURL, or pass an OpenMedTokenizerPin when you explicitly opt into network acquisition. tokenizerName never triggers a download; a pin for a different repository fails with .identityMismatch.

Policy profiles

OpenMedKit.Policy.init adds expectedDigest: String? = nil. Pass it to pin a bundled profile's content.

OpenMedKit.PolicyError is now a struct with a stable code and a fieldPath, shared with the Python and Android policy engines. Match on code instead of enum cases:

Removed case code
OpenMedKit.PolicyError.blankName profile_name_invalid
OpenMedKit.PolicyError.unknownProfile profile_unknown
OpenMedKit.PolicyError.missingResource resource_missing
OpenMedKit.PolicyError.invalidProfile profile_invalid, or a more specific code such as manifest_invalid or digest_mismatch

Value-free error payloads

These cases no longer carry a URL or free-form string. Drop the bound value from case patterns, or match the new reason or role:

Symbol Payload now
OpenMedKit.NERPipelineError.uncompiledModelUnsupported None
OpenMedKit.OpenMedModelStoreError.httpError HTTP status only
OpenMedKit.OpenMedModelStoreError.invalidResponse None
OpenMedKit.OpenMedModelStoreError.missingManifest None
OpenMedKit.OpenMedModelStoreError.missingWeights None
OpenMedKit.OpenMedSegmenterError.invalidDescriptor OpenMedSegmenterError.DescriptorReason
OpenMedKit.OpenMedSegmenterError.missingDescriptor None
OpenMedKit.OpenMedSegmenterError.missingResource Resource index
OpenMedExtensionSupport.ExtensionRedactionError.invalidAsset ExtensionAssetRole
OpenMedExtensionSupport.ExtensionRedactionError.missingAsset ExtensionAssetRole
OpenMedExtensionSupport.ExtensionRedactionError.nonLocalAsset ExtensionAssetRole
OpenMedExtensionSupport.ExtensionRedactionError.unsupportedModelFormat None

Share and Action extensions on iOS

OpenMedExtensionSupport.ExtensionItemCodec.plainText is now nonisolated(nonsending): it runs in the caller's isolation domain, so a main-actor view controller can pass its extension context's items without sending them to another actor. Callers keep the same await call; code that stored the function as a value or overrode isolation must be recompiled.