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 every1.xversion.
Migrate as follows:
- A request that omits
schema_versionresolves to the lowest version carrying every field it uses:1.0.0,1.1.0, or1.2.0when it carriesmedia. Existing1.0.0and1.1.0requests decide exactly as before and keep their result version. - A request that declares
schema_version: "1.1.0"and carriesmediais now refused withinput_error. Declare"1.2.0"or omit the version. Code that adds media to an existing request withdataclasses.replacemust also setschema_version="1.2.0"orNone. - Validators pinned to
https://openmed.dev/schemas/decision-request/1.1.0or.../decision-result/1.1.0should load the1.2.0documents, which accept every1.0.0,1.1.0and1.2.0payload. DECISION_SCHEMA_VERSIONis now"1.2.0", andmigrate_decision_result()migrates to1.2.0by default. Passtarget_version="1.1.0"to keep the previous label; results have the same fields at1.1.0and1.2.0.- The TypeScript client's
schema_versionfields use the newDecisionSchemaVersionunion, 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 refusesDeidentifyMethod.HASHwithOpenMedSecretException(OpenMedSecretFailure.MISSING).- Hold the hash key in a secret provider:
DeidentifyEngine(AndroidKeystoreSecretProvider()). DeidentifyEngine(hashSalt)still compiles but is deprecated, and under the defaultHashKeyPolicy.STRICTit refuses the old public salt withOpenMedSecretFailure.PUBLIC_DEFAULT. PassHashKeyPolicy.ALLOW_LEGACY_PUBLIC_SALTonly 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, withcom.openmed.openmedkit.ocr.MlKitOcrAdapter.<init>,com.openmed.openmedkit.ocr.MlKitOcrAdapter.closeandcom.openmed.openmedkit.ocr.MlKitOcrAdapter.recognize, now ship inopenmedkit-mlkit. The package is unchanged.com.openmed.openmedkit.ocr.OcrAdapter.recognizeandcom.openmed.openmedkit.ocr.FakeOcrAdapter.recognizetake anOcrImageinstead of an ML KitInputImage.
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.