Schemas Service

System Requirements

• Java version: 21

Install packages

From root directory, run:

chmod +x copy-resources.sh && \
mvn clean install

Compile

mvn compile

curl -X POST 'http://localhost:8081/render?schemaType=CoA&schemaVersion=1.0' \
     -H 'Content-Type: application/json' \
     -d '{"key":"value", "anotherKey": {"nestedKey":"nestedValue"}}'

Start the service

mvn exec:java -Dexec.mainClass="com.materialidentity.schemaservice.App"

Run the jar

java -jar target/schema-service-1.0-SNAPSHOT.jar

Watch

mvn spring-boot:run

Run tests

mvn test

UI

To use the UI to interact with the service, run command:

cd ui && npm install
npm start

Standalone PDF Generation

Prerequisites

Before using the standalone PDF generation, you must build the project:

# Install dependencies and build the project
chmod +x copy-resources.sh && mvn clean install

This compiles the Java classes and copies all dependencies to the target/ directory.

Important: If you get a NoClassDefFoundError or similar error, ensure dependencies are copied:

mvn dependency:copy-dependencies -DoutputDirectory=target/dependency

Single Certificate Conversion

node scripts/json2pdf.js <input-file> [output-file]

The script automatically detects the schema type and version from the certificate. By default, it saves the PDF in the same directory as the input JSON file with the same name but .pdf extension.

Examples:

# Convert single certificate (output to same directory)
node scripts/json2pdf.js test/fixtures/EN10168/v0.4.1/valid_certificate_2.json
# Output: test/fixtures/EN10168/v0.4.1/valid_certificate_2.pdf

# Convert with custom output path
node scripts/json2pdf.js test/fixtures/EN10168/v0.4.1/valid_certificate_2.json output/custom.pdf

# Using npm script
npm run json2pdf -- certificate.json output.pdf

Development Mode - Custom XSLT

For development and testing, you can provide a custom XSLT file path to override the default compiled XSLT:

# Use custom XSLT file for development
node scripts/json2pdf.js certificate.json --xsltPath ./schemas/EN10168/v0.5.0/stylesheet.xsl

# With input/output flags
node scripts/json2pdf.js --input cert.json --output result.pdf --xsltPath custom.xsl

This feature is particularly useful when developing or modifying XSLT stylesheets, as it allows you to test changes without rebuilding the entire project.

Batch Processing

# Process all test fixtures
npm run render-all-pdf

This processes all JSON certificates in the test/fixtures/ directory and outputs PDFs to the tmp/ directory with comprehensive statistics.

OpenAPI / Swagger

http://localhost:8081/api-docs http://localhost:8081/swagger-ui/index.html

Working with Schemas

All schemas, certificates, stylesheets and fixtures can be found in the ./schemas folder. The filepath convention is as follows: ./schemas/<schema-type>/<version>/.

If you are a part of S1EVEN team and would like to test the app with private schemas, log in to dotenv using npx dotenv-vault login and pull using npx dotenv-vault@latest pull to get environment variables for running the script. This will run the copy-from-s3bucket script which will pull all private schemas and fixtures. To add a new version, create a new folder with the version as the name. When the schemas-service app is built, the script copy-resources.sh will be run automatically and will copy across the needed stylesheet.xsl and translations.json files.

The file schema.json is obligatory, and for PDF validation valid stylesheet.xsl and translations.json files.

Rendering text fixtures should be added using the same file structure in the fixtures folder. Any valid_certificate_*.json files will be rendered and the result checked against the corresponding valid_certificate_*.pdf file.

Converting JSON to .XML

Purpose

The creation of a PDF from JSON is based on Apache FOP. The steps are:

1. JSON to XML Transformation

   The JSON is transformed to XML

2. XML + XSLT to FO Transformation

   The XSLT found next to the corresponding schema.json is applied to the XML from step 1. The output is a XSL-FO document.

3. FO to PDF Transformation

   An Apache FOP processes the XSL-FO to create the PDF.

The script generates the XML output of step 1.

Usage

npm run json2xml <relative filepath to schema>

Example:

npm run json2xml test/fixtures/CoA/v1.1.0/valid_certificate_1.json

It will save the resulting file to the same directory as the original .json file.

Security & Compliance

Vulnerability Scanning

This project uses Grype for automated vulnerability scanning to ensure compliance with the EU Cyber Resilience Act (CRA). Vulnerability scans run automatically on:

• Every pull request
• Every push to main
• Weekly schedule (Mondays at 9 AM UTC)

Severity Threshold: Builds fail on medium severity or higher vulnerabilities.

Viewing Results:

• Navigate to the Security tab to view vulnerability reports
• Vulnerability reports are also available as workflow artifacts

Configuration: See .grype.yaml for scan configuration and ignore rules.

Software Bill of Materials (SBOM)

In compliance with the EU Cyber Resilience Act, we automatically generate Software Bill of Materials (SBOM) for each release using Syft.

Accessing SBOMs:

• GitHub Releases: SBOM files are attached to each release as assets
• Repository: Version-tagged SBOMs are stored in the sbom/ directory
• Formats: Both SPDX (ISO/IEC 5962) and CycloneDX (OWASP) formats are provided

SBOM Contents:

• Complete inventory of all dependencies (direct and transitive)
• Component metadata (names, versions, licenses, suppliers)
• Dependency relationships and hierarchy
• Package checksums for integrity verification

For more information, see the SBOM documentation.

Configuration: See .syft.yaml for SBOM generation configuration.

Manual Security Operations

Run vulnerability scan locally:

# Install Grype
curl -sSfL https://raw.githubusercontent.com/anchore/grype/main/install.sh | sh -s -- -b /usr/local/bin

# Scan project
grype .

Generate SBOM locally:

# Install Syft
curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b /usr/local/bin

# Generate SPDX format
syft . -o spdx-json --file sbom-spdx.json

# Generate CycloneDX format
syft . -o cyclonedx-json --file sbom-cyclonedx.json

Reporting Security Issues

Please report security vulnerabilities by opening a security advisory or contacting the security team directly.