{"id":25811,"library":"jsonix-schema-compiler","title":"Jsonix Schema Compiler","description":"Jsonix Schema Compiler is a Java-based tool that generates Jsonix mappings and JSON Schema definitions from XML Schema (XSD) files. Version 2.3.9 is the latest stable release, with active but infrequent updates. It is a companion to the Jsonix library for XML-JSON conversion. Key differentiators: handles complex XML Schema features like enums, minOccurs/maxOccurs, xs:duration, and built-in type detection. Requires Java runtime to run, integrates via Java JAR or Maven plugin. Unlike pure JavaScript alternatives, it provides full XSD compliance. Does not support XML Schema 1.1 and has no TypeScript type generation.","status":"maintenance","version":"2.3.9","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/highsource/jsonix-schema-compiler","tags":["javascript","json","xml","unmarshal","unmarshalling","marshal","marshalling","parse","parsing"],"install":[{"cmd":"npm install jsonix-schema-compiler","lang":"bash","label":"npm"},{"cmd":"yarn add jsonix-schema-compiler","lang":"bash","label":"yarn"},{"cmd":"pnpm add jsonix-schema-compiler","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime dependency for consuming generated mappings","package":"jsonix","optional":false},{"reason":"Required to execute the compiler JAR","package":"java","optional":false}],"imports":[{"note":"Jsonix itself is ESM-compatible; this is for consuming generated mappings.","wrong":"const Default = require('jsonix')","symbol":"Default","correct":"import { Default } from 'jsonix'"},{"note":"Named export from jsonix.","wrong":"const Marshaller = require('jsonix').Marshaller","symbol":"Marshaller","correct":"import { Marshaller } from 'jsonix'"},{"note":"Named export from jsonix.","wrong":"const Unmarshaller = require('jsonix').Unmarshaller","symbol":"Unmarshaller","correct":"import { Unmarshaller } from 'jsonix'"},{"note":"This package provides a JAR, not a JS module. Do not attempt to import JavaScript symbols from it.","wrong":"import { compile } from 'jsonix-schema-compiler'","symbol":"compile","correct":"// not a JS import; use CLI: java -jar jsonix-schema-compiler-full.jar"}],"quickstart":{"code":"// First, install jsonix-schema-compiler and jsonix\n// npm install jsonix-schema-compiler jsonix\n// Then in package.json scripts:\n{\n  \"scripts\": {\n    \"prepublish\": \"java -jar node_modules/jsonix-schema-compiler/lib/jsonix-schema-compiler-full.jar schema.xsd\"\n  }\n}\n// Run npm run prepublish to generate mapping file jsonschema.js\n// Then in your code:\nimport { Default, Marshaller, Unmarshaller } from 'jsonix';\nimport { MyMapping } from './mapping/MyMapping.js';\n\nconst context = new Default([ MyMapping ]);\nconst marshaller = new Marshaller(context);\nconst unmarshaller = new Unmarshaller(context);\n\n// Example: marshal an object to XML\nconst obj = { name: 'John', age: 30 };\nconst xml = marshaller.marshalString(obj);\nconsole.log(xml);\n\n// Example: unmarshal XML string\nconst result = unmarshaller.unmarshalString(xml);\nconsole.log(result);","lang":"typescript","description":"Shows how to use the compiler via npm prepublish and then use generated mappings with Jsonix for XML marshalling/unmarshalling."},"warnings":[{"fix":"Use the CLI command `java -jar node_modules/jsonix-schema-compiler/lib/jsonix-schema-compiler-full.jar`. Do not expect to import anything from this package in JavaScript.","message":"This package is a Java JAR, not a JavaScript module. Installing via npm does not provide a JavaScript API; you must invoke the JAR via command line or Java API.","severity":"gotcha","affected_versions":"all"},{"fix":"Change scripts from `prepublish` to `prepare` in package.json.","message":"Usage of npm `prepublish` script is considered an antipattern. Since npm v5, `prepublish` runs on both `npm install` and `npm publish`, causing unintended generation. Use `prepare` instead.","severity":"deprecated","affected_versions":">=2.3.2"},{"fix":"Ensure Java 8+ is installed and available in PATH.","message":"Java Runtime Environment (JRE) is required to run the compiler. Node.js only, without Java, will fail.","severity":"gotcha","affected_versions":"all"},{"fix":"Regenerate mappings after upgrading to 2.3.7+ and use compatible Jsonix version.","message":"Version 2.3.7 introduced `required`, `minOccurs`, and `maxOccurs` in generated mappings. Mappings generated with older versions may produce different output when used with a newer Jsonix runtime.","severity":"breaking","affected_versions":">=2.3.7"},{"fix":"Check the actual JAR file in `node_modules/jsonix-schema-compiler/lib/` after install and adjust command accordingly.","message":"The compiler JAR filename has changed across versions. Some versions use `jsonix-schema-compiler-full.jar`, others may have different names.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Verify that jsonix-schema-compiler is installed and the JAR exists. Check exact filename in lib/ directory.","cause":"JAR file not found or path incorrect.","error":"Error: Unable to access jarfile node_modules/jsonix-schema-compiler/lib/jsonix-schema-compiler-full.jar"},{"fix":"Use the correct JAR file: `jsonix-schema-compiler-full.jar` which is an executable JAR. Do not invoke without -jar.","cause":"Running an older version of the JAR or incorrect invocation without main class.","error":"Error: Could not find or load main class org.jvnet.jaxb2_commons.xjc.XJCTask"},{"fix":"Ensure the generated mapping file path matches the import statement. The compiler outputs to a 'mapping' directory by default.","cause":"Generated mapping file is not imported or path is wrong.","error":"ReferenceError: MyMapping is not defined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}