Ocean Repository

1. Overview

The Ocean Repository is the source of reusable and versioned Ocean definitions. Ocean also recognizes a related local source, the Pre-baked Registry, for reusable items supplied by the local environment.

It allows system designers to reuse existing DSL definitions rather than redefining common models and capabilities for every system.

Repository items may include:

• datatypes;
• APIs;
• databases;
• brokers;
• expressions;
• FSMs;
• components;
• services;
• other reusable Ocean definitions.

Local pre-baked items may include ready-made capabilities or technology selections that a project can resolve locally, such as a particular PostgreSQL distribution. They use the same identity structure as Ocean Repository items but belong to a different source.

Definitions may be provided by:

• Ocean itself;
• organizations;
• teams;
• projects;
• other authorized publishers.

The repository provides the foundation for reuse, composition, discovery, versioning, and sharing across the Ocean ecosystem.

---

2. Core Principle

Reusable Ocean definitions should remain DSL definitions, not opaque implementation artifacts.

Conceptually:

Ocean Repository
       │
       ├── Datatypes
       ├── APIs
       ├── Expressions
       ├── FSMs
       ├── Components
       ├── Services
       └── ...
              │
              ▼
       Ocean DSL Project

A repository item retains its DSL identity and semantics when reused.

This allows Ocean to:

• parse it;
• validate it;
• inspect it;
• compose it;
• generate implementations from it;
• understand its relationships with other definitions.

---

3. Repository References

Every reusable item can be identified through a repository reference. The prefix identifies its source.

Canonical formats:

O.<namespace>.<name>@<version>
P.<namespace>.<name>@<version>

Example:

O.auth.loginFlow@1.2.0

Another example:

O.std.tax.nl.CalculateVAT@2.0.0

Local pre-baked example:

P.docker.postgresql@15.1.23-stable

O. identifies an item in the Ocean Repository. P. identifies an item in the local Pre-baked Registry. In both cases, the reference provides a stable identity for a specific reusable item.

---

4. Reference Structure

An Ocean or pre-baked reference consists of:

Part	Meaning	Example
O.	Identifies an Ocean Repository item	O.auth.loginFlow@1.2.0
P.	Identifies a local Pre-baked Registry item	P.docker.postgresql@15.1.23-stable
namespace	Logical hierarchy containing the item	auth, std.tax.nl, docker
name	Name of the reusable item	loginFlow, CalculateVAT, postgresql
version	Item version	1.2.0, 15.1.23-stable, latest

Conceptually:

O.<namespace>.<name>@<version>
│      │          │       │
│      │          │       └── version
│      │          └────────── item name
│      └───────────────────── namespace
└──────────────────────────── Ocean Repository

The equivalent local form is:

P.<namespace>.<name>@<version>
└──────────────────────────── local Pre-baked Registry

---

5. Namespaces

Namespaces organize reusable definitions into logical groups.

A namespace may contain multiple hierarchical segments.

Examples:

auth

billing

std.tax.nl

domain.payment

This allows related definitions to be grouped while maintaining globally meaningful references.

For example:

O.domain.payment.CardInfo@1.2.0

identifies:

Repository : Ocean
Namespace  : domain.payment
Name       : CardInfo
Version    : 1.2.0

---

6. Versioning

Ocean Repository definitions are versioned.

Example:

O.auth.loginFlow@1.2.0

A version allows systems to depend on a known definition rather than automatically consuming incompatible changes.

Where supported, latest may identify the latest applicable version:

O.auth.loginFlow@latest

If the version is omitted, the repository may resolve it to latest according to repository resolution rules.

The same version rules apply to P. references unless the local registry defines a more specific contract. A pre-baked version may contain a release channel or variant suffix:

P.docker.postgresql@15.1.23-stable

Version-resolution behavior should remain explicit and deterministic.

---

7. Using Repository Definitions

Repository definitions are consumed through Ocean reuse mechanisms.

The primary mechanisms include:

@import
@include

These mechanisms serve different purposes. O. references resolve through the Ocean Repository. Whether a construct accepts a P. reference is defined by that construct’s contract, because a local pre-baked item is not necessarily a DSL definition.

Conceptually:

             Ocean Repository
             or Pre-baked Registry
                    │
           Repository Reference
                    │
          ┌─────────┴─────────┐
          │                   │
       @import             @include
          │                   │
          └─────────┬─────────┘
                    │
                    ▼
             Local DSL Model

Their exact syntax and semantics are defined by their corresponding DSL references.

---

8. Importing Definitions

@import allows a DSL file to explicitly import a selected repository definition and expose it through a local alias.

Conceptually:

@import <type> <OceanRef> as <Alias>

Example:

@import datatype O.std.auth.UserToken@1.0.0 as Token

The alias may then be used as if the imported definition were available locally:

@datatype

@import datatype O.std.auth.UserToken@1.0.0 as Token

Session
    user    : Token
    expires : Int

The exact import contract is defined by:

dsl.import

---

9. Import Types

Different kinds of Ocean definitions may be imported.

Examples include:

@import datatype O.domain.payment.CardInfo@1.2.0 as CardInfo

@import expression O.common.logic.DotProduct@2.1.0 as Dot

@import fsm O.auth.loginFlow@1.2.0 as login

@import component O.billing.InvoiceLogic@2.0.0 as invoice

The receiving DSL construct determines which imported definition types are valid in its scope.

---

10. Local Aliases

Imported definitions are accessed through local aliases.

Example:

@import datatype O.std.auth.UserToken@1.0.0 as Token

The full repository identity is:

O.std.auth.UserToken@1.0.0

while its local DSL identity is:

Token

This separates:

• global repository identity;
• local model naming.

