The Sylang Language, in One Sitting

3.1 The three primitives: hdef, def, ref

Sylang's surface grammar rests on three primitives: hdef (header definition), def (definition), and ref (reference). Together they define the structure of every artifact file. Everything else in the language (properties, enumerated values, multi-line strings, the indentation that shows nesting) goes through one of these three.

We'll take each primitive in turn: what it does in the artifact's structure, an example from the EPB anchor project, and then the rules for how the primitives combine.

hdef: the header definition

Every Sylang file contains exactly one hdef clause, at the file's top level (column 0, no indentation). The hdef declares the type and identifier of the artifact the file contains. The artifact's header-level properties follow at column 2 (two-space indentation).

An hdef clause looks like this:

hdef <type-keyword> <Identifier>
  <property-name> <property-value>
  <property-name> <property-value>
  ...

1. Type-keyword is one of the 22 reserved header keywords: requirementset for .req, featureset for .fml, block for .blk, and so on. Subchapter 3.2 lists the full set.
2. Identifier is unique across the whole project and is conventionally PascalCase. It must match the filename stem exactly: hdef requirementset EpbSafetyRequirements lives in EpbSafetyRequirements.req. The validator enforces this, and it's how cross-file references (see ref below) resolve to specific files.
3. Header-level properties (name, description, owner, safetylevel and so on, depending on the file type) sit at column 2, right below the hdef line. Their order doesn't matter to the validator. The convention is identity first (name, description), then classification (safetylevel, status, level), then relationships (derivedfrom, allocatedto, etc.).

Here's an example from the EPB anchor project's EpbSafetyRequirements.req file:

hdef requirementset EpbSafetyRequirements
  name "EPB Safety Requirements"
  description "Functional safety requirements for the Electric Parking Brake."
  owner "EPB Safety Engineering"
  safetylevel ASIL-D
  status approved
  level system

Each property name comes from the file type's allowed-keyword set (defined in keywords.ts). Each value must fit that property's type: string, enum value, multi-line string, number, or identifier reference. The validator checks both: that the keyword is allowed, and that the value has the right type.

def: the definition

Below the hdef and its header-level properties, a file holds zero or more def clauses. These are the artifacts the header owns. Which def subtypes you can use depends on the file type:

• A .req file's hdef requirementset permits def requirement children
• A .fml file's hdef featureset permits def feature children with variability flags
• A .blk file's hdef block permits def characteristic children for AIAG-VDA product characteristics

Subchapter 3.2 has the complete mapping. A def clause looks like this:

  def <subtype-keyword> <Identifier>
    <property-name> <property-value>
    <property-name> <property-value>
    ...

