Validation

Catch configuration errors before code generation runs.

Overview

Ninjadog validates your ninjadog.json configuration in two phases before generating any code. This ensures that structural problems (malformed JSON, missing required fields) and logical problems (duplicate keys, invalid references) are caught early with clear, actionable diagnostics.

flowchart LR
    A["ninjadog.json"] --> B["Phase 1<br/>Schema Validation"]
    B -->|Pass| C["Phase 2<br/>Semantic Validation"]
    B -->|Fail| D["Errors reported"]
    C -->|Pass| E["Code generation"]
    C -->|Warnings/Errors| F["Diagnostics reported"]

Phase 2 only runs if Phase 1 passes. This avoids cascading errors from malformed JSON.

Phase 1 – Schema Validation

Schema validation checks that your configuration conforms to the JSON Schema draft-07 definition embedded in Ninjadog. It verifies:

• Structure – Required top-level sections (config, entities) are present
• Types – Values have the correct JSON types (string, boolean, integer, object, array)
• Required fields – Mandatory fields within each section exist (e.g., config.name, config.version, config.rootNamespace, config.description)
• Allowed values – Enum-constrained fields use valid values (e.g., database.provider must be sqlite, postgresql, or sqlserver)
• No extra properties – Unknown fields are rejected (additionalProperties: false throughout)

What the Schema Covers

Schema Error Example

Given this configuration with a missing required field:

{
  "config": {
    "name": "MyApi",
    "version": "1.0.0"
  },
  "entities": {}
}

Schema validation reports:

SCHEMA  Error  $.config  Required properties ["description","rootNamespace"] are not present

Phase 2 – Semantic Validation

Once the JSON structure is valid, Ninjadog parses the configuration and checks for logical correctness. Each check has a unique diagnostic code.

Diagnostic Codes

Built-in Types

The following types are recognized as built-in. Any other type must be defined in the enums section or exist as an entity name:

string, int, Int32, long, Int64, float, Single, double, decimal, bool, Boolean, Guid, DateTime, DateTimeOffset, DateOnly, TimeOnly, byte[], List<T>

Semantic Error Example

Given this configuration with two key properties and a non-existent relationship target:

{
  "config": {
    "name": "MyApi",
    "version": "1.0.0",
    "description": "My API",
    "rootNamespace": "MyApi"
  },
  "entities": {
    "Order": {
      "properties": {
        "Id": { "type": "Guid", "isKey": true },
        "Code": { "type": "string", "isKey": true },
        "Status": { "type": "OrderStatus" }
      },
      "relationships": {
        "customer": {
          "relatedEntity": "Customer",
          "type": "OneToMany"
        }
      }
    }
  }
}

Semantic validation reports:

NINJ001  Error    $.entities.Order.properties         Entity 'Order' must have exactly one isKey property, but found 2.
NINJ002  Error    $.entities.Order.relationships.customer.relatedEntity  Relationship 'customer' in entity 'Order' references non-existent entity 'Customer'.
NINJ005  Error    $.entities.Order.properties.Status.type  Property 'Status' in entity 'Order' uses type 'OrderStatus' which is not a built-in type and is not defined in the enums section.

Fix NINJ005 by adding an enums section: "enums": { "OrderStatus": ["Pending", "Shipped", "Delivered"] }.

Severity Levels

Errors prevent code generation from proceeding. Warnings are reported but do not block generation.

IDE Support with $schema

Add a $schema property to your ninjadog.json to get autocomplete, inline documentation, and real-time validation in editors like VS Code, JetBrains Rider, and Neovim:

{
  "$schema": "https://raw.githubusercontent.com/Atypical-Consulting/Ninjadog/main/src/library/Ninjadog.Settings/Schema/ninjadog.schema.json",
  "config": {
    "name": "MyApi",
    "version": "1.0.0",
    "description": "My API",
    "rootNamespace": "MyApi"
  },
  "entities": {
    "Product": {
      "properties": {
        "Id": { "type": "Guid", "isKey": true },
        "Name": { "type": "string" }
      }
    }
  }
}

The $schema property is ignored by Ninjadog at runtime – it exists solely for editor integration. You can safely add or remove it without affecting code generation.

What You Get

• Autocomplete – Property names, enum values (sqlite, postgresql, sqlserver), and relationship types are suggested as you type
• Inline docs – Hover over any property to see its description from the schema
• Error highlighting – Missing required fields, wrong types, and unknown properties are underlined immediately

Programmatic Usage

The validation framework is available in the Ninjadog.Settings.Validation namespace:

using Ninjadog.Settings.Validation;

var json = File.ReadAllText("ninjadog.json");
var result = NinjadogConfigValidator.Validate(json);

if (!result.IsValid)
{
    foreach (var error in result.Errors)
    {
        Console.Error.WriteLine($"{error.Code}  {error.Path}  {error.Message}");
    }
}

foreach (var warning in result.Warnings)
{
    Console.WriteLine($"Warning: {warning.Code}  {warning.Path}  {warning.Message}");
}

The SchemaValidationResult record provides:

Each ValidationDiagnostic contains:

Next Steps

• Getting Started – Build your first API
• Architecture – Understand the design decisions and tech stack
• CLI Reference – Scaffold projects with the CLI tool