Okyline Annex E Quick Reference - External Imports & Versioning

Version: 1.7.0 Date: May 2026 Status: Draft

Companion to the Okyline Core Language Quick Reference. Covers cross-schema composition: identity ($id/$version/$state), dependencies ($deps), imports ($import), multi-payload validation ($entries), visibility ($public/$private), and registry resolution.

E - External Imports & Versioning

Okyline supports cross-schema composition: a contract declares its own identity, depends on other contracts via $deps, and imports named definitions via $import. External references resolve at load time against a registry; once imported, aliases behave exactly like local $defs entries.

E.1 Contract Identity

Key	Purpose
`$id`	Schema identifier (`[namespace.]name`)
`$version`	Semver 2.0.0 (`1.3.4`, `2.0.0-rc.1`, …)
`$state`	Lifecycle: `"DRAFT"` (default, mutable) or `"FINAL"` (frozen, immutable)

$id and $version are required to publish to a registry or to be imported.

E.2 Dependency Declaration - `$deps`

"$deps": {
  "common":  "~1.3.0",
  "crm":     "^2.0.0",
  "billing": "1.5.0"
}

Constraint	Matches
`1.3.4`	Exact version only
`~1.3.0`	Same MAJOR.MINOR, any PATCH
`^1.3.0`	Same MAJOR, any MINOR/PATCH

$deps MUST be present whenever $import declares at least one import.

E.3 External Imports - `$import`

Maps local aliases to definitions from declared dependencies. $import lives inside the sub-block whose kind it imports:

"$deps": { "common": "~1.3.0" },
"$defs": {
  "$import": {
    "Address": "&common.Address",
    "Email":   "&common.Email"
  }
}

Inside $oky/$defs, references use the local alias (&Address); the external form (&common.Address) is only valid inside $import.

Each sub-block hosts its own $import and imports only its own kind:

"$defs":         { "$import": { "Address": "&common.Address" } }
"$nomenclature": { "$import": { "COUNTRY": "&geo.COUNTRY"    } }
"$format":       { "$import": { "Email":   "&common.Email"   } }
"$compute":      { "$import": { "Tax":     "&billing.Tax"    } }

E.4 Registry Resolution

Two-pass selection (F.5 stability contagion rule): 1. Stable preferred: highest stable version matching the constraint. 2. Pre-release fallback (gated): only if the constraint itself names a pre-release (e.g. ~1.3.0-rc.0) or the consumer’s own $version is a pre-release.

Constraint	Available	Stable consumer	Pre-release consumer
`"~1.3.0"`	`1.3.0`, `1.3.1`	`1.3.1`	`1.3.1`
`"~1.3.0"`	`1.3.5-rc.2`	no match	`1.3.5-rc.2`
`"~1.3.0"`	`1.3.0-rc.1`	no match	no match

Use ~1.3.0-rc.0 (pre-release in the constraint) to opt in to pre-releases of the base patch.

E.5 Interaction with Annex D

Once imported, $import aliases share the namespace of $defs. All Annex D mechanisms - $ref (property and object level), $override, $amend, $remove - work identically on local and imported definitions.

Scope rule: an imported field resolves its references in its source contract’s scope (nomenclatures, formats, computes). $override is the only mechanism that rebinds resolution to the local contract.

Numeric precision: an imported compute runs with the source contract’s $decimalScale if the source has explicitly declared one; otherwise it inherits the active scale. Prevents silent precision drift on financial calcs.

E.6 Validation Entry Points - `$entries`

Declare additional validation entry points within a single schema. Each entry maps a public name to a local type reference; consumers can validate against a specific entry rather than only the root $oky payload.

"$entries": {
  "AnimalCreate": "&Animal",
  "OrderCreate":  "&Order"
}

Value form: &Name (local reference). External form &id.Name is not allowed here - import via $import first if needed.
Name must resolve to a type in the unified symbol table (local $defs or imported $import alias).
Default validation target remains $oky when no entry name is supplied.

E.7 Visibility - `$public` / `$private`

Per-sub-block visibility ($defs, $nomenclature, $format, $compute) controls what is exposable to external $import imports. The two directives are mutually exclusive within a single sub-block.

"$defs": {
  "Animal":   { ... },
  "Helper":   { ... },
  "$private": ["Helper"]
}

Mode	Effect
Neither declared	All entries exposed (default - backward-compatible)
`$public: [...]`	Strict allow-list. `[]` locks all.
`$private: [...]`	Deny-list. Empty `[]` is rejected (use absence).
Both	Error (mutually exclusive)

Listed names are bare (no sigil). A hidden name appears absent to external importers - no information leak. Visibility is a barrier to import, not a runtime gate: an exposed type that internally uses hidden nomenclatures/formats/computes still resolves them at validation time.

E.8 Re-export through Alias Chains

A $import alias is itself a valid import target. An intermediate library can re-export definitions from its own dependencies under a local alias:

common.Address  ←  region.$import.Addr  ←  app imports &region.Addr

Applies to all four kinds. Re-exports are subject to the visibility rules of the intermediate (§E.7). Cycles in alias chains cause schema loading to fail.

Okyline® is a registered trademark of Akwatype.