Skip to main content
The @yasumu/schema package provides a parser for Yasumu Schema Language (YSL), a custom DSL for defining REST API request schemas.

​
Installation

Install the schema parser package: 
npm install @yasumu/schema

​
Package configuration

The package supports multiple runtimes: 
{
  "exports": {
    "deno": "./src/index.ts",
    "bun": "./src/index.ts",
    "node": {
      "import": "./dist/index.js",
      "types": "./dist/index.d.ts"
    }
  }
}

​
Supported runtimes

  • Node.js - ESM modules with TypeScript definitions
  • Deno - Direct TypeScript import
  • Bun - Native TypeScript support

​
What is Yasumu Schema Language?

Yasumu Schema Language is a structured format for defining API requests with embedded JavaScript code blocks: 
@Example

Metadata {
    name: "Get Users"
    method: GET
}

Request {
    url: "https://api.example.com/users"
    body: null
}

Test {
    console.log("tested");
}

​
Key features

  • Type-safe parsing - Full TypeScript support with type inference
  • Structured blocks - Define metadata, requests, and scripts
  • Code blocks - Embed JavaScript for pre-request, post-request, and test scripts
  • Serialization - Convert parsed objects back to schema format
  • Validation - Automatic schema validation during parsing

​
Quick start

import { deserialize, serialize, t } from '@yasumu/schema';

// Define schema structure
const schema = t.script({
  annotation: 'Example',
  blocks: {
    Metadata: t.object({
      name: t.string(),
      method: t.enum('GET', 'POST'),
    }),
    Request: t.object({
      url: t.string(),
      body: t.nullable(t.string()),
    }),
    Test: t.nullable(t.code()),
  },
});

// Parse schema string
const code = `
@Example

Metadata {
    name: "Get Users"
    method: GET
}

Request {
    url: "https://api.example.com/users"
    body: null
}

Test {
    console.log("tested");
}
`;

const parsed = deserialize(code, schema);
console.log(parsed);

// Serialize back to string
const serialized = serialize(parsed, schema);
console.log(serialized);

​
Schema types

The t factory provides methods to define schema structure:
  • t.string() - String values
  • t.number() - Numeric values
  • t.boolean() - Boolean values
  • t.null() - Null values
  • t.code() - JavaScript code blocks
  • t.enum(...) - Enumerated values
  • t.object({...}) - Object structures
  • t.record(type) - Key-value maps
  • t.list(type) - Arrays
  • t.nullable(type) - Optional values
  • t.union(...) - Union types
  • t.script({...}) - Root schema definition

​
Exports

The package exports the following: 
import {
  // Factory
  t,
  YasumuSchemaFactory,
  
  // Actions
  YasumuSchemaActions,
  deserialize,
  serialize,
  
  // Parser components
  YasumuSchemaLexer,
  YasumuSchemaParser,
  YasumuSchemaScanner,
  YasumuSchemaSerializer,
  
  // Types
  YasumuSchemaParsable,
  YasumuSchemaParsableToType,
} from '@yasumu/schema';

​
Next steps

Parsing API

Learn how to parse schemas

RestModule

Use schemas with REST entities

Build docs developers (and LLMs) love

Get started for freeTalk to us