Skip to main content
The schema parser provides functions and classes to parse Yasumu Schema Language (YSL) into structured data.

​
Functions

​
deserialize()

Parses a YSL string into a structured object. 
import { deserialize, t } from '@yasumu/schema';

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()),
    }),
  },
});

const code = `
@Example

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

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

const parsed = deserialize(code, schema);
console.log(parsed);
​
content
string
required
The YSL string to parse
​
expect
YasumuSchemaParsable
required
The schema definition that describes the expected structure
​
return
YasumuSchemaParsableToType<T>
Parsed object matching the schema structure

​
serialize()

Serializes a structured object back to YSL format. 
import { serialize, t } from '@yasumu/schema';

const value = {
  annotation: 'Example',
  blocks: {
    Metadata: {
      name: 'Get Users',
      method: 'GET',
    },
    Request: {
      url: 'https://api.example.com/users',
      body: null,
    },
  },
};

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()),
    }),
  },
});

const serialized = serialize(value, schema);
console.log(serialized);
​
value
YasumuSchemaParsableToType<T>
required
The object to serialize
​
expect
YasumuSchemaParsable
required
The schema definition
​
return
string
YSL-formatted string

​
YasumuSchemaActions class

The YasumuSchemaActions class provides methods to parse and serialize with a predefined schema.

​
Constructor

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

const schema = t.script({
  annotation: 'Example',
  blocks: {
    Metadata: t.object({
      name: t.string(),
      method: t.enum('GET', 'POST'),
    }),
  },
});

const actions = new YasumuSchemaActions(schema);
​
expect
YasumuSchemaParsable
required
The schema definition to use for parsing and serialization

​
parse()

Parses a YSL string using the predefined schema. 
const actions = new YasumuSchemaActions(schema);

const parsed = actions.parse(`
@Example

Metadata {
    name: "Get Users"
    method: GET
}
`);

console.log(parsed);
​
content
string
required
The YSL string to parse
​
return
YasumuSchemaParsableToType<T>
Parsed object matching the schema

​
serialize()

Serializes an object using the predefined schema. 
const actions = new YasumuSchemaActions(schema);

const serialized = actions.serialize({
  annotation: 'Example',
  blocks: {
    Metadata: {
      name: 'Get Users',
      method: 'GET',
    },
  },
});

console.log(serialized);
​
value
YasumuSchemaParsableToType<T>
required
The object to serialize
​
return
string
YSL-formatted string

​
YasumuSchemaFactory (t)

The t factory provides methods to define schema structures.

​
t.script()

Defines a root schema with annotation and blocks. 
const schema = t.script({
  annotation: 'Example',
  blocks: {
    Metadata: t.object({
      name: t.string(),
    }),
    Request: t.object({
      url: t.string(),
    }),
    Test: t.nullable(t.code()),
  },
});
​
expect
object
required

​
t.object()

Defines an object with named properties. 
const schema = t.object({
  name: t.string(),
  method: t.enum('GET', 'POST'),
  params: t.nullable(t.record(t.string())),
});
​
expect
Record<string, YasumuSchemaParsable>
required
Object property definitions

​
t.record()

Defines a key-value map where all values have the same type. 
const schema = t.record(t.string());
// Parses: { key1: "value1", key2: "value2" }

const schema = t.record(t.union(t.string(), t.number(), t.boolean()));
// Parses: { key1: "hello", key2: 123, key3: true }
​
expect
YasumuSchemaParsable
required
Type of values in the record

​
t.list()

Defines an array of values. 
const schema = t.list(t.string());
// Parses: ["value1", "value2"]
​
expect
YasumuSchemaParsable
required
Type of array elements

​
t.code()

Defines a JavaScript code block. 
const schema = t.code();
// Parses: { console.log("hello"); }

​
t.string()

Defines a string value. 
const schema = t.string();
// Parses: "hello world"

​
t.number()

Defines a numeric value. 
const schema = t.number();
// Parses: 123

​
t.boolean()

Defines a boolean value. 
const schema = t.boolean();
// Parses: true or false

​
t.null()

Defines a null value. 
const schema = t.null();
// Parses: null

​
t.nullable()

Makes a type optional. 
const schema = t.nullable(t.string());
// Parses: "hello" or null
​
expect
YasumuSchemaParsable
required
The type to make nullable

​
t.enum()

Defines an enumerated set of string values. 
const schema = t.enum('GET', 'POST', 'PUT', 'DELETE');
// Parses: GET, POST, PUT, or DELETE
​
...expect
string[]
required
Allowed enum values

​
t.union()

Defines a union of multiple types. 
const schema = t.union(t.string(), t.number(), t.boolean());
// Parses: "hello" or 123 or true
​
...expect
YasumuSchemaParsable[]
required
Types in the union

​
Complete example

Here’s a complete example showing parsing and serialization: 
import { deserialize, serialize, t, type YasumuSchemaParsableToType } from '@yasumu/schema';

// Define schema
const schema = t.script({
  annotation: 'Example',
  blocks: {
    Metadata: t.object({
      name: t.nullable(t.string()),
      method: t.nullable(t.enum('GET', 'POST')),
    }),
    Request: t.object({
      url: t.string(),
      params: t.nullable(
        t.record(t.union(t.string(), t.number(), t.boolean(), t.null()))
      ),
      headers: t.nullable(t.record(t.string())),
      body: t.nullable(
        t.object({
          type: t.string(),
          data: t.string(),
        })
      ),
    }),
    BeforeRequest: t.nullable(t.code()),
    AfterRequest: t.nullable(t.code()),
    Test: t.nullable(t.code()),
  },
});

// Parse schema
const code = `
@Example

Metadata {
    name: "Test"
    method: GET
}

Request {
    url: "https://example.com"
    body: null
    params: {
        key1: "hello"
        key2: 123
        key3: true
        key4: null
    }
}

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

const parsed = deserialize(code, schema);
console.log(JSON.stringify(parsed, null, 2));

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

// Type-safe value
const value: YasumuSchemaParsableToType<typeof schema> = {
  annotation: 'Example',
  blocks: {
    Metadata: {
      name: 'Test',
      method: 'GET',
    },
    Request: {
      url: 'https://example.com',
      body: null,
      params: {
        key1: 'hello',
        key2: 123,
        key3: true,
        key4: null,
      },
      headers: null,
    },
    Test: '\n    console.log("tested");\n',
    BeforeRequest: null,
    AfterRequest: null,
  },
};

const output = serialize(value, schema);
console.log(output);

Schema overview

Schema parser overview

RestModule

Use schemas with REST

Build docs developers (and LLMs) love

Get started for freeTalk to us