openmed.agent.schema_compatibility provides explicit, content-free compatibility
verification for agent-produced artifacts. Run summaries, handoff packets, policy
matrices, and evidence references evolve independently across versions. Consumers
use this module to enforce schema boundaries rather than silently accepting
unsupported schemas.
Evaluation returns one of four closed outcomes with a stable reason code:
compatible: The incoming schema version falls within the caller's declared inclusive range (min_version <= incoming <= max_version). Reasons:exact_matchorwithin_range.upgrade-required: The incoming schema is older than the consumer's minimum supported version (incoming < min_version). Reason:upgrade_required.downgrade-required: The incoming schema is newer than the consumer's maximum supported version (incoming > max_version). Reason:downgrade_required.unsupported: The version or kind cannot be reconciled. Reasons:unknown_artifact_kind,malformed_version,prerelease_unsupported, orinvalid_range.
Check compatibility with a declared SchemaRange:
from openmed.agent import (
ArtifactKind,
CompatibilityOutcome,
SchemaRange,
check_schema_compatibility,
)
range_policy = SchemaRange(min_version="1.0.0", max_version="2.1.0")
result = check_schema_compatibility(
artifact_kind=ArtifactKind.EVIDENCE,
incoming_version="1.4.2",
supported_range=range_policy,
)
if result.is_compatible:
print("Schema is compatible:", result.reason_code)
elif result.outcome == CompatibilityOutcome.UPGRADE_REQUIRED:
print("Artifact migration required before use")For multi-artifact agent workflows, use SchemaCompatibilityMatrix:
from openmed.agent import ArtifactKind, SchemaCompatibilityMatrix, SchemaRange
matrix = SchemaCompatibilityMatrix(
{
ArtifactKind.EVIDENCE: SchemaRange("1.0.0", "2.0.0"),
ArtifactKind.PREVIEW: SchemaRange("1.0.0", "1.5.0"),
ArtifactKind.FHIR: SchemaRange("1.0.0", "1.2.0"),
}
)
result = matrix.check(ArtifactKind.EVIDENCE, "1.2.0")
payload = result.to_json()CompatibilityResult.to_dict() and to_json() serialize deterministically using
only categorical artifact kind and semantic version strings:
{
"artifact_kind": "evidence",
"incoming_version": "1.4.2",
"max_version": "2.1.0",
"min_version": "1.0.0",
"outcome": "compatible",
"reason_code": "within_range"
}to_json() generates compact JSON with sorted keys for byte-for-byte identical
output across runs and platforms.
Compatibility checks never inspect, read, or infer schema characteristics from artifact content or payload files. Unknown mandatory schema kinds and malformed version identifiers fail closed without echoing unvalidated values.