JSON Reports¶

Status: Active v1.0 reference
Scope: JSON reports and Core-owned structured JSON surfaces
Applies to: OrbitFabric v1.0.0 - Stable Mission Data Contract

This page documents the JSON reports currently produced by OrbitFabric.

Current documented baseline:

v1.0.0 - Stable Mission Data Contract

OrbitFabric JSON reports are generated artifacts intended for:

CI inspection;
automated validation workflows;
reproducible scenario evidence;
Core-owned contract introspection;
Core-owned entity indexing;
Core-owned relationship inspection;
downstream integration tooling.

They are not the source of truth.

The source of truth remains the Mission Model YAML and scenario YAML.

Stability status¶

The following JSON report families are part of the v1.0 stable surface:

lint JSON report
simulation JSON report
model_summary.json
entity_index.json
relationship_manifest.json for admitted families

The following JSON manifest families remain public preview generated artifacts unless explicitly promoted later:

runtime_contract_manifest.json
ground_contract_manifest.json

Future versions may introduce:

JSON Schema definitions;
additional metadata fields;
richer diagnostic structures;
compatibility checks between tool version and Mission Model version.

These are not part of the v1.0.0 stable release boundary.

Version fields¶

OrbitFabric JSON reports include the OrbitFabric tool/package version where applicable.

Current lint report example:

{
  "tool": "orbitfabric-lint",
  "version": "1.0.0"
}

This identifies the OrbitFabric tool version that produced the report.

Mission Model version is represented separately.

For lint reports, the Mission Model version is exposed as:

{
  "mission": "demo-3u",
  "model_version": "0.1.0"
}

The top-level version and model_version fields have different meanings.

The model summary report uses orbitfabric_version and summary_version because it is a Core-owned contract introspection surface rather than a lint or simulation report.

The entity index report uses orbitfabric_version and index_version because it is a Core-owned entity surface rather than a lint or simulation report.

The relationship manifest report uses orbitfabric_version and manifest_version because it is a Core-owned relationship surface rather than a lint or simulation report.

See also:

Reference -> Versioning Model
Reference -> JSON Report Compatibility

Lint report¶

Generated by:

orbitfabric lint examples/demo-3u/mission/ \
  --json generated/reports/lint_report.json

Tool identifier:

orbitfabric-lint

Lint report top-level fields¶

Field	Type	Meaning
`tool`	string	Report producer. Current value: `orbitfabric-lint`.
`version`	string	OrbitFabric tool/package version that produced the report.
`mission`	string	Mission ID loaded from the Mission Model.
`model_version`	string	Mission Model version declared by the mission.
`result`	string	Machine-readable lint result.
`loaded`	object	Counts of loaded core Mission Model domains.
`summary`	object	Count of findings by severity.
`findings`	array	List of lint findings.

Lint result values¶

Current lint report result values:

Value	Meaning
`passed`	No error or warning findings.
`passed_with_warnings`	Warning findings exist, but no error findings exist.
`failed`	At least one error finding exists.

Simulation report¶

Generated by:

orbitfabric sim examples/demo-3u/scenarios/payload_data_flow_evidence.yaml \
  --json generated/reports/payload_data_flow_evidence_report.json

Tool identifier:

orbitfabric-sim

Simulation report top-level fields¶

Field	Type	Meaning
`tool`	string	Report producer. Current value: `orbitfabric-sim`.
`version`	string	OrbitFabric tool/package version that produced the report.
`mission`	string	Mission ID.
`scenario`	string	Scenario ID.
`result`	string	Scenario execution result.
`summary`	object	Counts of key execution outputs.
`timeline`	array	Ordered timeline entries.
`events`	array	Emitted events.
`commands`	array	Executed commands.
`mode_transitions`	array	Mode transitions.
`data_flow_evidence`	array	Contract-level data-flow evidence records.
`final_state`	object	Final simulator state.
`failed_expectations`	array	Failed scenario expectations.

Simulation result values¶

Current simulation report result values:

Value	Meaning
`passed`	All scenario expectations passed.
`failed`	One or more scenario expectations failed.

Simulation summary object¶

Current fields:

Field	Meaning
`events`	Number of emitted events.
`commands`	Number of executed or auto-dispatched commands.
`mode_transitions`	Number of mode transitions.
`data_flow_evidence`	Number of data-flow evidence records.
`failed_expectations`	Number of failed expectations.

Data-flow evidence records¶

A data-flow evidence record is created when an accepted command declares a data product in expected_effects.data_products.

It traces:

command -> data product -> storage intent -> downlink intent -> eligible downlink flows -> contact windows

Record shape:

