CJM v0.5.0

CJM v0.5.0 Release Notes

CJM v0.5.0 adds the first JSON Schema backend.

The release keeps C++ models as the source of truth. Users still write ordinary
C++ headers with CJM JSON metadata; CJM builds Metadata IR and can now emit both
generated nlohmann/json C++ integration and JSON Schema artifacts for the
supported mapping surface.

This release does not make CJM a schema-first generator, OpenAPI framework,
runtime validator, or cross-language code generator.

Highlights

• Adds a JSON Schema Draft 2020-12 backend that consumes Metadata IR
• Adds golden tests for primitive, array, optional, map, enum, nested object, and
  composed schema output
• Preserves std::array<T, N> extent in Metadata IR for schema generation
• Adds cjm generate-schema --input <header> --output <file>
• Wires schema generation into cjm_generate(...) through opt-in
  GENERATE_SCHEMAS
• Keeps C++ headers under generated/cjm
• Keeps schema artifacts under generated/schemas
• Exposes generated schema paths through GENERATED_SCHEMAS_VAR
• Keeps existing cjm generate and default CMake header generation compatible

CLI Workflow

Generate the normal C++ integration header:

cjm generate \
  --input user.hpp \
  --output user.cjm.hpp

Generate a JSON Schema artifact:

cjm generate-schema \
  --input user.hpp \
  --output user.schema.json

Both commands use the same parser and Semantic Analysis pipeline. Schema output
is generated from validated Metadata IR.

CMake Workflow

Existing CMake calls continue to generate only C++ headers:

cjm_generate(
  TARGET app
  HEADERS user.hpp
)

Schema generation is opt-in:

cjm_generate(
  TARGET app
  HEADERS user.hpp
  GENERATED_TARGET app_cjm_generated
  GENERATE_SCHEMAS
  GENERATED_SCHEMAS_VAR app_cjm_schemas
)

For user.hpp, the current CMake layout is:

<build-dir>/generated/cjm/user.cjm.hpp
<build-dir>/generated/schemas/user.schema.json

Schema files are build artifacts. They are tracked by the generated target, but
they are not added as C++ sources and are not added to the generated include
directory.

Schema Coverage

Implemented schema mappings:

• object schemas for supported generated structs
• bool
• signed and unsigned integers
• common fixed-width integer spellings
• floating-point types
• std::string
• unsigned integers with minimum: 0
• std::vector<T> and std::array<T, N> when T is a scalar or string mapping
• std::optional<T> when T is a scalar or string mapping
• std::map<std::string, T> and std::unordered_map<std::string, T> when T
  is a scalar or string mapping
• enum and enum class fields as JSON string enums
• direct generated-struct fields through $ref and $defs
• json:"-" fields omitted from schema properties
• non-optional supported fields listed in required

Known Limitations

Not yet supported:

• schema output for nested containers
• schema output for containers whose element or value type is an enum or
  generated struct
• schema output for std::optional<T> when T is an enum, generated struct, or
  container
• custom enum string mapping policies
• custom converters
• default-value metadata
• time and datetime schema formats
• OpenAPI route generation
• HTTP endpoint policy
• runtime JSON Schema validation
• arbitrary JSON values
• std::variant
• std::any
• pointer fields
• polymorphism
• automatic header discovery
• full C++ grammar support at the CJM product level
• multiline managed field declarations are not yet documented as supported
• private fields
• native JSON backend
• install/package distribution

Verification

The v0.5 branch was verified locally with:

cmake --build build
ctest --test-dir build --output-on-failure

Expected result:

100% tests passed, 0 tests failed out of 30

Coverage includes:

• schema backend golden tests
• CLI schema generation tests
• CMake schema artifact tests
• existing nlohmann backend tests
• contract backend tests
• parser and semantic tests
• generated compile tests
• basic example build/run tests

Tag

Release tag:

v0.5.0