Standards#

A shared data engine must work beyond one language, client library, or vendor. Private protocols make every integration depend on the knowledge of one project. Open specifications carry decisions that many people have examined across different industries. The RFC process shows how public review can turn that shared knowledge into a stable agreement.

One model between systems#

JSON gives languages a small, widely understood value model. JSON-compatible values give each client the same objects, arrays, strings, numbers, booleans, and null. No implementation language owns those values. Clients can use common JSON tooling while schemas state the exact constraints.

Some values in Stardust have no JSON counterpart. Stardust renders each link, UTC time, duration, UUID, and SHA-256 digest as an object with one #-prefixed key:

when {#utc 2024-01-02T03:04:05Z}

Times and durations use ISO 8601 text. A plain JSON object is therefore always a map, and the leading # marks the other kinds.

JSON is effective between machines but can become noisy during human authoring and review. DUST provides a human-readable form that decodes to the same JSON values. It learns from the readability goals of YAML and TOML without adopting a different value model. Keys and values are bare words when they need no quotes, arrays and objects separate members with whitespace, and // starts a comment. These tutorials use DUST because people must read, write, and review them.

// A document in DUST
name   Dune
active true
// The meaning of life, universe, and everything
count  42 // the answer
tags   [database graph]
when   {#utc 2024-01-02T03:04:05Z}
friend {#link 42}

A top-level document, and any object that spans lines, holds exactly one member per line, and the rest of the line is the value of that member. That lets a bare value hold spaces: title The Fellowship of the Ring is one string. To keep several members on one line, put the whole object on that line, as in {op a args {t 1}}. Once the object continues on a later line, start each member on its own line:

step {op parse
      args {text "[1" format json}
      error {status invalid_json}}

In a multi-line object, {op a args 1 reads as the member op with the string a args 1. A line such as {op a args {t 1} is refused with Members_On_One_Line at the second key, because a bare string cannot contain a bracket.

Conversion changes the notation without changing the data. Every entity appears in both a JSON and a DUST projection of the same facts, and a write in either projection commits the same facts. The bundled dustfmt tool converts and formats in both directions.

DUST comments become one $comment member of the object that holds them, so review notes survive conversion in place. Each comment is one line of that text.

A comment above the first member is a plain line. A comment after a value is count: the answer. A comment on its own line before a later member is count:: The meaning of life, universe, and everything. A comment before the closing brace is :: text. Items in an array use their index, as in tags[1]:: text.

Machine-readable contracts#

A shared value model describes possible data but does not define one operation. JSON Schema Draft-7 gives each stored schema an exact, machine-readable structure. The schema is the authority for names, types, required values, bounds, defaults, and descriptions. A schema that is not a valid Draft-7 document is rejected when it is written. Clients can validate against the same contract without a second language-specific definition.

The database itself is a FUSE mount. Entities, definitions, the transaction log, and runtime status are ordinary files, so any tool that reads and writes files can use them. No client library is required for reads and document writes.

Queries, mutations, expressions, and validation run through the Language Server Protocol (LSP). The mount listens on a loopback port and accepts workspace/executeCommand requests such as stardust.query.execute, stardust.mutation.execute, and stardust.entity.validate. The same connection serves editor features, so an editor and an agent use one protocol. A generated Go SDK wraps these files and commands with types that follow the database's current schemas and queries.

Results are JSON-compatible values that agents and other clients can use directly. People can read the same results in DUST for review. The conversion changes the presentation but preserves the data.

When no standard fits#

Established specifications remain the default wherever they fit. A missing standard can justify new work when the same problem occurs across projects and languages. The proposed solution must remain useful outside Stardust instead of encoding private product behavior. DUST follows this rule because it decodes to the same values as JSON, which keeps it connected to existing tools and shared expectations.