Every One project has one canonical authored language. A .one file combines
non-executable semantic items with isolated implementation claims without
merging their grammar, identity, or trust.
Source units and items
Every source begins with its exact envelope revision:
one 1
It then contains one or more top-level items. There are exactly two envelope forms:
semantic acme.orders
domain one.product@1
# declarations governed by the selected domain
impl acme.orders#OrdersRust@1
realizes acme.orders#Orders@1
using one.language.rust#OwnedAsync@1
source
// isolated source-language body
semantic selects one namespace and one primary domain. impl associates one
stable implementation claim with one semantic target and one exact language
profile. Co-location creates no reference, reachability, provider choice,
authority, or runtime activation.
Indentation is structure
Four spaces form one canonical structural level. A greater indentation starts the preceding head's child suite; a matching dedent closes it. Blank lines and comment-only lines do not affect structure.
Tabs in structural indentation, inconsistent dedents, required empty suites, children under scalar-only clauses, trailing block colons, and structural braces are errors. A newline ends the current clause; indentation is not a generic continuation mechanism.
Colons remain valid inside lines for typed fields and named arguments:
record Order@1
id: OrderId
items: List<LineItem>
@Invariant(total == sum(items[*].price))
Expression delimiters remain explicit: List<T>, f(x), items[*],
1..=100, and @Length(1..=64) do not acquire special layout rules.
Identities, lanes, and exact revisions
Order@1 names the @1 compatibility lane of Order; the lock selects its
exact immutable revision. A declaration name, continuing identity, compatibility
lane, and exact revision are different things.
Source uses owner-qualified names where context does not already establish the namespace. A friendly name resolves only when the selected source and lock make it unambiguous. Later stages retain exact owner identities and never repeat name search.
Domain selection and imports
The first child of a semantic item is its primary domain:
semantic acme.orders
domain one.product@1
That domain supplies a closed public vocabulary: declaration heads, types, traits, units, rules, defaults, and normalizers. There is no compiler-owned hidden prelude.
Additional dependencies are definition-ordered use declarations:
use acme.money.Money@3
use one.identity@1 only Principal, TenantId
use acme.compliance@1
use one.data@2 as data_v2
A symbol import binds its terminal name. A package import binds its terminal
namespace, such as compliance.Control. only is a finite one-line selective
import. as performs a category-preserving rename. Two identities or lanes
cannot occupy the same source name, and an import cannot silently shadow a
primary-domain export.
Imports precede first use. Local declarations and members are also definition-ordered: a refinement can reference only imports, completed declarations, and preceding members. Genuine recursion uses an explicit domain-owned recursion group; unresolved forward references do not imply it.
Structural types, collections, and relations
The selected domain may expose scalar and nominal types, records, variants, references, and constructors such as:
Text
Bytes
UInt
Decimal
Optional<T>
List<T>
Map<K, V>
Relations use <, <=, ==, !=, >=, and >. Ranges use start..end or
inclusive start..=end. Both sides must have compatible owner-defined types or
dimensions.
Typed quantities and units
A dimensional literal is a number followed directly by an exact, case-sensitive unit symbol:
timeout: 30s
retention: 7y
payload_limit: 16MiB
throughput: 100MiB/s
monthly_cost: <= 5_000USD
availability: >= 99.95%
Fixed durations and calendar periods remain distinct. m is a minute; mo
is a calendar month. B, KiB, and MiB are binary byte units, while kB
and MB are decimal. b is a bit. Case changes are semantic and are never
corrected heuristically.
The lexer recognizes quantity structure; the exact imported owner resolves the unit and dimensional arithmetic. Equivalent forms normalize only when an owner definition proves the conversion. Decimal normalization never depends on binary floating-point rounding.
Comments, formatting, and incomplete source
# introduces a System IDL comment where the selected language permits it.
The formatter preserves comments and malformed regions, uses four-space
structural indentation, keeps every use on one line, and never rewrites a
foreign implementation body.
Incomplete or malformed bytes remain the current authored state. Editors may offer completion and patch candidates, but they cannot show a previous valid semantic value as though it represented newer invalid source.
Next: domains and traits, then author a product.