mvt/docs/output-schemas.md

Output schemas

MVT validates its JSON output with versioned Pydantic models. The schema version used for a run is recorded as output_schema_version in info.json.

MVT preserves the established on-disk format: most module files contain an array of result objects, while modules whose results are naturally grouped contain an object keyed by source or namespace. Detection files and alerts.json contain arrays of alert objects. Timestamps remain strings because their timezone and precision depend on the source artifact.

Exporting JSON Schema

Both platform commands can print a versioned JSON Schema bundle:

mvt-ios schemas
mvt-android schemas

Use --output to write one Draft 2020-12 JSON Schema file for each output:

mvt-ios schemas --output ./mvt-ios-schemas
mvt-android schemas --output ./mvt-android-schemas

Python API

Models and schema discovery functions are available from mvt.schemas:

from mvt.schemas import get_output_model

SafariHistoryOutput = get_output_model("safari_history", platform="ios")
validated = SafariHistoryOutput.model_validate(records)
json_schema = SafariHistoryOutput.model_json_schema()

Common outputs have dedicated field-level models. Built-in module outputs have a declared root shape, and modules with an established dedicated record model expose its complete field schema.

Custom modules

Custom modules can publish a precise contract by assigning a Pydantic root model to output_model:

from pydantic import BaseModel, RootModel

from mvt.common.module import MVTModule


class ExampleRecord(BaseModel):
    message: str
    timestamp: str | None = None


class ExampleOutput(RootModel[list[ExampleRecord]]):
    pass


class ExampleModule(MVTModule):
    output_model = ExampleOutput

For compatibility, a custom module without output_model can still write an array or object containing JSON values. MVT logs a warning when it uses this generic contract. A future major release may require custom modules to declare their output models.

Compatibility policy

Within one output schema major version, required fields are not removed and field types are not narrowed. New optional fields may be added. A breaking output change requires a new schema major version and a migration note.