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.4, 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.
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.
| Capability | Standalone document | Embedded frame |
|---|---|---|
| Human-editable UTF-8 TOML 1.1 | Yes | The payload is the same text |
| Standard and profile versioning | Yes | Yes |
| Namespaced project extensions | Yes | Yes |
| Exact temporal literals | Yes | Yes |
| Read without touching unrelated host content | Entire document | Header plus declared document bytes |
| Requires an archive or decompressor | No | No |
| Executes embedded code | No | No |
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.
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.
Install the published native Python package with:
python -m pip install ylspecPublished versions are available on PyPI and
in the checksummed GitHub Releases.
For offline installation, download a matching release wheel and install it with
python -m pip install path/to/the-wheel.whl. Verification-only builds are also
available in successful CI runs' wheels-* artifacts.
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.
| Consumer | Distribution | Integration guide |
|---|---|---|
| JavaScript / TypeScript / Node.js | @younglionorganization/ylspec, native Node-API |
JavaScript API |
| Browser / React | The same npm package, bundled C WebAssembly | Browser initialization |
| Java / Kotlin desktop | xyz.younglion:ylspec and ylspec-kotlin |
JVM guide |
| Android | Common Java/Kotlin API plus ylspec-android JNI AAR |
Android dependencies |
| VS Code | ylvsmp.ylspec / ylspec-0.1.4.vsix; language tools using bundled WebAssembly |
Editor guide |
The JavaScript package is published on npm. The Maven namespace is verified and the VS Code extension is available on the Marketplace. Each new version becomes available after its registry workflow succeeds. Checksummed tarballs, the Maven-layout ZIP, and the VSIX are available from GitHub Releases independently of registry verification. Registry badges reference actual published metadata.
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.
[_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.
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.
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.
| Property | Default or policy |
|---|---|
| Maximum document text | 16 MiB; configurable |
| Maximum value depth | 64 edges from root; configurable up to 128 |
| Frame header | 32 bytes, little-endian |
| Embedded text | UTF-8 TOML 1.1, uncompressed |
| Integer / float | Signed 64-bit / IEEE-754 binary64 |
| Required feature or profile validation | Explicit; unsupported means failure |
| Integrity and authenticity | Supplied by the host, if needed |
Additional parser limits are listed in compatibility. Parsing does not imply profile approval, cryptographic verification, or permission to execute host content. See security.
ylspec --version
ylspec validate examples/config.ylspec
ylspec inspect examples/manifest.ylspec
ylspec pack examples/config.ylspec > metadata.bin
ylspec inspect-frame metadata.bin 0See the CLI reference for commands, output, and exit codes.
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.
| Guide | Audience |
|---|---|
| Specification | Independent implementers |
| Embedding | Host-format designers |
| Profiles and extensions | Application developers |
| C API and ownership | C integrators |
| Python API and types | Python integrators |
| JavaScript, TypeScript, browser, and React | Web and Node.js developers |
| Java, Kotlin, and Android | JVM and Android developers |
| VS Code integration | Editor users and extension maintainers |
| CLI | Users inspecting documents |
| Building | Native-library consumers |
| Compatibility | Maintainers and adopters |
| Publishing | Release maintainers |
| Registry accounts and secrets | Package publishers |
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.