Aliases also prevent repository namespace details from leaking unnecessarily throughout the local DSL.

---

11. Resolution

When Ocean encounters a repository reference, the referenced item must be resolved before it can be used. Resolution first selects the source from the prefix: O. selects the Ocean Repository and P. selects the local Pre-baked Registry.

Conceptually:

Repository Reference
      ↓
Source Selection (`O.` or `P.`)
      ↓
Version Resolution
      ↓
Reusable Item
      ↓
Validation
      ↓
Local Model

For Ocean Repository items, resolution must produce an unambiguous DSL definition. A pre-baked item must produce an unambiguous locally usable item that satisfies the contract of the construct consuming it.

An unresolved or ambiguous reference is invalid.

---

12. Repository Item Requirements

A reusable Ocean item should be backed by a valid Ocean definition.

This ensures that repository content remains understandable to the Ocean toolchain.

A reusable item should therefore be:

• identifiable;
• versioned;
• parseable;
• validatable;
• deterministic;
• discoverable;
• compatible with the Ocean DSL model.

The repository should preserve the DSL definition as the authoritative representation of the reusable capability.

---

13. Reuse and Composition

The Ocean Repository enables systems to be assembled from existing definitions.

For example:

Application
│
├── local definitions
│
├── O.std.auth.UserToken
├── O.common.audit.AuditService
├── O.domain.payment.CardInfo
└── O.common.validation.IsEmail

These definitions may originate from different namespaces while participating in the same system model.

This enables composition without copying DSL definitions between projects.

---

14. Discovery

Repository items should be discoverable through their metadata and identity.

Discovery may support criteria such as:

• name;
• namespace;
• DSL type;
• version;
• tags;
• domain;
• publisher;
• lifecycle status.

Discovery allows designers and tooling to find reusable definitions before creating new ones.

The concrete search and discovery implementation is outside the scope of this concept.

---

15. Publishing

Reusable definitions may be published to the Ocean Repository.

Conceptually:

DSL Definition
      ↓
Validation
      ↓
Metadata
      ↓
Version
      ↓
Publish
      ↓
Ocean Repository

Publishing should preserve:

• identity;
• version;
• DSL type;
• metadata;
• dependencies;
• relationships.

The detailed publishing lifecycle and governance are defined separately from this concept.

---

16. Access and Visibility

Repository definitions may have different visibility scopes.

Possible models include:

• public definitions;
• organization-internal definitions;
• private project or team definitions;
• licensed or restricted definitions.

Access control is a repository concern and does not change the semantic meaning of the underlying DSL definition.

The exact access model may evolve with the Ocean Repository implementation.

---

17. Repository vs Implementation Technology

The Ocean Repository stores reusable Ocean definitions, not technology-specific implementations as its primary abstraction.

For example:

O.common.audit.AuditService@1.0.0

represents an Ocean service definition.

Generation may later produce:

Go
Java
Kubernetes
NATS
PostgreSQL
...

depending on the target configuration and selected generators.

This preserves technology independence at the repository level.

The local Pre-baked Registry has a different role. A P. item may intentionally select a prepared, technology-specific capability, for example:

P.docker.postgresql@15.1.23-stable

This distinction keeps reusable Ocean semantics under O. while making local prepared capabilities explicitly recognizable under P..

---

18. Repository vs Ocean-Atlas

The Ocean Repository and Ocean-Atlas serve different purposes.

Ocean Repository

Contains reusable machine-consumable Ocean definitions used to build systems.

Ocean-Atlas

Contains knowledge about Ocean used to understand, document, govern, and evolve the platform.

Conceptually:

Ocean-Atlas
    │
    └── Knowledge about Ocean
        ├── DSL references
        ├── concepts
        ├── guides
        ├── architecture
        └── decisions

Ocean Repository
    │
    └── Reusable Ocean definitions
        ├── datatypes
        ├── expressions
        ├── FSMs
        ├── services
        └── ...

Ocean-Atlas may document the repository, but it is not itself the repository.

---

19. Ecosystem

The Ocean Repository provides the foundation for an ecosystem centered around reusable system definitions.

Important capabilities include:

• Reuse — use existing definitions across systems.
• Composition — build larger systems from smaller definitions.
• Versioning — depend on known versions.
• Discovery — find available definitions.
• Publishing — make definitions available for reuse.
• Validation — ensure repository items conform to Ocean rules.
• Governance — control lifecycle, ownership, and visibility.

These capabilities can evolve independently while retaining the same repository identity model.

---

20. Future Evolution

The repository model may evolve to support additional capabilities such as:

• richer dependency resolution;
• compatibility rules;
• version ranges;
• organization-specific namespaces;
• publishing workflows;
• trust and verification;
• licensing;
• caching and mirrors;
• repository federation;
• dependency graphs.

These capabilities should build on the stable foundation of:

identity + type + namespace + version + DSL definition

For local pre-baked items, the corresponding foundation is:

source + namespace + name + version + consumable contract

---

21. Related Knowledge

The Ocean Repository concept is related to:

• dsl.import — imports selected definitions from the Ocean Repository into a local DSL scope.
• dsl.include — includes reusable definitions from the Ocean Repository.
• dsl.datatype — reusable datatype definitions may be stored in the repository.
• dsl.api — reusable API definitions may be stored in the repository.
• dsl.database — reusable database definitions may be stored in the repository.
• dsl.broker — reusable broker definitions may be stored in the repository.
• dsl.expression — reusable expressions may be stored in the repository.
• dsl.fsm — reusable FSM definitions may be stored in the repository.
• dsl.component — reusable component definitions may be stored in the repository.
• dsl.service — reusable service definitions may be stored in the repository.

These semantic relationships are declared in the document metadata.