{"id":24369911,"url":"https://github.com/s1seven/schema-tools","last_synced_at":"2025-04-10T17:29:16.276Z","repository":{"id":37006964,"uuid":"305376070","full_name":"s1seven/schema-tools","owner":"s1seven","description":"Tools to create, validate and render certificates using Material Identity JSON schemas","archived":false,"fork":false,"pushed_at":"2024-10-21T09:00:12.000Z","size":81813,"stargazers_count":1,"open_issues_count":19,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-03T18:01:48.938Z","etag":null,"topics":["json-schema","typescript"],"latest_commit_sha":null,"homepage":"https://materialidentity.org/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/s1seven.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":"audit-ci.json","citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-10-19T12:26:50.000Z","updated_at":"2023-07-18T09:12:59.000Z","dependencies_parsed_at":"2024-05-02T12:38:22.895Z","dependency_job_id":"1173771d-3619-4e5b-b4fd-2f11d9ad5dbd","html_url":"https://github.com/s1seven/schema-tools","commit_stats":{"total_commits":1218,"total_committers":11,"mean_commits":"110.72727272727273","dds":0.4967159277504105,"last_synced_commit":"5666c1eceebb33f67ab45e07d04c5383b9fac906"},"previous_names":[],"tags_count":498,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s1seven%2Fschema-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s1seven%2Fschema-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s1seven%2Fschema-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s1seven%2Fschema-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/s1seven","download_url":"https://codeload.github.com/s1seven/schema-tools/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248261983,"owners_count":21074229,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["json-schema","typescript"],"created_at":"2025-01-19T04:10:58.614Z","updated_at":"2025-04-10T17:29:16.254Z","avatar_url":"https://github.com/s1seven.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Schema-tools\n\n[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)\n[![Schema-tools CI](https://github.com/s1seven/schema-tools/actions/workflows/node.yml/badge.svg)](https://github.com/s1seven/schema-tools/actions/workflows/node.yml)\n[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=s1seven_schema-tools\u0026metric=coverage)](https://sonarcloud.io/summary/new_code?id=s1seven_schema-tools)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=s1seven_schema-tools\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=s1seven_schema-tools)\n[![FOSSA Status](https://app.fossa.com/api/projects/custom%2B18065%2Fgithub.com%2Fs1seven%2Fschema-tools.svg?type=shield)](https://app.fossa.com/projects/custom%2B18065%2Fgithub.com%2Fs1seven%2Fschema-tools?ref=badge_shield)\n\nThis repository contains a suite of components and modules to handle certificates and schemas.\nThe specification of these libraries can be found in [SEP](https://s1seven.github.io/SEP/schemas/).\n\n## Supported Schemas\n\n| Name      | Version range |\n| --------- | :-----------: |\n| [EN10168] | 0.0.2 - 0.4.x |\n| [E-CoC]   |     1.0.0     |\n| [CoA]     | 0.0.3 - 1.x.x |\n| [CDN]     |      xx       |\n\n### Deprecations\n\nE-CoC v0.0.2 has been deprecated.\n\n## List of packages\n\n- [Certificate-Model](https://github.com/s1seven/schema-tools/tree/master/packages/certificate-model#readme)\n  The certificate-model module provides a class using template pattern to generate a class / instances based a given JSON schema.\n\n- [Certificate-Summary](https://github.com/s1seven/schema-tools/blob/main/packages/certificate-summary/README.md)\n  Build certificate summary by retrieving general common properties.\n\n- [Extract-Emails](https://github.com/s1seven/schema-tools/tree/master/packages/extract-emails#readme)\n  This repository contains tools to extract information (emails, VAT, ...) about parties included in certificate(s).\n\n- [Generate-CoA-PDF-Template](https://github.com/s1seven/schema-tools/blob/main/packages/generate-coa-pdf-template/README.md)\n  This package provides a minified script to be used in CoA-schemas specific verison release.\n\n- [Generate-EN10168-PDF-Template](https://github.com/s1seven/schema-tools/blob/main/packages/generate-en10168-pdf-template/README.md)\n  This package provides a minified script to be used in EN10168-schemas specific verison release.\n\n- [Generate-HTML](https://github.com/s1seven/schema-tools/tree/master/packages/generate-html#readme)\n  The generate-html module uses handlebars to generate HTML string using a certificate using a supported JSON schema.\n\n- [Generate-Interfaces](https://github.com/s1seven/schema-tools/tree/master/packages/generate-interfaces#readme)\n  The generate-interfaces module is using the json-schema-to-typescript package to generate TS interfaces and types using a JSON / OpenAPI schema.\n\n- [Generate-PDF](https://github.com/s1seven/schema-tools/tree/master/packages/generate-pdf#readme)\n  The generate-pdf module uses pdfmake to generate PDF buffer | stream from a certificate as JSON or HTML.\n\n- [Types](https://github.com/s1seven/schema-tools/tree/master/packages/types#readme)\n  Contains shared types. Uses duck typing / type guards for quick validation. To be updated every time the schema is updated.\n\n- [Utils](https://github.com/s1seven/schema-tools/tree/master/packages/utils#readme)\n  internal utilities including static resources caching.\n\n- [Validate](https://github.com/s1seven/schema-tools/tree/master/packages/validate#readme)\n  Takes certificates as input and validates them by using the referenced JSON schema.\n\n- [Versioning](https://github.com/s1seven/schema-tools/blob/main/packages/versioning/README.md)\n  Update all files containing versioning during release, to be used within schemas repositories.\n\n## Dependency graph\n\n![dependency graph](./graph.png)\n\n## Contributing\n\nWhen updating the schema (links below), the tools need to be updated at the same time.\n\nSchema links:\n\n- [EN10168]\n- [E-CoC]\n- [CoA]\n- [CDN]\n\nProcess:\n\n1. Update the schema in question\n2. Check and update the types using the `create-schema-interfaces` CLI tool\n3. 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`.\n   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 - https://github.com/s1seven/schema-tools/pull/147\n4. For a new Release Candidate, add a new fixture (used for testing) using the method outlined [below:](#fixtures)\n\n## Starting out\n\nTo get started, run :\n\n```sh\nnpm install\nnpm run build\n```\n\nMake sure you have installed ImageMagick and GhostScript on your system. This is required for testing the PDF generation.\n\n```sh\n# MacOS\nbrew install graphicsmagick\nbrew install ghostscript\n# Linux\nsudo apt-get install graphicsmagick\nsudo apt-get install ghostscript\n```\n\n## Development\n\nWhen 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.\n\n```sh\nnpm run build\nnpm install\n```\n\n## Testing\n\nThe following packages only test the compatibility with the latest schema version:\n\n- generate-coa-pdf-template\n- generate-en10168-pdf-template\n\nThe remaining packages should be made compatible with [all schema versions](#supported-schemas)\n\n### Fixtures\n\n- Create or use a folder following the schema name\n- ⚠️ Create a subfolder following the version of the release candidate\n- Add a valid json certificate with the name `valid_cert.json`\n- Add an invalid json certificate with the name `invalid_cert.json`\n- Add the `translations.json` - for ease of use we keep English and German translations in a single file\n- Add the `extraTranslations.json` if necessary (for use with CoA) - for ease of use we keep English and German translations in a single file\n- Add a copy of the `template.hbs` from the schema repo (for use with the local rendering tests until the version is released)\n- `certificate.ts`, `schemaTypes.ts`, `template_hbs.html` and `valid_cert.pdf` should be dynamically generated using the following scripts:\n\n#### Typescript interface\n\nTo generate `certificate.ts` (json-schema converted to Typescript interfaces),from the root directory, run the following command, updating the version number and schema name :\n\n```sh\nnpm run fixtures:interfaces -- -s ../CoA-schemas/schema.json -o fixtures/CoA/v0.2.0/certificate.ts\n```\n\nwhere -s indicates the path to the updated schema and -o indicates the path to the certificate to be generated.\n\n#### schemaTypes.ts\n\n`generate-\u003cen10168/coa\u003e-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:\n\n```sh\nnpm run fixtures:interfaces -- -s ../CoA-schemas/schema.json -o packages/generate-coa-pdf-template/src/types/schemaTypes.ts\n```\n\n#### HTML certificate\n\nTo 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 :\n\n```sh\nnpm 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\n```\n\nFor EN10168\n\n```sh\nnpm 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\n```\n\nIf external translations are not needed, remove the `-e` command from the above command.\nIf partial maps are not needed, remove the `-p` command from the above command.\n\nIf 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`.\n\n#### PDF certificate\n\nTo 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 :\n\n```sh\nnpm 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\n\n# or using remote resources\nnpm 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'\n```\n\nEN10168\n\n```sh\nnpm 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\n```\n\nIf external translations are not needed, remove the `-e` command from the above command.\n\n##### Troubleshooting PDF tests\n\nIf 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`.\n\n## PDF Generation - Making changes to a PDF\n\nTo 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.\n\n[en10168]: https://github.com/material-identity/EN10168-schemas\n[e-coc]: https://github.com/material-identity/E-CoC-schemas\n[coa]: https://github.com/material-identity/CoA-schemas\n[cdn]: https://github.com/material-identity/CDN-schemas\n\n## Tests to update for new releases\n\nWhen creating a new release, the following tests need to be updated with the latest version (usually in a `testSuitesMap` or `testMap` array):\n\n- generate-\u003cschema\u003e-pdf-template\n- generate-pdf\n- generate-html\n- certificate-summary\n- extract-emails\n- generate-interfaces\n\n## Creating new releases\n\nTo first see what will be released, run `nx release --dry-run`.\n\nNote: 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.\n\nTo release new versions of the schema-tools packages, run `GITHUB_TOKEN=\u003ctoken\u003e nx release`. This will automatically bump package version numbers, generate changelogs, create github releases and release on npm.\n\n## License\n\n[![FOSSA Status](https://app.fossa.com/api/projects/custom%2B18065%2Fgithub.com%2Fs1seven%2Fschema-tools.svg?type=large)](https://app.fossa.com/projects/custom%2B18065%2Fgithub.com%2Fs1seven%2Fschema-tools?ref=badge_large)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fs1seven%2Fschema-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fs1seven%2Fschema-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fs1seven%2Fschema-tools/lists"}