Schema-tools

This repository contains a suite of components and modules to handle certificates and schemas. The specification of these libraries can be found in SEP.

Supported Schemas

Name	Version range
EN10168	0.0.2 - 0.4.x
E-CoC	1.0.0
CoA	0.0.3 - 1.x.x
CDN	xx

Deprecations

E-CoC v0.0.2 has been deprecated.

List of packages

• Certificate-Model The certificate-model module provides a class using template pattern to generate a class / instances based a given JSON schema.

• Certificate-Summary Build certificate summary by retrieving general common properties.

• Extract-Emails This repository contains tools to extract information (emails, VAT, ...) about parties included in certificate(s).

• Generate-CoA-PDF-Template This package provides a minified script to be used in CoA-schemas specific verison release.

• Generate-EN10168-PDF-Template This package provides a minified script to be used in EN10168-schemas specific verison release.

• Generate-HTML The generate-html module uses handlebars to generate HTML string using a certificate using a supported JSON schema.

• Generate-Interfaces The generate-interfaces module is using the json-schema-to-typescript package to generate TS interfaces and types using a JSON / OpenAPI schema.

• Generate-PDF The generate-pdf module uses pdfmake to generate PDF buffer | stream from a certificate as JSON or HTML.

• Types Contains shared types. Uses duck typing / type guards for quick validation. To be updated every time the schema is updated.

• Utils internal utilities including static resources caching.

• Validate Takes certificates as input and validates them by using the referenced JSON schema.

• Versioning Update all files containing versioning during release, to be used within schemas repositories.

Dependency graph

Contributing

When updating the schema (links below), the tools need to be updated at the same time.

Schema links:

• EN10168
• E-CoC
• CoA
• CDN

Process:

1. Update the schema in question
2. Check and update the types using the create-schema-interfaces CLI tool
3. If necessary, make changes in generateContent.ts in schema-tools/packages/generate-coa-pdf-template/src/generateContent.ts or schema-tools/packages/generate-en10168-pdf-template/src/generateContent.ts and run npm run build. If generateContent.ts has been changed and built, copy the contents of dist/packages/generate-*-pdf-template/generateContent.cjs to the schema repository and replace the contents of generate-pdf.min.js with the new minified code. Edit: this step has been automated as of PR #147 - #147
4. For a new Release Candidate, add a new fixture (used for testing) using the method outlined below:

Starting out

To get started, run :

npm install
npm run build

Make sure you have installed ImageMagick and GhostScript on your system. This is required for testing the PDF generation.

# MacOS
brew install graphicsmagick
brew install ghostscript
# Linux
sudo apt-get install graphicsmagick
sudo apt-get install ghostscript

Development

When working on changes that affects multiple packages, you should rebuild them when they are declared as dependencies in order for those changes to be effective.

npm run build
npm install

Testing

The following packages only test the compatibility with the latest schema version:

• generate-coa-pdf-template
• generate-en10168-pdf-template

The remaining packages should be made compatible with all schema versions

Fixtures

• Create or use a folder following the schema name
• ⚠️ Create a subfolder following the version of the release candidate
• Add a valid json certificate with the name valid_cert.json
• Add an invalid json certificate with the name invalid_cert.json
• Add the translations.json - for ease of use we keep English and German translations in a single file
• Add the extraTranslations.json if necessary (for use with CoA) - for ease of use we keep English and German translations in a single file
• Add a copy of the template.hbs from the schema repo (for use with the local rendering tests until the version is released)
• certificate.ts, schemaTypes.ts, template_hbs.html and valid_cert.pdf should be dynamically generated using the following scripts:

Typescript interface

To generate certificate.ts (json-schema converted to Typescript interfaces),from the root directory, run the following command, updating the version number and schema name :

npm run fixtures:interfaces -- -s ../CoA-schemas/schema.json -o fixtures/CoA/v0.2.0/certificate.ts

where -s indicates the path to the updated schema and -o indicates the path to the certificate to be generated.

schemaTypes.ts