{
  "t": 5,
  "data_product_id": "payload.radiation_histogram",
  "producer": "demo_iod_payload",
  "producer_type": "payload",
  "triggered_by_command": "payload.start_acquisition",
  "storage_intent": {
    "declared": true,
    "class": "science",
    "retention": "7d",
    "overflow_policy": "drop_oldest"
  },
  "downlink_intent": {
    "declared": true,
    "policy": "next_available_contact"
  },
  "eligible_downlink_flows": [
    "science_next_available_contact"
  ],
  "contact_windows": [
    "demo_contact_001"
  ]
}

This is evidence about declared contract consistency.

It does not imply real payload file generation, onboard storage writes, downlink queue execution, contact scheduling, RF behavior or ground integration.

Model summary report¶

Generated by:

orbitfabric export model-summary examples/demo-3u/mission/ \
  --json generated/reports/model_summary.json

Output kind:

{
  "kind": "orbitfabric.model_summary",
  "summary_version": "0.1"
}

The model summary report contains:

summary_version
kind
orbitfabric_version
mission
source
boundaries
counts
domains

It answers:

What contract domains are present in this mission?

It does not expose entity records, relationship records, source line or column locations, plugin APIs or Studio-specific APIs.

See also:

Reference -> Contract Introspection Surface

Entity index report¶

Generated by:

orbitfabric export entity-index examples/demo-3u/mission/ \
  --json generated/reports/entity_index.json

Output kind:

{
  "kind": "orbitfabric.entity_index",
  "index_version": "0.1"
}

The entity index report contains:

index_version
kind
orbitfabric_version
mission
source
boundaries
counts
domains
entities

It answers:

What contract entities are defined in this mission?

Each entity record includes:

id
domain
entity_type
display_name
source_file
provenance
required_domain
present

The entity index does not expose relationship records, dependency graphs, source line or column locations, YAML AST data, plugin APIs or Studio-specific APIs.

See also:

Reference -> Entity Index Surface

Relationship manifest report¶

Generated by:

orbitfabric export relationship-manifest examples/demo-3u/mission/ \
  --json generated/reports/relationship_manifest.json

Output kind:

{
  "kind": "orbitfabric.relationship_manifest",
  "manifest_version": "0.1-candidate"
}

The manifest_version value is a report format identifier, not the release status of the surface.

In v1.0.0, the relationship manifest surface is stable for the admitted relationship families documented in the Relationship Manifest Surface reference.

The relationship manifest report contains:

manifest_version
kind
orbitfabric_version
mission
source
boundaries
relationship_types
relationship_type_counts
relationships

It answers:

How are indexed mission contract entities related?

Each relationship record includes:

relationship_id
relationship_type
from
to
derived_from

The relationship manifest does not expose graph behavior, dependency graph behavior, source line or column locations, YAML AST data, plugin APIs, runtime behavior, ground behavior or Studio-specific APIs.

See also:

Reference -> Relationship Manifest Surface

Stability and compatibility references¶

v1.0.0 defines compatibility classification references for current stable, preview, disposable, internal and out-of-scope surfaces.

These include:

Stability and Compatibility Contract
Mission Model Stability Contract
CLI Contract v1
Generated Surfaces Stability
Lint Rule Code Stability
JSON Report Compatibility
Scenario Evidence Stability
Release Compatibility Policy

These references classify compatibility expectations for existing surfaces.

They do not add report fields, report schemas, JSON Schema publication, schema migration tooling, runtime behavior, ground behavior or plugin execution.

Ground artifacts and JSON dictionaries¶

OrbitFabric also generates JSON ground dictionaries through:

orbitfabric gen ground examples/demo-3u/mission/

The JSON ground dictionaries are generated under:

generated/ground/generic/dictionaries/

They are ground-facing generated artifacts, not stable JSON report families.

They are documented separately in:

Reference -> Ground Integration Artifacts

Simulation report example¶

Compact example:

{
  "tool": "orbitfabric-sim",
  "version": "1.0.0",
  "mission": "demo-3u",
  "scenario": "payload_data_flow_evidence",
  "result": "passed",
  "summary": {
    "events": 2,
    "commands": 2,
    "mode_transitions": 1,
    "data_flow_evidence": 1,
    "failed_expectations": 0
  },
  "timeline": [],
  "events": [],
  "commands": [],
  "mode_transitions": [],
  "data_flow_evidence": [],
  "final_state": {
    "mode": "PAYLOAD_ACTIVE",
    "telemetry": {}
  },
  "failed_expectations": []
}

Current limitations¶

The current JSON reporting surface does not include:

JSON Schema URL;
report generation timestamp;
source file paths for lint and simulation reports;
Git commit SHA;
environment metadata;
compatibility matrix;
optional payload/data product/contact loaded counts in the lint report;
relationship records in the model summary report;
relationship records in the entity index report;
source locations in the entity index report;
source locations in the relationship manifest report;
relationship graph behavior;
real storage, downlink or ground runtime state.