openmed.agent.tool_contract_lint checks a clinical agent tool's JSON input
schema before registration or review. It is deterministic, local-only, and
value-free: findings contain only a fixed severity, a stable reason code, and a
JSON Pointer path into the schema.
The root object declares one versioned, canonical purpose identifier with
x-openmed-purpose. Every property, including nested properties, repeats that
purpose and declares one x-openmed-minimum-data disposition:
required: the field is a necessary, directly supplied input;optional: the tool accepts the field but does not require it;derived: the tool could derive the field instead of receiving it.
Only required properties that also appear in their containing object's JSON
Schema required array pass. Optional and derived inputs expand the accepted
data surface and are blocking findings. A field declared for a different
purpose is also blocking.
from openmed.agent.tool_contract_lint import lint_tool_contract
schema = {
"type": "object",
"x-openmed-purpose": "purpose:org.example/care-summary@1.0.0",
"properties": {
"question": {
"type": "string",
"x-openmed-purpose": "purpose:org.example/care-summary@1.0.0",
"x-openmed-minimum-data": "required",
}
},
"required": ["question"],
"additionalProperties": False,
}
report = lint_tool_contract(schema)
assert report.passedFor arrays, annotate the array property. Object properties nested below its
items schema have their own annotations. Keep input objects closed with
additionalProperties: false so runtime schema validation cannot admit fields
outside the reviewed contract.
All current findings have severity error and fail review.
| Reason code | Meaning |
|---|---|
invalid_schema |
The inspected schema structure is malformed. |
missing_purpose |
The root or a field lacks x-openmed-purpose. |
invalid_purpose |
A purpose is not a versioned canonical purpose ID. |
overbroad_for_purpose |
A field's purpose differs from the root purpose. |
missing_minimum_data |
A field lacks x-openmed-minimum-data. |
invalid_minimum_data |
A minimum-data disposition is outside the closed vocabulary. |
optional_input |
A field is optional by annotation or JSON Schema structure. |
derived_input |
A field is marked as derivable and should not be supplied. |
open_input_object |
An object does not set additionalProperties to false. |
unsupported_schema_keyword |
A composition or dynamic-property keyword could hide inputs from this linter. |
Reports are sorted by schema path and reason code, deduplicate identical findings, and serialize to byte-stable compact JSON:
{"findings":[],"passed":true,"schema_version":"openmed.agent.tool_contract_lint.v1"}The linter never includes annotation values, examples, defaults, descriptions, or clinical values in a finding, exception, representation, or report. Schema paths can include developer-authored property names, so property names must not contain patient, clinician, tenant, or record identifiers.
This check makes a declared minimum-data contract reviewable; it does not
decide whether a field is clinically necessary, authorize access, redact
runtime values, or prove that a tool implementation follows its schema. A
reviewer remains responsible for confirming that each required declaration
is appropriate for the stated purpose. Combine the reviewed schema with
purpose-bound access tickets, capability grants, runtime argument
classification, and the later projection layer where applicable.
The first contract version intentionally accepts bounded direct properties
trees and array items only. $ref, tuple schemas, composition keywords,
conditional subschemas, pattern properties, and unevaluated properties fail
closed instead of being partially inspected.