The def clause sits at column 2 (under the hdef's header-level properties), and its own properties sit at column 4. You can nest a def inside a def wherever the file type's grammar allows it; each level adds two spaces. A .haz file, for example, holds def hazard clauses at column 2, and each of those holds one or more def situation clauses at column 4.

hdef hazardanalysis EpbHazards
  name "EPB Hazard Analysis"
  safetylevel ASIL-D

  def hazard UnintendedRelease
    name "Unintended Release on Gradient"
    malfunctionof ref function HoldMonitor
    affects ref feature CoreEpb

    def situation RollawayInTraffic
      name "Rollaway in stop-and-go traffic"
      severity S3
      exposure E4
      controllability C3
      safetylevel ASIL-D

The payoff is that references resolve without extra context: no namespace prefixes, no qualified names. The cost is that you have to choose identifiers carefully. Two conventions help: build the parent identifier into the child's (RollawayInTraffic under UnintendedRelease), or use a project-wide prefix (EPB_, INS_, ACR_) for top-level identifiers.

ref: the typed reference

One artifact points to another through the ref keyword, paired with a relationship keyword and a target type. The general form is:

    <relationship-keyword> ref <target-type> <Identifier>

The relationship-keyword is one of the 47 typed relationship keywords listed in Subchapter 3.3 (derivedfrom, allocatedto, satisfies, mitigates, causedby, and so on). The target-type is the type of the artifact you're pointing at: a requirement, a function, a block, a safetygoal, and so on. The Identifier is that artifact's project-wide unique identifier.

So if an AI agent writes an invalid reference, it gets a structured validator error straight away, not a silent failure at audit. Here's a canonical example from the EPB requirements file:

  def requirement REQ_EPB_002
    name "Prevent engagement above 10 km/h"
    reqtype safety
    safetylevel ASIL-D
    derivedfrom ref safetygoal SG_NoUnintendedEngagementAtSpeed
    implements ref function EngageController
    allocatedto ref block EpbController

• derivedfrom ref safetygoal: requires SG_NoUnintendedEngagementAtSpeed to be defined somewhere as def safetygoal ... (in EpbSafetyGoals.sgl)
• implements ref function: requires EngageController to be def function ... (in EpbFunctions.fun)
• allocatedto ref block: requires EpbController to be hdef block ... (in EpbController.blk)
• If any identifier is misspelled, points to an artifact that doesn't exist, or points to one of the wrong type, the validator rejects it at parse time with a specific error code

The use statement: surfacing cross-file dependencies

If a file has ref expressions pointing to artifacts in other files, it must declare those dependencies with use statements at the top (column 0, above the hdef). Each use statement names the artifact type and identifier of the other file's header.

use functionset EpbFunctions
use safetygoalset EpbSafetyGoals

hdef requirementset EpbSafetyRequirements
  name "EPB Safety Requirements"
  ...

Putting the three primitives together

Every Sylang file has the same shape. Zero or more use statements sit at column 0, followed by exactly one hdef clause, also at column 0. The hdef's header-level properties go at column 2, and so do zero or more def clauses. Each def's own properties sit at column 4, further-nested defs sit at column 4 with their properties at column 6, and so on.

Every reference from this file's artifacts to artifacts in other files reads the same way: a relationship keyword, then ref, a target type, and the target's identifier. Once you've written a few files, you'll read that pattern without thinking about it.

Exercises

The only thing left for the agent to learn is each file type's vocabulary. The skill file captures it compactly (Subchapter 3.5), and the validator enforces it deterministically. Next, in Subchapter 3.2, we'll walk through those 22 file types.

3.2 The 22 file types

Sylang splits its artifacts across 22 file types, each with its own extension, its own header keyword and its own purpose. This is the language's main organizational decision. SysML expresses requirements, blocks, activities and use cases in one XMI vocabulary and tells them apart with internal markers. Sylang gives each artifact category its own file extension instead.

The 22 file types, in six functional groups

The 22 file types fall into six functional groups. The groups are just a teaching aid; the language itself doesn't treat them as a syntactic category. Once you know them, you can open a Sylang project folder and tell what each file holds before you read a line of it.

Group 1: Product Line and Configuration (4 file types)

Group 2: Functions and Requirements (2 file types)

Group 3: Architecture and Behavior (5 file types)

Group 4: Safety Engineering (6 file types, the ISO 26262 chain)

Group 5: Verification and Documentation (3 file types)

Group 6: AI Project Management (2 file types)

Counting to 22

I expect the count to grow as more engineering disciplines join the artifact set: mechanical assemblies, FEA, software architecture description languages, system-of-systems descriptions. I expect that growth to stay conservative, because every new file type must arrive with a complete grammar, validator and skill file. The language is designed to take new types cleanly, without disturbing the existing 22.

What a typical project looks like on disk

A typical project arranges its files in directories that follow the engineering decomposition, not the file type. The EPB anchor project shows the convention:

automotive-epb/
├── EpbProductLine.ple
├── System/
│   ├── EpbFeatures.fml
│   ├── EpbFunctions.fun
│   ├── EpbItem.itm
│   ├── EpbHazards.haz
│   ├── EpbSafetyGoals.sgl
│   └── EpbSafetyRequirements.req
├── PowerStage/
│   ├── EpbController.blk
│   ├── EpbInterfaces.ifc
│   ├── EpbStateMachine.smd
│   ├── EpbSafetyMechanisms.sam
│   ├── EpbFmea.flr
│   ├── EpbFta.fta
│   └── EpbTests.tst
├── Variants/
│   ├── Epb_SingleMotor.vml
│   ├── Epb_DualMotor.vml
│   ├── EpbConfig_SingleMotor.vcf
│   └── EpbConfig_DualMotor.vcf
├── Agents/
│   └── EpbProgramAgents.agt
├── Sprints/
│   └── EpbSprint01.spr
└── Reports/
    ├── EpbSpec.spec
    └── EpbDashboard.dash

The 22 file types live in an 18-package ecosystem

That's what AI-first means in practice. It isn't only the language design. It's the tool surface that AI agents bind to.

Exercises

3.3 The 47 relationship keywords

The 47 typed relationship keywords are the core of the language's ontology. They define the edges of the artifact graph: the typed links between requirements and safety goals, functions and blocks, failure modes and their causes, test cases and the requirements they verify. Each keyword carries three things: (a) the source artifact types it permits, (b) the target artifact types it permits, and (c) an optional file-extension scope, for when the same keyword means different things in different file types.

Below, the 47 keywords are grouped into nine functional categories. The categories are there to help you learn; the validator doesn't treat them as a syntactic distinction. For each keyword you'll get its permitted source and target types and a short gloss. The worked examples come later, in the chapters that introduce each source file type.

Category 1: Hierarchical decomposition (3 keywords)

Category 2: Refinement and derivation (4 keywords)

Category 3: Allocation and realization (5 keywords)

Category 4: Verification (3 keywords)

Category 5: Safety / ISO 26262 (10 keywords)

Categories 6 to 9 at a glance

How we count to 47

The exact number matters less than this: the rule set is finite, enumerable and auditable. You can read all of it, and so can an agent.

The four query-clause keywords in .spec and .dash files (source, where, groupby, orderby) aren't part of the 47. They aren't edges in the artifact graph. They're query operators that the reactive-documentation renderer interprets, rather than relationships validated against a target node type. Chapter 16 covers them in detail.

Exercises

The rules table fits in a few hundred lines of source and rarely changes. That discipline is what makes the language workable for AI authors without giving up expressiveness. Next, Subchapter 3.4 covers the smaller syntax details and the validator that enforces all of this.

3.4 Syntactic conventions and the validator

Subchapters 3.1 to 3.3 covered the language's primitives, file types and relationship vocabulary. This one finishes the syntax with the smaller details (indentation, string quoting, enumerated values, comments). Then it turns to the validator that enforces all of it.

Indentation: significant, two-space, no tabs

• use and hdef always at column 0
• The hdef's properties, and def clauses directly under the hdef, at column 2
• Properties of a def nested under the hdef at column 4
• Each further nesting level adds two more spaces

Most modern editors use two-space indentation by default, and Sylang Studio configures itself when you open a file. If you're editing in an editor that isn't set up for it, a project-level .editorconfig file at the project root is enough to enforce the convention.

String quoting: single for atoms, triple for prose

Sylang has two string forms, and you choose by purpose.

  def requirement REQ_EPB_001
    name "Detect clamp force undershoot within 100 ms"
    description """
      When commanded to engage, the EPB shall detect a clamp force
      undershoot (force more than ClampForceTolerance below the
      ClampForceSetpoint) within 100 ms of the engagement timer expiring,
      and shall annunciate ClampForceFault.
    """
    rationale """Without timely undershoot detection, the vehicle
      may be left in a perceived-engaged state that does not hold
      against a gradient.""\

Multi-value properties (tags, owner when there are several owners, includes, excludes and a few others) take comma-separated double-quoted strings on one line: tags "EPB", "ASIL-D", "ISO-26262". Prefer this over repeating the property name on several lines.

Enumerated values: bare, no quotes

Properties that take their value from a fixed vocabulary are written as bare keywords, with no quotes:

  safetylevel ASIL-D
  status approved
  reqtype safety
  method HIL
  severity S3
  exposure E4
  controllability C3

• safetylevel: ASIL-A to ASIL-D, QM, SIL-1 to SIL-4
• status: draft, review, approved, deprecated, implemented, ...
• reqtype: functional, safety, system, software, hardware, interface, ...
• method: MIL, SIL, PIL, HIL, VIL, manual, automated
• severity / exposure / controllability: S0 to S3, E0 to E5, C0 to C3
• mechanismtype: redundancy, monitoring, diagnostic, degradation, validation
• gatetype: and, or, xor, inhibit
• chartype: special, critical, significant

Comments

Sylang has two comment forms. Single-line comments start with // and run to the end of the line, while block comments sit between /* and */. The parser strips comments before validation, so they have no effect on the artifact graph. They're there only for human readers.

  // Top-level safety requirement for the unintended-release hazard.
  def requirement REQ_EPB_001
    name "Detect clamp force undershoot within 100 ms"
    /* This requirement was originally tagged ASIL-C but was promoted
       to ASIL-D after the 2024 HARA review identified the highway
       traffic situation. See HARA-2024-Q4-rev3 for the analysis. */
    safetylevel ASIL-D

The validator: a single source of truth

The validator implements every rule in this chapter. It runs at parse time on a Sylang file (or a whole project of files) and returns either a clean parse or a list of ValidationError records. Each record carries a structured error code, a human-readable message, a file location and an optional severity (error or warning).

You can run it from four places: Sylang Studio (continuous feedback as you edit), the CI pipeline (gating pull-request merges), the command-line tool (ad hoc checks), and an AI agent's reasoning loop. In that last case, it's the feedback signal the agent uses to converge on a valid artifact. You'll know it's doing its job when your mistakes show up while you edit, not at audit.

Validator error codes (the contract)

• SYLANG_UNKNOWN_KEYWORD: property name not in the file type's allowed-keyword set
• SYLANG_UNKNOWN_RELATIONSHIP: relationship keyword not valid in the current file type
• SYLANG_INVALID_RELATIONSHIP_TARGET: relationship referencing the wrong target type
• SYLANG_INVALID_ENUM_VALUE: enumerated-value property with a value not in the allowed set
• SYLANG_MISSING_REF_KEYWORD: reference without the mandatory ref keyword
• SYLANG_UNRESOLVED_REFERENCE: reference whose target identifier can't be found in the project
• SYLANG_INDENTATION_ERROR: inconsistent or invalid indentation
• SYLANG_IDENTIFIER_NOT_UNIQUE: identifier defined more than once in the project
• SYLANG_FILENAME_HDEF_MISMATCH: filename stem doesn't match the hdef identifier
• SYLANG_CONFIG_INCONSISTENT_REFERENCE: variant-gated artifact references an artifact in an inconsistent variant state

Where this leaves you

With Subchapters 3.1 to 3.4, you now have the language in enough detail to author any file in any of the 22 file types. The three primitives, the use statement, the 22 file-type vocabularies, the 47 relationship keywords, the indentation and quoting conventions, the enumerated values, the comment forms and the validator's error-code contract: together, they make up the complete language reference.

One piece of Chapter 3 is left: the skill-file convention. These are the per-file-type Markdown documents that AI agents load on first encounter, and they're the language's most distinctive contribution to making AI authorship workable. Subchapter 3.5 covers them.

Exercises

3.5 The skill-file convention: how Sylang teaches itself

In principle, the language reference in 3.1 to 3.4 is enough for an AI agent to author Sylang artifacts. In practice, an agent needs more: which property goes first, which patterns are idiomatic, which mistakes the language permits but the safety standards reject, which workflows the surrounding tooling assumes. Most tools bury that knowledge in the IDE's interface (toolbar buttons, wizard dialogs, inline documentation). Sylang puts it in one Markdown file per file type, and the agent loads that file explicitly.

The problem skill files solve

Picture an AI agent opening its first .flr file. The language reference tells it that .flr is a failureset file containing failuremode definitions, each with the properties severity, occurrence, detectability and rpn. It also says failure modes can point to each other through causedby and effects references, with optional within N temporal constraints. That's enough to produce a syntactically valid .flr file.

• The severity and occurrence scales carry meaning (10 = catastrophic; 1 = no effect).
• RPN has a customary threshold of 100, above which mitigation is mandatory.
• The causedby chain must trace from root causes to top events without cycles.

The usual documentation strategy (write a user manual and expect the engineer to read it) fails with AI authors, because an agent doesn't load user manuals on its own. Even with retrieval augmentation, it can't reliably find the right section of the manual at the right moment. What's needed is documentation the agent is required to load when it meets a file of a given type. It has to fit in the agent's context and hold the conventions, idioms and pitfalls the agent needs to author that file well.

What a skill file is

In Sylang, a skill file is a Markdown document, conventionally 200 to 500 lines, that goes with one file type. It holds the conventions and worked examples the agent needs. Every skill file follows the same fixed template:

1. Front matter (YAML): the skill's name, plus a one-paragraph description of when the agent should load it
2. Purpose section: what the file type represents and where it sits in the wider artifact set
3. File structure section: the header keyword, the allowed def subtypes, and the required and optional properties at each level
4. Worked examples section: one or more complete, runnable artifact examples covering the file type's main use cases
5. Authoring patterns section: the idiomatic workflows (top-down vs bottom-up, common decomposition strategies, integration with other file types)
6. Common pitfalls section: mistakes that give valid syntax but unwanted semantics, each with symptom, cause and correction
7. Cross-skill references: which other skills to consider loading alongside this one

When skills get loaded

Sylang Studio, and any AI agent that integrates with it through the Hermes runtime, follows this loading discipline:

• When an agent session starts, load sylang-fundamentals.md: the cross-cutting skill covering the three primitives, the 22-file-type map, the 47-relationship-keyword summary and the conventions common to all file types
• The first time the agent meets a file of a given type, load the matching file-type skill (for example, sylang-requirements.md for .req files)
• If the task spans several file types, load sylang-traceability.md instead of several individual skills
• Keep it to one or two skills at a time. Loading every skill on every interaction throws away the context savings.

The current skill set

As of the Sylang 0.1 release (late 2024), nine skills cover the 22 production file types, each covering one functional group from Subchapter 3.2:

Why this convention matters

On the surface, the skill-file convention is a small operational detail: a recommendation about where to put per-file-type documentation. It matters more than that, for three reasons:

Skills meet the MCP server

Skill files are the documentation contract: what the agent loads to understand a file type. The complementary execution contract is the @sylang/mcp server (introduced in Subchapter 3.2), which exposes Sylang's structured operations as MCP tools.

In concrete terms: sylang_get_symbol_by_id reads an artifact, sylang_get_symbols_by_kind and sylang_resolve_symbol query the graph, and sylang_validate_file checks a proposed modification. Other tools compute the FMEA, FTA and traceability analyses.

Put together, they produce a pattern you'll see again and again: skill file → agent prompt → MCP tool call → structured result → next reasoning step. It recurs in every artifact production session, and it's what AI as primary author means in day-to-day operation.

Exercises

From here, Chapter 4 sets up the Sylang Studio IDE, where you'll most often write the language. It walks you through your first complete project and shows the agent integration that makes AI authorship work in practice. Chapter 5 then develops the project-management constructs (.agt and .spr) that organize the AI authoring work itself.