feat: manually generated json-schema with validation

[9pace]

Fixes #

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

[kaizencc]

🐝

[kaizencc]

🐝

[kaizencc]

🐝

[kaizencc]

🐝

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[we-are-the-hive]

🐝 buzz

[kaizencc]

🐝

[we-are-the-hive]

🐝 buzz

[kaizencc]

🐝

[we-are-the-hive]

🐝 buzz

[kaizencc]

🐝 is there a better way to do this

[kaizencc]

🐝 is there a better way to do this

[kaizencc]

🐝 is there a better way to do this

[kaizencc]

🐝 is there a better way to do this

[kaizencc]

🐝 what do you think? is there a better way to do this

[we-are-the-hive]

🐝 The Hive Has Spoken

Question: "what do you think? is there a better way to do this"

Options considered:

• Manual JSON Schema — Keep the current approach of manually maintaining a JSON schema file with validation logic. This provides full control over schema structure and validation messages, and the schema can be versioned alongside the codebase. It's straightforward to understand and doesn't require additional build tooling.
• TypeScript-to-Schema Generation — Use libraries like typescript-json-schema or ts-json-schema-generator to automatically generate the JSON schema from TypeScript interfaces. Define the configuration types in TypeScript and generate the schema as a build step, ensuring type definitions and schema stay synchronized.
• Zod Schema as Source of Truth — Define configuration using Zod schemas which provide both runtime validation and TypeScript type inference. Use zod-to-json-schema to generate JSON schema for IDE support and documentation. This keeps validation logic, types, and schema in a single source of truth with excellent error messages.
• JSON Schema with Ajv Compilation — Use the manual JSON schema but leverage Ajv's standalone code generation to compile the schema into optimized JavaScript validation code at build time. This provides fast runtime validation without parsing the schema at startup and enables better error formatting.
• TypeBox Schema Definition — Use TypeBox to define schemas that simultaneously generate JSON Schema and TypeScript types from a single definition. TypeBox schemas are JSON Schema compliant at runtime, eliminating the generation step while maintaining type safety. Validation can use Ajv directly with the TypeBox schemas.

Winner: Zod Schema as Source of Truth (1 round)

The hive chose Zod Schema as Source of Truth because it eliminates the maintenance burden of keeping separate JSON schema and TypeScript types in sync, while providing runtime validation, automatic type inference, and the ability to generate JSON schema on demand—all from a single authoritative source.

Debate details

Round 1: Zod Schema as Source of Truth(3) · Manual JSON Schema(1) · TypeScript-to-Schema Generation(0) · JSON Schema with Ajv Compilation(0) · TypeBox Schema Definition(0)

[kaizencc]

🐝 what do you think? is there a better way to do this

[we-are-the-hive]

🐝 The Hive Has Spoken

Question: "what do you think? is there a better way to do this"

Options considered:

• Manual JSON Schema — Keep the current approach of a hand-crafted JSON schema file with validation logic in user-configuration.ts. This gives full control over the schema structure, custom error messages, and allows incremental additions without tooling dependencies. Validation is performed at config load time using a standard JSON Schema validator like ajv.
• TypeScript-Generated Schema — Define the configuration as TypeScript interfaces/types and use a tool like ts-json-schema-generator or zod-to-json-schema to auto-generate the JSON schema from the source of truth. The generated schema is committed or produced at build time and used for runtime validation. This ensures the schema always matches the TypeScript types developers already maintain.
• Zod Runtime Validation — Replace the JSON schema with Zod schemas defined in TypeScript that serve as both the type definition and the runtime validator. Zod provides excellent error messages, composability, and TypeScript type inference without needing a separate schema file. The .toJsonSchema() export can still produce a JSON schema for IDE autocompletion if needed.
• Projen Schema Integration — Leverage projen's existing configuration management to generate and validate the schema as part of the project synthesis step. Define config shape in .projenrc.ts and have projen produce both the schema JSON and TypeScript validation code during npx projen, treating the schema as a managed project artifact rather than manually authored code.
• JSON Schema from JSII — Since CDK already uses JSII for cross-language type information, extract the configuration interface from the JSII assembly or use the existing type model to generate the JSON schema automatically. This reuses the project's existing type reflection infrastructure and ensures config types stay aligned with the public API surface.

Winner: Zod Runtime Validation (1 round)

