# JSON diff reports Use JSON reports to automate layout review while retaining the evidence behind a result. The [comparison rules](comparison.md) define equality; the [version 1 JSON Schema](diff-report-v1.schema.json) defines every field. A [complete example](https://mpxd.net/code/jan/pheon/src/branch/master/tests/golden/report-geometry.json) shows geometry changes. ```sh pheon diff before.gds after.gds --format json > report.json pheon diff before.gds after.gds --format json --hierarchy graph pheon diff before.gds after.gds --format json --top CHIP --layer 1/0 ``` `diff` writes one UTF-8 JSON document and a newline to stdout, including comparison diagnostics. Output write failures go to stderr and return 2; interrupted output is invalid. Other CLI commands retain text output. ## Check the result first | `status` | `result` | Exit code | Meaning | | --- | --- | --- | --- | | `complete` | `equal` | 0 | Equal under the recorded profile and scope. | | `complete` | `different` | 1 | Differences found. | | `incomplete` | `different` | 2 | Definite differences, with comparison limitations. | | `incomplete` | `unknown` | 2 | Equality cannot be established. | | `failed` | `unknown` | 2 | No comparison result. | A code of 1 is an expected result, including when saving a report. Unsupported records, future metadata, unresolved references, and cycles make a comparison incomplete. Malformed input, I/O errors, invalid scopes, and command errors fail. `summary` covers the whole scoped comparison before display filters. Counts are `exact` for complete results and `observed` for incomplete ones. Failed reports have a null summary and empty change arrays. Replacement suggestions and affected ancestors do not add to change counts. ## Scope and evidence selection `scope` records `top`, `cell`, and numeric `layer` selectors; null means unrestricted. The full input is parsed before scope selection. `report_selection` records display-only cell/layer filters and `max_objects`. JSON is unbounded by default. Explicit `--max-changes N` limits total emitted removals plus additions, with removals first within each cell. Selection counters `filtered_cells`, `filtered_objects`, `limited_objects`, and `emitted_objects` explain omissions. `truncated` is true when filtering or limits omit evidence. Library changes, layer-name changes, diagnostics, summaries, and the optional graph remain. Replacement links appear only if both objects are emitted. ## Read values safely Aggregate counts, limits, and byte offsets are unsigned decimal **strings** to avoid JSON number precision loss. Coordinates, numeric tags, layer/type pairs, widths, and array dimensions are bounded JSON numbers. Null means absent or unavailable; zero and empty arrays remain meaningful values. `inputs.old` and `inputs.new` record paths, presence, and UNITS. An absent revision is distinct from an empty library. The Rust API supports absent Git revisions with `Document::empty_like`. Failed reports may lack presence, units, or argument context. Non-UTF-8 paths use null `path` and `path_encoded_hex`: `0x`-prefixed platform-native Rust path bytes, not a portable filename encoding. ## Interpret changes | Section | Evidence | | --- | --- | | `library_changes` | Typed before/after header fields, including unscaled UNITS. Presence changes use a null tag and boolean values. | | `layer_name_changes` | Before/after names for numeric pairs `{ "number": 1, "purpose": 0 }`. | | `layer_legend` | Unchanged names available in scope. Annotation labels do not also appear as object changes. | | `cell_changes` | Name, nullable before/after cell records, attributes, removed/added objects, and replacement suggestions. A null side means absent; an existing empty cell still has a byte offset. | Objects retain kind, numeric tag, layer, target, bounds, source side and half-open byte range, typed fields, and a sorted property multiset including duplicates. Convenience fields include origin, width, and reference dimensions. SREF counts are `[1, 1]`; kind and retained fields still distinguish a one-element AREF. Coordinates are cell-local database units. Bounds are stored-coordinate envelopes, excluding stroke width, rendered text, and recursive target geometry. Consider UNITS before deriving physical dimensions. Fields contain `tag`, display `name`, `encoding`, decoded `value`, and `payload_hex`. Numeric tags are authoritative. XY values are lists of points; other numeric values are arrays. Unsupported encodings have null values and preserved bytes. Invalid UTF-8 strings/properties have null decoded values; hex preserves their bytes. Evidence follows the comparison profile: boundary/box rings are canonicalized, string padding is removed, and fields/properties are sorted. REAL8 encodings and explicit defaults remain significant. For gzip inputs, source offsets locate records in the decompressed layout. Replacements link report-local removed/added IDs with `match_rule`, `field_changes`, and `properties_changed`. The `unique_layer_change` rule matches a unique polygon, box, or path on each side with identical retained fields and properties outside the layer and datatype fields. The other rules are `unique_kind_layer_bounds`, `unique_kind_layer`, and `unique_kind_target`. Ambiguous candidates stay separate. Replacement IDs refer only to objects in the current report. Explanation text is for display only. ## Diagnostics and hierarchy Diagnostics provide `code`, `severity`, `message`, input side, byte offset, cell, layer, and target; unknown context is null. Use codes and context for automation. Fatal parser locations currently appear only in the human message, with null structured offsets. Do not parse message wording. Limitation codes are `unsupported_record`, `unsupported_metadata_version`, `unresolved_reference`, `hierarchy_cycle`, and `scope_mismatch`. Failure codes are `invalid_input`, `io_error`, `invalid_scope`, and `command_error`. `--hierarchy graph` includes the full scoped union graph; otherwise `hierarchy` is null. Nodes are keyed by name, with per-side states `included`, `outside_scope`, `unresolved`, or `absent`, and change states `direct`, `affected`, or `unchanged`. Edges record parent, target, before/after direct placement counts, and changed reference records. Array multiplicities are symbolic, not expanded or recursively accumulated. Shared cells occur once and removed edges remain. Display filters, object limits, and text depth do not trim the graph. ## Versions `schema_version` is 1, `comparison_profile` is `pheon-structural-v1`, and `producer.name` is `pheon`. Structure, equality rules, and producer version evolve independently. Understand the profile before interpreting equality. Consumers should tolerate additional optional fields and unknown codes/rules without assuming equality. Removed fields or changed meanings require a schema change. Serialization is deterministic for identical inputs, paths, options, and producer version. Sorted evidence retains duplicates. Reports have no generation timestamp or required content fingerprint. See [development](development.md) for contract tests and golden updates.