YAML reference

socotra.yaml reference

Schema 1.1. Every field, type, default, and validation rule.

Full example

socotra.yaml

socotra:
  version: "1.1"
  solution:
    name: "MyApp"
    rootNamespace: "MyCompany.MyApp"
    dotnetVersion: "net9.0"
    outputPath: "./src"
    nullable: true
    implicitUsings: true
    treatWarningsAsErrors: true
  architecture:
    pattern: modular-monolith
    enforceLayerConstraints: true
    allowedDependencies:
      - from: "*.Domain"
        to: "*.Domain"
  modules:
    - name: "Orders"
      namespace: "MyApp.Orders"
      description: "Order processing module"
      layers:
        - name: "Domain"
          type: ClassLib
          templates: ["base-entity", "value-object"]
        - name: "Application"
          type: ClassLib
          references: ["Orders.Domain", "../SharedKernel"]
          packages: ["FluentValidation:11.9.2"]
        - name: "Infrastructure"
          type: ClassLib
          references: ["Orders.Application"]
          packages: ["Microsoft.EntityFrameworkCore.SqlServer:8.0.0"]
        - name: "Api"
          type: WebApi
          references: ["Orders.Application", "../SharedKernel"]
  shared:
    - name: "SharedKernel"
      type: ClassLib
      templates: ["base-entity", "result-pattern"]
  host:
    name: "MyApp.Api.Host"
    type: WebApi
    references: ["**/*.Api"]

Root: `socotra`

Field	Type	Required	Description
`version`	string	Yes	Schema version. Must be `"1.0"` or `"1.1"`
`solution`	object	Conditional	Required if no modules are defined
`architecture`	object	No	Architecture constraints and dependency rules
`modules`	array	Conditional	Required if no solution is defined
`shared`	array	No	Shared projects referenced by modules
`host`	object	No	Host / entry-point project

SCT-000

At least one of solution or modules must be present.

`socotra.solution`

Field	Type	Required	Default	Description
`name`	string	Yes	—	Solution name (used for .sln filename)
`rootNamespace`	string	No	`name`	Root namespace for generated code
`dotnetVersion`	string	Yes	—	Target framework
`outputPath`	string	No	`"./"`	Directory where projects are created
`nullable`	bool	No	true	Enable nullable reference types
`implicitUsings`	bool	No	true	Enable implicit usings
`treatWarningsAsErrors`	bool	No	false	Treat all warnings as errors

Valid dotnetVersion: net8.0, net9.0, net10.0, netstandard2.0, netstandard2.1

`socotra.architecture`

Field	Type	Required	Default	Description
`pattern`	string	No	`modular-monolith`	Architecture pattern
`enforceLayerConstraints`	bool	No	false	Validate references against `allowedDependencies`
`allowedDependencies`	array	No	—	Allowed dependency rules

Patterns

modular-monolith — monolithic solution decomposed by business modules with DDD-style layers (Domain, Application, Infrastructure, Api). Recommended for large team-scale monoliths that may later extract to microservices.
clean-architecture — single-module solution with strict layer dependency inversion (WebApi → Application → Domain). Recommended for smaller projects or strict onion/hexagonal architectures.

`socotra.modules[]`

Field	Type	Required	Description
`name`	string	Yes	Module name. Must be unique (SCT-003)
`namespace`	string	No	Override namespace for this module's projects
`description`	string	No	Human-readable description
`layers`	array	Yes	List of layer definitions within this module

layers[]

Field	Type	Required	Description
`name`	string	Yes	Must be unique within the module (SCT-004)
`type`	string	Yes	Project type — see enum below
`templates`	array	No	Template names to apply to this project on creation
`references`	array	No	Project references
`packages`	array	No	NuGet packages — format `"PackageId:Version"`

`socotra.shared[]`

Shared projects not tied to any specific module but referenceable by any layer.

Field	Type	Required	Description
`name`	string	Yes	Unique across all shared, modules, and host
`type`	string	Yes	Project type
`templates`	array	No	Template names to apply
`references`	array	No	Project references
`packages`	array	No	NuGet packages

`socotra.host`

Host / entry-point project — typically a WebApi or Worker that references module Api projects.

Field	Type	Required	Description
`name`	string	Yes	Host project name
`type`	string	Yes	Project type
`templates`	array	No	Template names to apply
`references`	array	No	Project references
`packages`	array	No	NuGet packages

Reference resolution

Pattern	Example	Resolution
Exact name	`MyApp.Data`	Matches project by exact name
Glob	`MyApp.*`	Converted to regex, matches multiple projects
Module.Layer	`Orders.Domain`	Resolves to Orders module's Domain layer project
Local prefix	`./Data`	Strips ./ prefix, resolves relative to current context
Relative path	`../MyApp.Data`	Uses last segment (Data) for name matching

Glob patterns support * (single-segment) and ** (multi-segment).

ProjectType enum

Value	.NET template	Description
`ClassLib`	`classlib`	.NET class library
`WebApi`	`webapi`	ASP.NET Core Web API
`Worker`	`worker`	Worker service
`Console`	`console`	Console application
`Maui`	`maui`	.NET MAUI app
`Blazor`	`blazorserver`	Blazor Server
`BlazorWasm`	`blazorwasm`	Blazor WebAssembly
`Wpf`	`wpf`	WPF application
`WinForms`	`winforms`	Windows Forms
`XunitTest`	`xunit`	xUnit test project
`NUnitTest`	`nunit`	NUnit test project
`MsTest`	`mstest`	MSTest test project
`Razor`	`razorclasslib`	Razor class library

Package format

packages:
  - "FluentValidation:11.9.2"
  - "Microsoft.EntityFrameworkCore.SqlServer:8.0.0"
  - "Serilog.AspNetCore:8.0.0"

Both PackageId and Version are validated against NuGet naming conventions (SCT-009).

Schema migration: 1.0 → 1.1

socotra.architecture for constraint enforcement
socotra.shared for cross-module shared projects
socotra.host for explicit entry-point projects
allowedDependencies for fine-grained layer access

Use socotra migrate to upgrade a 1.0 file. The original is backed up with a .bak extension.

Schema 1.1 · CLI 1.0

Previoussocotra template Next Error codes