generate-<en10168/coa>-pdf-template/src/types/schemaTypes.ts also needs to be updated. The above command can be run again with the output replaced by the path to the schemaTypes.ts in question, for example:

npm run fixtures:interfaces -- -s ../CoA-schemas/schema.json -o packages/generate-coa-pdf-template/src/types/schemaTypes.ts

HTML certificate

To generate template_hbs.html (HTML certificate generated from Handlebars template), from the root directory, run the following command, updating the version number and schema name :

npm run fixtures:html -- -c fixtures/CoA/v1.0.0/valid_cert.json -o fixtures/CoA/v1.0.0/valid_cert.html -t fixtures/CoA/v1.0.0/translations.json -T ../CoA-schemas/template.hbs -e fixtures/CoA/v1.0.0/extra_translations.json -p ../CoA-schemas/partials-map.json

For EN10168

npm run fixtures:html -- -c fixtures/EN10168/v0.4.1/valid_cert.json -o fixtures/EN10168/v0.4.1/valid_cert.html -t fixtures/EN10168/v0.4.1/translations.json -T ../EN10168-schemas/template.hbs -p ../EN10168-schemas/partials-map.json

If external translations are not needed, remove the -e command from the above command. If partial maps are not needed, remove the -p command from the above command.

If you get an error that a partial could not be loaded, make sure that the full (absolute) filepath is included in your local partials-map.json.

PDF certificate

To generate valid_cert.pdf (PDF certificate generated from JS generator), from the root directory, run the following command, updating the version number and schema name :

npm run fixtures:pdf -- -c fixtures/CoA/v1.1.0/valid_cert.json -o fixtures/CoA/v1.1.0/valid_cert.pdf -t fixtures/CoA/v1.1.0/translations.json -g ../CoA-schemas/generate-pdf.min.js -s ../CoA-schemas/generate-pdf.styles.json -e fixtures/CoA/v1.1.0/extra_translations.json

# or using remote resources
npm run fixtures:pdf -- -c fixtures/EN10168/v0.3.0/valid_cert.json -o fixtures/EN10168/v0.3.0/valid_cert.pdf -t 'fixtures/EN10168/v0.3.0/translations.json' -g 'https://schemas.s1seven.com/en10168-schemas/v0.3.0/generate-pdf.min.js' -s 'https://schemas.s1seven.com/en10168-schemas/v0.3.0/generate-pdf.styles.json'

EN10168

npm run fixtures:pdf -- -c fixtures/EN10168/v0.4.1/valid_cert.json -o fixtures/EN10168/v0.4.1/valid_cert.pdf -t fixtures/EN10168/v0.4.1/translations.json -g ../EN10168-schemas/generate-pdf.min.js -s packages/generate-en10168-pdf-template/utils/styles.json

If external translations are not needed, remove the -e command from the above command.

Troubleshooting PDF tests

If the PDF hashes are not matching, ensure that the styles in the filepath that you are passing to the npm run fixtures:pdf are the same as the ones that are used for the tests such as packages/generate-en10168-pdf-template/utils/styles.js.

PDF Generation - Making changes to a PDF

To change the appearance of a PDF, make the needed changes to generateContent.ts for CoA and en10168, run the build script to generate a minified version in dist which can then be used following the -g argument in the root script fixtures:pdf PDF Generator.

Tests to update for new releases

When creating a new release, the following tests need to be updated with the latest version (usually in a testSuitesMap or testMap array):

• generate--pdf-template
• generate-pdf
• generate-html
• certificate-summary
• extract-emails
• generate-interfaces

Creating new releases

To first see what will be released, run nx release --dry-run.

Note: releases should only be created on main. Be sure to export a GITHUB_TOKEN env variable so the github releases can be done automatically. You should also be logged in to the npm cli if creating an npm release. To login, use npm login from the cli.

To release new versions of the schema-tools packages, run GITHUB_TOKEN=<token> nx release. This will automatically bump package version numbers, generate changelogs, create github releases and release on npm.

License