Magnexis Development Team

Posted on Jul 20

Introducing TypeYAML: A More Expressive, Type-Safe Way to Write YAML

#webdev #programminglanguage #about #yaml

Today, we are releasing TypeYAML, an open-source language that extends YAML with stronger structure, reusable types, validation, and developer-focused tooling.

TypeYAML is designed for developers who like YAML’s readability but need more confidence when working with large configuration files, schemas, deployment definitions, automation pipelines, application settings, and structured data.

The project is now available through:

npm: @magnexis/typeyaml
Visual Studio Code Marketplace: magnificent-language/typeyaml
GitHub: magnexis/typeyaml-lang

TypeYAML is still evolving, but this release establishes the foundation for a language intended to make configuration safer, clearer, and easier to maintain.

Why Build Another YAML-Based Language?

YAML is everywhere.

It is used for:

CI/CD pipelines
Docker Compose files
Kubernetes resources
GitHub Actions
Application configuration
Infrastructure definitions
API specifications
Static-site configuration
Package and project metadata

Its popularity makes sense. YAML is compact, readable, and approachable. A configuration file can often be understood without extensive documentation.

However, YAML becomes more difficult to manage as projects grow.

Large YAML files can contain deeply nested structures, duplicated values, inconsistent field names, invalid data types, undocumented conventions, and subtle indentation errors. In many cases, the file is only validated after another tool attempts to consume it.

That creates a frustrating workflow:

Write configuration.
Run a command.
Receive an unclear validation error.
Search through a large YAML file.
Fix the issue.
Repeat.

TypeYAML is an attempt to improve that experience without abandoning what makes YAML useful.

The goal is not to replace YAML’s readability. The goal is to build a stronger language around it.

What Is TypeYAML?

TypeYAML is a typed superset of YAML.

It introduces a language layer for defining and validating structured configuration while keeping the syntax familiar to developers who already use YAML.

A normal YAML file might look like this:

user:
  name: person
  age: 48
  active: true

This is easy to read, but the file does not **independently explain **its expected structure.

Should age always be a number?

Is name required?

Can active be omitted?

Are additional fields allowed?

TypeYAML is designed to make those expectations explicit.

A TypeYAML definition could describe the intended structure before data is used by the rest of an application:

type User:
  name: string
  age: number
  active: boolean

The exact syntax and feature set will continue to develop, but the central idea is simple: configuration should be able to describe and verify itself.

Instead of treating configuration as loosely structured text, TypeYAML treats it as a language with rules, types, tooling, and predictable behavior.

The Main Goals of TypeYAML

TypeYAML is being developed around several core principles.

1. Preserve YAML’s Readability

TypeYAML should remain recognizable to anyone familiar with YAML.

A developer should not need to learn an entirely unfamiliar syntax simply to gain validation and stronger structure.

The language should continue to feel lightweight and configuration-oriented rather than becoming a verbose general-purpose programming language.

2. Detect Errors Earlier

Configuration problems should be caught while the file is being written, not only after deployment or execution.

TypeYAML aims to support earlier feedback for issues such as:

Incorrect value types
Missing required properties
Unknown fields
Invalid nested structures
Duplicate declarations
Incorrect references
Malformed language syntax

Earlier validation means fewer failed builds, fewer broken deployments, and less time spent debugging configuration.

3. Make Large Configurations Easier to Maintain

As configuration grows, repeated structures become difficult to keep consistent.

TypeYAML is intended to support reusable definitions so developers can describe a structure once and use it throughout a project.

This can reduce duplicated schemas and make changes safer.

4. Provide First-Class Developer Tooling

A language is more than its parser.

TypeYAML is being released with tooling intended to support a practical development workflow, including an npm package and a Visual Studio Code extension.

The long-term goal is to provide a complete language experience with:

Syntax highlighting
Diagnostics
Validation
Autocomplete
Hover information
Formatting
Navigation
Language-aware refactoring
Command-line tooling
Programmatic APIs

5. Remain Compatible With Existing Ecosystems

YAML already has a massive ecosystem.

TypeYAML should work alongside existing YAML-based tools rather than requiring developers to immediately replace their entire configuration stack.

A major goal is to make it possible to author safer TypeYAML files and transform or compile them into standard YAML or other widely supported formats.

This approach would allow TypeYAML to add stronger guarantees during development while preserving compatibility with tools that already understand YAML.

Installing TypeYAML

The TypeYAML package is available on npm under the Magnexis organization.

Install it globally for command-line usage:

npm install -g @magnexis/typeyaml

Or install it inside a project:

npm install --save-dev @magnexis/typeyaml

Using it as a project dependency makes it easier to keep builds reproducible because the project can define the exact TypeYAML version it expects.

After installation, the package can be integrated into scripts, build systems, validation workflows, or other developer tooling supported by the current release.

