# NAME **jmc** - JSON Model Compiler # SYNOPSIS jmc [--help] [--version] [--man] [--debug] [--verbose] [--quiet] [plenty other options] [--op {P,U,J,N,E,C} | --preproc | --dump | --jdump | --nope | --export | --compile] [--output OUTPUT] (--model MODEL | MODEL) [VALUES ...] # DESCRIPTION The JSON Model Compiler command processes a [JSON Model](https://json-model.org/) to generate modules or scripts in C, JS, Python, PL/pgSQL, Perl, or a more-or-less equivalent JSON Schema, pydantic, or TypeScript type declarations. # ARGUMENTS - **model** Model to process, a local file or a URL. - **values...** List of value files to check. # OPTIONS Here are the most useful options: ## Metadata - **--help**/**-h** Show auto-generated synopsis and exit. - **--version** Show command version and exit. - **--doc {pod,syn,help,man}** Show help in some format and exit. - **--man** Show man page and exit. ## Verbosity - **--verbose**/**-v** Set verbose mode. - **--quiet** Set quiet mode, only show warnings. - **--debug** Set debug mode, which is very verbose. ## Input - **--model MODEL"** Provide the mode with an option instead of a parameter. - **--maps "URL PATH"**/**-m …** Map remote urls to a local path. Can also use `=` as a separator. - **--auto**/**-a** Infer url to path mapping from declared model URL (`.$.""`). - **--check** Whether to check the model for errors at various stages. - **--allow-duplicates** Accept JSON with objects containing duplicated properties. - **--extend** Allow some extensions to help with JSU back-end implementation. - **--from-ir**/**-fir** Read a JSON intermediate representation, as generated with `-C -F json`, instead of a JSON model, so that only code generation (`-C`) is available. The entry name and package are taken from the IR, and reporting must have been enabled when it was generated. An IR generated with `-F json` targets a generic back-end: the regenerated code may differ from a direct compilation, and PL/pgSQL is not supported. Pass the tuning options when generating the IR for a closer match. ## Processing - **--op {P,E,C,U,J,N}** Operation to run (preprocessing, export, compile, dump, jdump, none). - **--{loose,strict}-{int,float,number}** **--loose** Whether to assume loose JSON numbers, i.e. accept _42.0_ as an integer or _42_ as a float. Default is strict, but JS, PL/pgSQL and Perl backends are always loose due to the language and type capabilities. - **--re RELIB** Regular expression library to use, default is to use **re2** when available, else the internal library. - **--optimize**/**-O** Whether to optimize the model (partial eval, constraint simplifications, flattening, or-inlining, dead code elimination, xor to or conversion…). - **--no-opt** OPTIM Whether to disable specific preprocessing optimizations: `srx`, `csp`, `sim`, `flt`, `pev`, `ans`, `aco`, `x2o`, `non`. ## Output - **--output FILE**/**-o FILE** Output file, the suffix of which is used for setting the default format and generation. - **--format FMT**/**-F FMT** Output language, to override defaults. - **--gen GEN** Whether to generate an **exec**utable, a **module**, source **code** or nothing **none**, to overide defaults. - **--entry ENTRY** Name of the entry function to generate. - **--package PKG** Name of package for generated module, if appliable. - **--mark COMMENT** Add comment to generated source file. ## Code Generation Optimizations - **--map-threshold THRESHOLD** Maximum number of props to inline property checks in objects. - **--map-share** Whether to share common maps, may result in smaller generated code. - **--may-must-open-threshold THRESHOLD** Consider mmo object property scheme if the number of optional properties is below the provided threshold, default is depends on target. - **--must-only-threshold THRESHOLD** Consider must-only object property scheme if the number of mandatory properties is below the provided threshold, default depends on target. - **--partition-threshold THRESHOLD** Number of properties to trigger partitioning inlined property checks, default depends on target, 0 means no partitioning. - **--or-must-prop THRESHOLD** Shortcut or-list based on full or partial discriminating mandatory properties if length above threshold, default depends on target, 0 to disable. - **--sort-must** **--no-sort-must** **--sort-may** **--no-sort-may** Whether to sort must or may properties when checks are unrolled, default is to preserve the initial order within each category. - **--predef** **--no-predef** Whether to check value contents wrt predef declarations. - **--single-line-regex** **--no-single-line-regex** Whether to assume that regex are implicitely single line (`s` option). - **--regex-pattern** **--no-regex-pattern** Whether to optimize some regex pattern for starts with, ends with or equality. - **--call-shortcut** **--no-call-shortcut** Whether to shortcut function calls when possible. - **--array-unrolling-size SIZE** Maximum size of simple array unrolling. - **--disjunction** **--no-disjunction** Whether to try to detect disjunctions, aka discriminating properties. - **--all-but-one** **--no-all-but-one** Whether to detect and simplify all but one type checks. - **missing-basics** **--no-missing-basics** Whether to detect type checks with few missing basics. - **xor-repeats** **--no-xor-repeats** Whether to extract repeated models inside a xor. - **xor-is-not** **--no-xor-is-not** Whether to detect a xor which is a not (any or str). - **homogeneous-list** **--no-homogeneous-list** Whether to factor out type check on homogeneous or/and lists. ## C Compilation - **--cc COMPILER** Compiler to use, defaut is `cc`. - **--{cpp,c,ld}flags ...** Set raw `cpp`, `cc` or `ld` flags. - **-I DIR** **-D VAR=VAL** Add `cpp` include path and definitions. - **-L DIR** Add to `ld` link path. - **--static** Generate a statically linked executable. - **--inline** **--no-inline** Generate inline hints. - **--strcmp-optimize** **--no-strcmp-optimize** Whether to optimize string comparisons in some cases. - **--max-strcmp-cset SIZE** Maximum size for string constant set expansion. - **--byte-order ORDER** Set byte order for string comparison, either `le` (little endian) or `be` (big endian). - **--regex-optimize** **--no-regex-optimize** Whether to optimize regex when possible. - **--unique-optimize** **--no-unique-optimize** Whether to use type-specific uniticy check runtime functions. - **--precompiled** **--no-precompiled** Whether to use precompiled runtime. Beware that the precompiled runtime depends either on `re2` or `pcre2`, so the regex engine cannot be changed. ## Java Compilation - **--javac JAVAC** Java compiler. - **--jflags JFLAGS** Java compiler flags. ## JSON Schema Export - **-\[-no\]-schema-version** Whether to force include/not include JSON Schema version. ## Testing When testing values: - **--name NAME**/**-n NAME** Name of model to use, default is empty string for the root model. - **--test-vector** Assume a test vector input format for tested values. - **--none**/**--true**/**--false** Expected result of test values, return an error status if unexpected values are encountered. - **--report** Generate a report about why a value failed. Default is just to say PASS or FAIL. Note that environment variable `JMC_OPTS` is also processed for preliminary options. # OPERATIONS This section describes the main operations implemented by the compiler: ## Preprocessing The optimized proprocessed JSON Model is shown with `-P -o preprocessed.json`. ## Compilation The compiler can generate code to actualy validate JSON data as: - **native** C source (`-o model.c`), object file (`-o model.o`) or compiled executable (`-o model.out`); - **byte-code** Java source (`-o model.java`) or compiled class (`-o model.class`); - **scripts** Python (`-o model.py`), JavaScript (`-o model.js`) or Perl (`-o model.pl`); - **modules** Python (`-o model.py --module`), JavaScript (`-o model.mjs`), Perl (`-o model.pm`), PL/pgSQL (`-o model.sql`), Java (`-o model.java`) ready to be imported and used in the corresponding language. ## Export The compiler can export models to other data type declaration formats: - **JSON Schema** Formatted in JSON (`-E -o schema.json`) or yaml (`-E -o schema.yaml`). - **Python Pydantic** Generate classes and types with `-E -o Models.py`). - **TypeScript** Generate TypeScript `interface`/`type` declarations with `-E -F ts -o Model.ts`. # AUTHORS Fabien Coelho (Mines Paris - PSL) and Claire Yannou-Medrala (MESR). # COPYRIGHT This software is dedicated to the public domain. # SEE ALSO - [JSON Model Web Site](https://json-model.org/) Including [JSON Model Tutorial](https://json-model.org/#/TUTO), [JSON Model HOWTO](https://json-model.org/#/HOWTO), [JSON Model Specification](https://json-model.org/#/SPEC), and [JSON Model illustrative models](https://json-model.org/#/MODELS). - [JSON Model Sources](https://github.com/clairey-zx81/json-model) Source code on GitHub. - [JSON Model Issues](https://github.com/clairey-zx81/json-model/issues) Report bugs on GitHub.