The hive chose Zod runtime validation because it allows defining the schema once in code and deriving both the JSON schema and TypeScript types from it, eliminating the maintenance burden of keeping a manually written JSON schema in sync with the validation logic and type definitions.

Debate details

Round 1: Zod Runtime Validation(9) · TypeScript-Generated Schema(3) · Projen Schema Integration(1) · Manual JSON Schema(0) · JSON Schema from JSII(0)

[kaizencc]

🐝 what do you think? is there a better way to do thi

[we-are-the-hive]

🐝 The Hive Has Spoken

Question: "what do you think? is there a better way to do thi"

Options considered:

• Manual JSON Schema — Keep the current approach of a hand-crafted JSON Schema file checked into the repository with manual validation logic. This gives full control over the schema shape, custom error messages, and allows incremental additions without tooling dependencies. Validation is implemented directly using a library like ajv against the static schema file.
• TypeScript-Generated Schema — Use a tool like ts-json-schema-generator or typescript-json-schema to automatically derive the JSON Schema from TypeScript interfaces/types that define the CDK config structure. The schema generation becomes a build step, ensuring the schema always reflects the actual type definitions. Validation still uses ajv or similar at runtime.
• Zod Runtime Validation — Define the config schema using Zod, which provides both runtime validation and TypeScript type inference from a single source of truth. Zod schemas can be exported as JSON Schema via zod-to-json-schema for IDE autocompletion, while the runtime validation provides rich, structured error messages out of the box.
• JSON Schema with Codegen — Treat the JSON Schema as the canonical source and use json-schema-to-typescript (or similar) to generate TypeScript interfaces from it. This inverts the typical flow—schema-first design ensures the validation contract is always authoritative, and generated types keep code in sync. The schema file remains manually authored but is the single source of truth.
• Projen Structured Config — Leverage projen's existing configuration management patterns to define the CDK config schema declaratively within .projenrc.ts, generating both the JSON Schema and validation code as synthesized project artifacts. This keeps schema management consistent with how the rest of the monorepo handles generated files and ensures the schema is always regenerated on npx projen.

Winner: Zod Runtime Validation (1 round)

The hive chose Zod runtime validation because it provides type-safe schema definition with automatic TypeScript type inference, eliminates the need to manually maintain a separate JSON schema file, and offers robust runtime validation with clear error messages—all while being a well-established library that reduces the risk of the hand-written schema drifting out of sync with the actual configuration interface.

Debate details

Round 1: Zod Runtime Validation(7) · JSON Schema with Codegen(3) · Projen Structured Config(2) · TypeScript-Generated Schema(1) · Manual JSON Schema(0)

[we-are-the-hive]

🐝 The Hive Has Spoken

Question: "should we use DynamoDB or PostgreSQL?"

Options considered:

• Neither - File-Based Schema — The PR is about JSON schema validation for CDK configuration files, which are local filesystem artifacts. No database is needed as the schema is bundled with the package and validation happens at CLI runtime against local cdk.json files. This is the architecturally correct approach given the actual context.
• DynamoDB for Schema Registry — If future requirements include a centralized schema registry for versioned schemas across deployments, DynamoDB could store schema versions with partition key on schema-name and sort key on version. This enables schema evolution tracking and cross-team schema sharing with low-latency lookups.
• PostgreSQL for Schema Analytics — If there's a need to analyze validation failures across enterprise CDK deployments, PostgreSQL with JSONB columns could store validation telemetry and enable complex queries on failure patterns. This supports aggregate reporting on which schema violations are most common.
• S3 with CloudFront — For distributing schema updates independently of CLI releases, host the JSON schema in S3 with CloudFront caching. The CLI fetches the latest schema at runtime with fallback to bundled version, enabling schema hotfixes without new CLI releases.
• Embedded Schema Only — Keep the current PR approach of bundling the JSON schema directly in the npm package as a static asset. Validation is performed synchronously using ajv against the local schema file, requiring no external dependencies or network calls. Schema updates ship with CLI versions.

Winner: Embedded Schema Only (1 round)

The hive chose "Embedded Schema Only" because this PR implements a self-contained JSON schema validation approach for CDK configuration files, with the schema embedded directly in the cdk package rather than relying on external database services. The question about DynamoDB vs PostgreSQL appears unrelated to this PR's scope, which focuses on local schema validation without any database requirements.