Using TypeYAML in a Project

A project using TypeYAML may include dedicated TypeYAML source files alongside its application code.

For example:

my-project/
├── src/
├── config/
│   ├── application.typeyaml
│   ├── database.typeyaml
│   └── deployment.typeyaml
├── package.json
└── README.md

TypeYAML files can act as the source of truth for structured configuration.

A typical workflow may look like this:

Define configuration and its expected structure.
Validate the TypeYAML source.
Compile or transform it into a target format.
Pass the generated output to the application or deployment tool.
Include validation in CI to prevent invalid configuration from being merged.

This separates authoring from consumption.

Developers receive a richer language experience, while applications can continue consuming standard formats.

Visual Studio Code Support

TypeYAML is also available as a Visual Studio Code extension.

The extension is intended to make .typeyaml files feel like first-class source files instead of generic text documents.

Depending on the capabilities available in the current version, the extension provides or establishes the foundation for features such as:

TypeYAML syntax highlighting
Language-aware editing
File recognition
Error diagnostics
Validation feedback
Improved readability for nested structures
Future autocomplete and navigation support

To install it, open Visual Studio Code, search the Extensions Marketplace for TypeYAML, and install the extension published by Magnexis.

The extension is an important part of the project because configuration errors are most useful when they appear directly inside the editor.

Developers should not have to leave their editor or wait for a deployment command to discover that a value is invalid.

Example: Describing Application Configuration

Imagine an application that expects this configuration:

application:
  name: Example Service
  port: 8080
  environment: production
  logging:
    enabled: true
    level: info

In ordinary YAML, the expected types and allowed values are usually documented separately or enforced inside the application.

TypeYAML can move those expectations closer to the configuration itself.

A conceptual type definition might look like this:

type LoggingConfig:
  enabled: boolean
  level: "debug" | "info" | "warn" | "error"

type ApplicationConfig:
  name: string
  port: integer
  environment: "development" | "staging" | "production"
  logging: LoggingConfig

The corresponding configuration could then be checked against ApplicationConfig.

This would allow TypeYAML tooling to detect problems such as:

application:
  name: Example Service
  port: "eight thousand"
  environment: prod
  logging:
    enabled: yes
    level: verbose

Several values may be readable to a human but incompatible with the expected structure.

A type-aware tool could report that:

port should be an integer.
environment must use one of the declared values.
enabled should be a boolean.
verbose is not an accepted logging level.

That is the type of feedback TypeYAML is intended to make more immediate and understandable.

Why Types Matter in Configuration

Type systems are often associated with application code, but configuration benefits from them for many of the same reasons.

A configuration file acts as an interface between systems.

It may connect:

A developer and a deployment platform
An application and its runtime
A CI pipeline and a repository
An infrastructure definition and a cloud provider
A package and its build system

When either side misunderstands the expected shape of the data, the result is often a runtime failure.

Types make that contract explicit.

They can answer questions such as:

Which properties are required?
Which properties are optional?
What type of value is accepted?
Which string values are allowed?
Can a field contain a list?
What structure must each list item follow?
Can additional properties be included?
Does a referenced type exist?

These checks are especially valuable in shared repositories where many contributors modify configuration.

TypeYAML and CI/CD

One of the most practical uses for TypeYAML is automated validation.

A CI workflow could validate TypeYAML files whenever a pull request is opened.

A simplified script might look like:

{
  "scripts": {
    "validate:config": "typeyaml validate ./config",
    "build:config": "typeyaml build ./config"
  }
}

A CI job could then run:

npm ci
npm run validate:config

This makes configuration validity part of the project’s quality checks.

Invalid changes can be caught before they are merged, rather than after they reach a staging or production environment.

Potential TypeYAML integrations include:

GitHub Actions
GitLab CI
Jenkins
Azure Pipelines
Local pre-commit hooks
Build scripts
Deployment pipelines
Monorepo task runners

The exact commands may change as the CLI evolves, so users should refer to the repository documentation for the currently supported interface.

Potential Use Cases

TypeYAML is not limited to one category of configuration.

Application Configuration

Define environment settings, service options, ports, feature flags, logging rules, and runtime behavior.

Infrastructure Configuration

Add stronger validation before generating configuration for infrastructure and deployment systems.

CI/CD Pipelines

Describe reusable workflow structures and validate pipeline-specific values before running jobs.

API Definitions

Represent structured endpoint metadata, request models, response models, authentication settings, and API documentation.

Game and Tool Configuration

Define entities, levels, items, plugins, themes, commands, or project-specific metadata in a readable format.

Static-Site Content

Use TypeYAML for typed front matter, content collections, navigation, metadata, and site configuration.

Monorepo Configuration

Create shared configuration types that can be reused across multiple packages and applications.

Internal Developer Platforms

