We Deserve Better Than JSON as a DSL
It always starts simply. You need a config, and you want to keep it simple this time. What's simpler than JSON? Some keys, some nesting, done.
Six months later the file looks like this:
{
"timeout": "5m",
"memory": "2GB",
"retries": "{{ env.CI ? 5 : 2 }}",
"url": "${PROTOCOL}://${HOST}:${PORT}"
}
Four values, three of which are secretly something else. "5m" is a duration someone has to parse. "2GB" is a size someone has to parse, and whether that's 2000 MB or 2048 MiB depends on which library parses it. The other two are expressions in a template language you invented, which a new hire has to be told about because nothing in the file says so.
Every team does this. GitHub Actions is YAML with an expression language inside it. Terraform invented HCL because JSON wasn't enough. OpenAPI is JSON Schema with extensions on top. Every AI framework has its own JSON for tool definitions, each slightly different.
JSON, YAML, and TOML are fine at what they do. The trouble starts when we ask them to carry logic, then build scaffolding around them when they can't.
What if the data could just do it?
That's why I built Stof. Stof is JSON with functions: the logic lives next to the data it works on, and your app runs the document in a sandbox. Here's that config as a Stof document. Press Run:
s timeout: 5min
MiB memory: 2GB
int retries: 2
str protocol: 'https'
str host: 'api.example.com'
int port: 443
fn url() -> str { `${self.protocol}://${self.host}:${self.port}` }
#[main]
fn main() {
pln(self.timeout); // a real duration, in seconds
pln(self.memory); // a real size, converted exactly
pln(self.url()); // a real function, not a template string
}Nothing here is secretly something else. 5min is a duration, and asking for it in seconds gives you seconds. 2GB is a size, and MiB on the field says what unit you want it in. url() is a function, so there's no template syntax to document and no second pass to run. Your app reads any of these the same way it reads a field:
import { StofDoc } from '@formata/stof';
const doc = await StofDoc.new(source);
doc.get('timeout'); // 300
doc.get('memory'); // 1907.3486328125
await doc.call('url'); // 'https://api.example.com:443'
Any JSON is already valid Stof, so you don't convert anything. You add a unit, a type, or a function where the config needed one, and leave the rest alone.
Rules that can't drift
The other thing a config grows is a schema. Here's a JSON Schema for a server config:
{
"type": "object",
"properties": {
"port": { "type": "integer", "exclusiveMinimum": 1024, "maximum": 65535 },
"memory": { "type": "string", "description": "Memory in MB, must be at least 256" }
},
"required": ["port"]
}
It's a second file in a second format, and nothing keeps it in sync with the first. Look at memory: JSON Schema has no units, so the best it can do is a description and a hope that someone reads it. The real check lives in your app code, which is a third place.
In Stof, the rule sits on the field it protects:
#[type]
Server: {
#[schema((v: int): bool => v != null && v > 1024 && v <= 65535)]
int port: 8080
#[schema((v: MiB): bool => v != null && v >= 256MB)]
MiB memory: 2GB
}
#[main]
fn main() {
pln(<Server>.schemafy(new { port: 8080, memory: '2GB' })); // true
pln(<Server>.schemafy(new { port: 80, memory: '100MB' })); // false
}The memory rule means something because Stof knows units: '2GB' converts and passes, '100MB' fails. The rule can't drift from the data because it's in the data. A model can read it, a person can review it, and the same check runs in TypeScript, Python, and Rust.
It's still your data
Stof doesn't replace your formats. It imports JSON, YAML, and TOML, and exports them back:
doc.parse(yamlFromDisk, 'yaml'); // load what you have
await doc.call('validate'); // run the logic that belongs with it
doc.stringify('json'); // hand plain JSON to whatever's next
So the config a model generates, the YAML your team already keeps, and the JSON your API expects can all be the same document for the few milliseconds it matters.
In production
Limitr runs on Stof. Every pricing policy (plans, credits, limits, and the rules that enforce them) is one Stof document, run in-process on every request. It's "data that carries its own logic" well past the toy stage.
Try it
The playground runs Stof in your browser, and every page in the docs has runnable examples.
npm i @formata/stof # TypeScript / JavaScript
pip install stof # Python
cargo add stof # Rust
cargo install stof-cli # CLI
Stof is open source under Apache 2.0, on GitHub. Tell us what you're building on Discord.
