YLSpec

Portable metadata documents that work on their own and inside other file formats.

YLSpec defines a versioned document envelope around TOML 1.1 and an optional, length-delimited binary frame for embedding that document into another file. The reference implementation is written in C11. Its Python package uses the same C core through a native CPython extension. JavaScript and TypeScript use Node-API on Node.js and WebAssembly in browsers and React applications. Java and Kotlin use JNI on desktop JVMs and Android. A VS Code extension brings the same parser to .ylspec editing.

Status: 0.1.1, experimental. The specification and APIs may change before 1.0. Review the compatibility policy before depending on an experimental version. A release's support claims are backed by its linked GitHub Actions run. Package-registry publication requires the account setup described in the registry guide; release assets can be used independently of those uploads.

Why YLSpec?

Applications frequently need the same metadata in several contexts: editable configuration, a component manifest, or a small record embedded in a larger binary file. YLSpec gives those contexts a shared document model and an explicit version boundary.

YLSpec does not define plugin execution, package installation, dependency resolution, signatures, or a host file's layout. Future formats can place YLSpec frames wherever their own headers or indexes specify.

Architecture

flowchart LR
    Text["Standalone .ylspec text"] --> Core["C11 document core"]
    Host["Host-supplied offset and region"] --> Frame["32-byte frame decoder"]
    Frame --> Core
    Core --> Values["Typed document values"]
    Values --> Profile["Explicit profile validation"]
    Core --> Python["Native Python API"]
    Core --> Node["Node-API: JavaScript and TypeScript"]
    Core --> WASM["WebAssembly: browser and React"]
    Core --> JNI["JNI: Java, Kotlin, and Android"]
    WASM --> Editor["VS Code language tools"]
    Core --> CLI["Inspection CLI"]

The embedding guide explains the byte layout and the host's responsibilities. The normative specification defines document validity independently of the reference implementation.

Installation

After the first PyPI release, install the native Python package with:

python -m pip install ylspec

Until then, download a wheel from a successful CI run's wheels-* artifact and install that wheel with python -m pip install path/to/the-wheel.whl. The release workflow adds published distributions to PyPI; this README does not display a PyPI version badge before a real project exists.

Native release assets contain both static/ and shared/ installations, with headers, libraries, CLI binaries, CMake package exports, and license notices. Choose one installation as your CMake prefix:

find_package(YLSpec CONFIG REQUIRED)
target_link_libraries(my_application PRIVATE YLSpec::ylspec)

See building for source builds and supported toolchains.

Other language packages

These names describe the built distributions. npm, Central, and Marketplace listings become available after their separate publishing workflows succeed. Until then, use the checksummed tarball, Maven-layout ZIP, or VSIX from the GitHub Release. No registry availability badge is shown before publication.

import {createClient} from '@younglionorganization/ylspec';
const yl = await createClient();
const document = new yl.Document({name: 'Example', count: 42n});
const restored = yl.unpack(yl.pack(document));
console.assert(restored.data.count === 42n);

Integer values are bigint in JavaScript and Long in Java/Kotlin. Exact temporal values retain their original fractional precision across adapters. The type mapping explains conversion boundaries. Browser initialization is asynchronous; once initialized, in-memory parsing and framing use the same synchronous C implementation.

Document example

[_ylspec]
version = "0.1"
profile = "core.data"
profile_version = "0.1"

[data]
name = "Example component"
enabled = true
platforms = ["linux-x86_64", "windows-x64", "macos-arm64"]

[extensions."xyz.younglion.example"]
channel = "stable"

data is application-defined. An application's version inside data is independent of the YLSpec format version and the profile version.

Python quick start

The complete, CI-executed example is examples/basic.py.

import io
import ylspec

document = ylspec.Document({"name": "Example", "enabled": True})
document.validate()

text = ylspec.dumps(document)
restored = ylspec.loads(text)
assert restored.data == document.data

prefix = b"host-defined prefix"
frame = ylspec.pack(document)
host = io.BytesIO(prefix + frame + b"unrelated payload")
metadata = ylspec.read_at(host, offset=len(prefix), available=len(frame))
assert metadata.data["name"] == "Example"

read_at restores the stream's original position. It reads the 32-byte header and exactly the document bytes declared in that header. Determining the region size may seek to the end, but does not read the host payload.

See the Python API for types, profile validators, errors, and exact timestamps. Detailed __init__.pyi and _native.pyi stubs and a py.typed marker ship with the package for editor completion and static checks; no separate stub distribution is required.

C quick start

The complete, CI-executed example is examples/basic.c.

#include <stdio.h>
#include <string.h>
#include <ylspec.h>

int main(void) {
    const char text[] =
        "[_ylspec]\nversion='0.1'\nprofile='core.data'\n"
        "profile_version='0.1'\n[data]\nname='Example'\n";
    yl_document *document = NULL;
    yl_error error = {0};
    if (yl_parse(text, strlen(text), NULL, &document, &error) != YL_OK) {
        fprintf(stderr, "%s\n", error.message);
        return 1;
    }
    yl_document_free(document);
    return 0;
}

Lengths are explicit; the input does not need a terminating NUL. The core does not open files. A host can supply a yl_read_at_fn callback to read an embedded document from a file, mapping, device, or other bounded source.

Resource limits and trust boundaries

Additional parser limits are listed in compatibility. Parsing does not imply profile approval, cryptographic verification, or permission to execute host content. See security.

CLI

ylspec --version
ylspec validate examples/config.ylspec
ylspec inspect examples/manifest.ylspec
ylspec pack examples/config.ylspec > metadata.bin
ylspec inspect-frame metadata.bin 0

See the CLI reference for commands, output, and exit codes.

Verification and releases

GitHub Actions builds static/shared C artifacts and Python wheels, runs C and Python tests, checks TOML 1.1 decoding against toml-test, runs sanitizers and bounded fuzzing, executes documentation examples, and renders Mermaid diagrams. Benchmark reports record the workload and environment without asserting an unmeasured speed threshold.

Language verification executes Node-API and JNI on the target systems, tests TypeScript ESM/CommonJS consumers, launches React in Chromium, builds four Android ABIs, executes JNI on an API 26 emulator, and tests a real VS Code Extension Host before packaging the VSIX.

The manually dispatched publish workflow rebuilds and verifies one commit, creates a draft release, attaches checksummed assets, publishes the same Python distributions to PyPI using the PYPI_API_TOKEN GitHub Actions secret, and then publishes the GitHub Release. Read publishing before the first release. Separate npm, Maven Central, and VS Code workflows consume the public release's checksummed artifacts. See registry setup for exact secret names, account ownership, and upload steps.

Documentation map

License and authorship

Copyright 2026 Cavanşir Qurbanzadə. Created under YoungLionOrganization. Original project material is licensed under Apache-2.0. See NOTICE, AUTHORS.md, and third-party notices. A document created by a user does not acquire this project's license merely by using the YLSpec format.