# Semantic domains

One owns a standard semantic distribution, but it does not own every meaning an
organization, industry, or community needs. A semantic domain is an independent
package of vocabulary, validation, normalization, compatibility, and evidence.

## Own meaning in your namespace

A domain defines stable declaration kinds, nominal values, defaults,
constraints, reference rules, normalized owner records, compatibility, and
diagnostics. It uses the Contracts meta-model without translating its concepts
into `one.*` identities.

Every domain extends exactly one language rooted at `one.semantic@1` and
composes additional packages through any number of explicit `use` entries.
Trait packages use `one.trait@1`; domain languages use
`one.semantic.domain@1`. Imported names retain their semantic owners and become
applicable only through exact coherent trait implementations.

Examples include payments, clinical protocols, industrial processes,
geospatial policy, games, logistics, scientific instruments, or an
organization's internal governance. Each domain remains independently useful
and independently releasable.

## Keep the frontend untrusted

A `.one` semantic item selects one primary domain. Its authored syntax is an
input projection. The admitted domain normalizer validates the complete item
and produces the owner-qualified normalized value.

The frontend cannot mint trusted IR, choose an implementation or provider,
issue authority, or establish conformance. Generated forms and diagrams edit
canonical source through revision-checked transactions; they do not become a
second semantic store.

## Compose through directional mappings

Two domains compose only through explicit mappings owned at a declared
boundary. A mapping records preserved meaning, transforms, defaults, narrowing,
widening, loss, preconditions, and evidence.

Mappings are directional and versioned. Shared field names, shared source
files, or structural similarity never establish equivalence.

## Package a complete domain

A reusable distribution can include:

- the declaration vocabulary and normalized schemas;
- evaluator or normalizer implementations;
- compatibility and mapping rules;
- conformance and negative suites;
- documentation projections;
- provider-independent planning contributions;
- implementations and providers in separately owned packages.

These pieces publish through governed supply-chain contracts. Selecting the
semantic package does not activate optional implementations or providers.

## Evolve one current contract line

Pre-stable authoring syntax may change while normalized owner meaning remains
stable. A semantic change updates the domain's current contract and all active
callers together. Compatibility paths exist only when users genuinely need
bounded coexistence at a public boundary, not to preserve repository history.

## Example

Illustrative source selects organization-owned meaning directly:

```one
semantic shop.products
    domain acme.commerce@1
    product TrailShoe@1
        sku "shoe-trail-42" price EUR 129.00
```

Follow [Define a semantic domain](/one/examples/semantic-domain).
For the complete authoring model, read
[domains and traits](/one/authoring/domains-and-traits).

Canonical owners:
[Contracts](https://github.com/muijf/one/blob/main/systems/contracts/AGENTS.md),
[System IDL](https://github.com/muijf/one/blob/main/systems/system-idl/AGENTS.md),
and [Provider Ecosystem](https://github.com/muijf/one/blob/main/systems/providers/AGENTS.md).