Introduction
A block design inside a Vivado project is represented by a file that has a .bd suffix in its file name, for example vivado_system.bd. This file contains all the information about the block design in a format that is textual and readable by human. In older versions of Vivado, this file was written in XML format. Today, the JSON format is used to represent a block design.
Thanks to the textual format, it is possible to compare two block design files with well-known tools for textual comparison (diff and similar graphical tools). This allows keeping track on which changes have been made to the block design.
However, the JSON format has a significant drawback in relation to comparing text files: In the definitions of objects, the properties and their values can be listed in arbitrary order. Hence, tools like diff can show that the textual content of two JSON files is significantly different even though they contain exactly the same information.
Unfortunately, some parts of the block design files that are generated by Vivado suffer from this problem. As a result, a textual comparison between two .bd files shows many misleading differences, that are the result of inconsistent ordering of the information.
Canonicalization of a JSON file
The natural solution to random ordering of a textual file is to bring this file to a canonical form. There is a strict definition on how to perform such a canonicalization in RFC 8785, however there is no need to follow that standard for the purpose of comparing two files. Avoiding random reordering is enough.
A simple solution is sorting the properties of objects in alphabetical order, according to the properties' names. This ensures a consistent representation of the information inside a JSON file. However, reordering the information in this way has a drawback. The properties are usually listed in an order that makes the file is easy to read: Important properties are usually put first in the file, and properties are grouped according to their meaning. It's therefore slightly more difficult to read a JSON file in canonical form.
A Perl script
Thanks to the JSON Perl module, it's easy to write a Perl script that carries out canonicalization of a JSON file:
#!/usr/bin/perl
use warnings;
use strict;
use JSON;
local $/; # Slurp mode
my $json = JSON->new->allow_nonref->space_after->indent->canonical;
my $in = <>;
my $h = $json->decode($in);
my $out = $json->encode($h);
print $out;
The use of this script is with something like this:
$ ./jsonize.pl vivado_system.bd > canonicalized.bd
In order to compare block designs, perform a textual comparison of two canonicalized JSON files.