Skip to main content

Form fingerprint

The fingerprint of a form definition is a SHA-256 hash of the form that is stable as long as the structure of the form is not changed. Textual changes in the content of the form definition will not alter the fingerprint hash. But adding, removing or reordering elements does. The fingerpint is useful for quick validation when the runner pushes form results back to your application. Since the runner will include this fingerprint hash in the response data, you can use it to verify that the results coming in are generated by the right (version of the) form.

Generating the fingerprint at client-side​

The fingerprint is generated by the Runner library, the engine that drives all Tripetto runners. You could generate the fingerprint when running a form. But, since the fingerprint is calculated from the form definition, it is more efficient to generate it when saving a form. You then can store the fingerprint along with the form definition. The following code shows how to do that using the calculateFingerprintAndStencil function:

import { calculateFingerprintAndStencil } from "@tripetto/runner";
import { Builder } from "@tripetto/builder";

// Generate the fingerprint when the form definition is saved
const builder = new Builder({
    onSave: (definition) => {
        const fingerprint = calculateFingerprintAndStencil(definition)?.fingerprint;

        // The fingerprint hash is now available (or `undefined` when something went wrong):
        console.log(fingerprint);
    }
});
tip

In addition to the fingerprint hash, you should also have a look at the data stencil hashes of a form.

Generating the fingerprint at server-side​

The Runner library can also run in Node.js environments (it doesn't need a browser). So if your server-side runs Node.js you can also generate the fingerprint there. For example, when you are saving a form definition to a server store.

import { calculateFingerprintAndStencil } from "@tripetto/runner";

const definition = /* Definition goes here */;
const fingerprint = calculateFingerprintAndStencil(definition)?.fingerprint;

// The fingerprint hash is now available (or `undefined` when something went wrong).
tip

If you are able to generate the fingerprint at server-side, always use that approach. It makes it impossible for a client to interfere with the fingerprint hash.