Define service catalogs, deployment templates, ownership data, environment policies, and platform metadata.

A Language, Not Just a Validator

TypeYAML is intended to become more than a wrapper around a schema validator.

The broader goal is to create a real language ecosystem around structured configuration.

That can include:

A formal grammar
A parser and abstract syntax tree
A semantic analyzer
A type checker
A formatter
A compiler or transpiler
A language server
Editor integrations
A package API
A command-line interface
Testing utilities
Documentation generators
Schema import and export
Plugin support

Treating TypeYAML as a language creates opportunities that would be difficult to implement through basic text validation alone.

For example, a language server could eventually understand references across files, locate type definitions, provide rename operations, and generate contextual autocomplete suggestions.

Interoperability

Interoperability is essential for adoption.

Developers already rely on tools that accept YAML, JSON, TOML, and other structured formats. TypeYAML should add value without isolating users from those ecosystems.

Possible interoperability goals include:

TypeYAML to YAML compilation
TypeYAML to JSON conversion
JSON Schema generation
Importing existing schema formats
Generating TypeScript types
Generating runtime validators
Exporting documentation
Integrating with OpenAPI
Supporting existing YAML parsers after compilation

This would allow a TypeYAML definition to potentially become a shared source for multiple outputs.

For example:

TypeYAML source
├── YAML configuration
├── JSON configuration
├── JSON Schema
├── TypeScript types
└── Generated documentation

A workflow like this could reduce duplication between configuration files, schemas, application types, and documentation.

Current Status

This release represents the beginning of TypeYAML as a public open-source project.

The language, tooling, syntax, and documentation will continue to evolve as real-world use cases are tested.

The priorities for the project include:

Stabilizing the language grammar
Expanding type-system capabilities
Improving parser diagnostics
Strengthening CLI behavior
Expanding Visual Studio Code support
Adding more examples
Improving documentation
Creating interoperability tools
Establishing a reliable test suite
Gathering feedback from early users

Because the project is still developing, users should expect changes as the language becomes more consistent and capable.

That is also why early feedback is valuable.

Planned Features

Some of the features being explored for future TypeYAML releases include:

Reusable Type Definitions

Define a structure once and reference it throughout a project.

Optional and Required Properties

Clearly distinguish between values that must be provided and values that may be omitted.

Union Types

Allow a field to accept one of several valid types or literal values.

environment: "development" | "staging" | "production"

Lists and Typed Collections

Describe lists whose items must follow a particular structure.

servers: Server[]

Default Values

Allow types or fields to specify defaults that can be applied during compilation.

Imports

Split large configurations and type definitions across multiple files.

References and Inheritance

Compose new structures from existing definitions.

Constraints

Support rules such as minimum values, maximum values, length restrictions, patterns, and allowed ranges.

Generated Documentation

Turn TypeYAML definitions into readable configuration reference pages.

Language Server Protocol Support

Provide diagnostics, autocomplete, go-to-definition, references, hover information, and rename functionality across compatible editors.

Multiple Compilation Targets

Generate YAML, JSON, schemas, code types, or documentation from a single TypeYAML source.

These are development goals rather than guarantees for the current release, but they represent the direction of the project.

Open Source and Community Contributions

TypeYAML is open source, and community involvement will play a major role in its development.

Contributions can include:

Reporting parser bugs
Suggesting syntax improvements
Improving documentation
Adding test cases
Creating examples
Building integrations
Improving editor support
Testing the language in real projects
Contributing to the CLI or compiler
Discussing interoperability requirements

One of the biggest challenges when designing a new language is balancing power with simplicity.

TypeYAML should be expressive enough to solve real problems without losing the readability that makes YAML appealing.

Feedback from developers using the language in different environments will help determine that balance.

How to Get Started

Install the npm package:

npm install --save-dev @magnexis/typeyaml

Install the TypeYAML extension from the Visual Studio Code Marketplace.

Then visit the typeyaml-lang repository on GitHub to review the latest documentation, examples, supported syntax, commands, issues, and release notes.

Because TypeYAML is actively evolving, the GitHub repository should be considered the primary source for the latest usage instructions.

Final Thoughts

Configuration has become a critical part of modern software development.

It controls deployments, infrastructure, automation, build systems, applications, services, and development environments. Despite that importance, configuration files are often treated as untyped text and validated only after something fails.

TypeYAML is built around a different idea:

Configuration should be readable like YAML, structured like a language, and validated like code.

This first release is the foundation.

There is still a great deal to build, refine, test, and document, but TypeYAML is now publicly available for developers who want to experiment with a more structured approach to YAML-based configuration.

You can find the project on GitHub under typeyaml-lang, install the package from npm as @magnexis/typeyaml, and download the TypeYAML extension from the Visual Studio Code Marketplace.

Feedback and issues are welcome.

This is only the beginning of TypeYAML.