Debate details

Round 1: Embedded Schema Only(3) · Neither - File-Based Schema(1) · DynamoDB for Schema Registry(0) · PostgreSQL for Schema Analytics(0) · S3 with CloudFront(0)

[we-are-the-hive]

🐝 The Hive Has Spoken

Question: "is there a better way to do this"

Options considered:

• TypeScript-First Schema Generation — Define the configuration schema using TypeScript interfaces/types and use a tool like ts-json-schema-generator or typescript-json-schema to automatically generate the JSON schema. This keeps the source of truth in TypeScript, ensuring type safety throughout the codebase while auto-generating the schema artifact. The generated schema can be committed or built at compile time.
• Zod Schema with Inference — Use Zod to define the configuration schema programmatically, leveraging zod-to-json-schema to export JSON Schema when needed. This provides runtime validation, TypeScript type inference, and JSON Schema generation from a single source definition. Zod's composable API makes complex validation rules more maintainable than raw JSON Schema.
• JSON Schema as Source of Truth — Keep the manually authored JSON Schema as the canonical definition (current approach) but use json-schema-to-typescript to generate TypeScript types for internal use. This leverages JSON Schema's mature ecosystem for editor support and validation while ensuring type consistency. Consider adding schema linting via ajv-cli or spectral.
• Projen-Managed Schema Component — Create a custom Projen component that manages the schema lifecycle, including generation, validation task registration, and type synchronization. This aligns with the existing .projenrc.ts pattern in the monorepo and centralizes schema management logic. The component could wrap any underlying schema tool (Zod, TypeBox, etc.).
• TypeBox Runtime Schema — Use TypeBox to define schemas that are simultaneously valid JSON Schema and TypeScript types at compile time, with zero code generation step. TypeBox schemas compile directly to JSON Schema draft specifications and provide static type inference without separate build steps. This is particularly well-suited for configuration validation scenarios.

Winner: TypeBox Runtime Schema (1 round)

The hive chose TypeBox Runtime Schema because it enables defining the schema once in TypeScript and deriving both runtime validation and JSON Schema from the same source, eliminating the synchronization problem between manually maintained JSON Schema files and TypeScript types while providing type-safe validation.

Debate details

Round 1: TypeBox Runtime Schema(3) · Projen-Managed Schema Component(1) · TypeScript-First Schema Generation(0) · Zod Schema with Inference(0) · JSON Schema as Source of Truth(0)

[we-are-the-hive]

🐝 The Hive Has Spoken

Question: "what do you think? is there a better way to do this"

Options considered:

• Manual JSON Schema — Keep the current approach of manually maintaining a JSON schema file with explicit validation logic. This gives full control over schema structure, error messages, and validation behavior. The schema can be carefully curated to match exact CDK config requirements without tooling constraints.
• TypeScript-to-Schema Generation — Use tools like ts-json-schema-generator or typescript-json-schema to automatically generate the JSON schema from existing TypeScript interfaces. This ensures the schema always matches the source types and reduces duplication. The generated schema can be committed or generated at build time.
• Zod Schema as Source — Define configuration schema using Zod, then use zod-to-json-schema to generate the JSON schema for editor support while using Zod directly for runtime validation. This provides excellent TypeScript inference, composable schemas, and rich error messages out of the box.
• JSON Type Definition (JTD) — Use JSON Type Definition (RFC 8927) instead of JSON Schema, leveraging Ajv's JTD support for validation and code generation. JTD is simpler than JSON Schema with a smaller feature set, making it easier to maintain and faster to validate.
• Hybrid Schema with Tests — Keep the manual JSON schema but add automated tests that verify the schema matches TypeScript types using tools like ajv with typescript type guards or snapshot testing against interface shapes. This catches drift during CI while preserving manual control over the schema.

Winner: Hybrid Schema with Tests (1 round)

The hive chose the Hybrid Schema approach because it balances maintainability with safety—keeping the manually-written JSON schema for flexibility while adding comprehensive test coverage to catch drift between the schema and actual TypeScript types, ensuring long-term reliability without the complexity of full code generation.

Debate details

Round 1: Hybrid Schema with Tests(3) · JSON Type Definition (JTD)(1) · Manual JSON Schema(0) · TypeScript-to-Schema Generation(0) · Zod Schema as Source(0)