Ocean-Atlas

1. Overview

Ocean-Atlas is the canonical knowledge base for the Ocean platform and its domain-specific language.

It contains:

• normative DSL references;
• supporting DSL catalogs;
• foundational concepts;
• shared syntax and metadata rules;
• relationships between language constructs;
• guidance for understanding and evolving Ocean.

Ocean-Atlas documents the language and platform. It is distinct from the Ocean Repository, which contains reusable machine-consumable Ocean definitions.

---

2. Start Here

Document	ID	Purpose
Ocean DSL	concept.ocean-dsl	Introduces the purpose, structure, and principles of the Ocean language
Ocean Repository	concept.ocean-repository	Defines reusable Ocean items and the O. and P. reference model
Control Structure	concept.control-structure	Explains how services, components, FSMs, and expressions work together
Metadata	dsl.metadata	Defines shared metadata available across Ocean definitions

---

3. DSL Reference Catalog

Most entries below are top-level DSL sections declared through an @<section> header. The user-interface family also includes the nested Widget construct and its supporting predefined-type catalog; their kind is identified explicitly.

Project and shared models

Section	ID	Status	Purpose
@info	dsl.info	Approved	Declares project-level name, version, and description
@datatype	dsl.datatype	Approved	Defines reusable types, fields, enums, and type relationships
@context	dsl.context	Approved	Defines typed contextual information available to supported runtime scopes
@config	dsl.config	Approved	Defines reusable typed runtime-configuration schemas
@vault	dsl.vault	Approved	Defines logical vaults and typed secret schemas

Interfaces and infrastructure

Section	ID	Status	Purpose
@api	dsl.api	Approved	Defines typed API contracts and operations
@broker	dsl.broker	Approved	Defines brokers, topics, and messaging patterns
@database	dsl.database	Approved	Defines database models, entities, queries, and commands
@integration	dsl.integration	Approved	Provides the placeholder for the canonical Ocean integration-item definition

Behavior and composition

Section	ID	Status	Purpose
@expression	dsl.expression	Approved	Defines reusable stateless and side-effect-free logic
@fsm	dsl.fsm	Approved	Defines stateful behavior using states, events, and transitions
@component	dsl.component	Approved	Defines stateless composition of FSMs, expressions, and nested components
@service	dsl.service	Approved	Defines deployable orchestration boundaries and system connections

User interfaces

Construct	ID	Kind	Status	Purpose
@dashboard	dsl.dashboard	Section	Approved	Defines reusable backend-agnostic pages composed of widgets
Widget	dsl.widget	Nested construct	Approved	Defines named UI building blocks inside dashboards
Predefined Widget Types	dsl.widget-predefined-types	Supporting reference	Approved	Defines built-in widget types, properties, defaults, and functions
@ui	dsl.ui	Section	Approved	Defines deployable presentation services and backend wiring

The presentation hierarchy is:

@ui
└── uses @dashboard
    └── contains Widget
        └── uses predefined widget types

Deployment

Section	ID	Status	Purpose
@deploy	dsl.deploy	Approved	Defines environment-specific deployment materialization

---

4. DSL Directives

Directives extend the scope or materialization behavior of a DSL file. They are not independent top-level section types.

Directive	ID	Status	Scope extended	Purpose
@import	dsl.import	Approved	Dependency scope	Imports a selected reusable definition under a local alias
@include	dsl.include	Approved	Model scope	Statically composes a compatible same-section definition
@asset	dsl.asset	WIP	Filesystem scope	Materializes an opaque external file without semantic transformation
@artifact	dsl.artifact	Approved	Materialization scope	Interprets, transforms, and materializes a typed semantic file

Conceptually:

@import   → selected reusable definition
@include  → complete compatible DSL section
@asset    → opaque external file
@artifact → type-aware external semantic file

---

5. Concepts

Concept documents explain cross-cutting Ocean models that span multiple DSL references.

Concept	ID	Status	Purpose
Ocean DSL	concept.ocean-dsl	Approved	Defines the language’s purpose, organization, and core principles
Ocean Repository	concept.ocean-repository	Approved	Defines reusable-definition sources, identity, versioning, publishing, and discovery
Control Structure	concept.control-structure	Approved	Defines the roles of services, components, FSMs, and expressions

---

6. Reusable References

Ocean uses two qualified reference spaces:

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

Where:

• O. identifies a reusable item from the Ocean Repository;
• P. identifies a local Pre-baked item;
• namespace provides the item’s logical hierarchy;
• name identifies the item;
• version selects its version.

The source prefix is part of the item’s identity. Complete semantics are defined by concept.ocean-repository.

---

7. Behavioral Composition

Ocean separates deployment, composition, state, and stateless logic:

Service     → deployable orchestration boundary
Component   → stateless behavioral composition
FSM         → stateful behavior and transitions
Expression  → stateless logic and transformation

See Control Structure for the complete model.

---

8. Presentation Composition

Ocean UI definitions are composed as follows:

@ui
  ├── technology and configuration
  ├── navigation and page chrome
  ├── uses @dashboard
  │       └── contains Widget
  └── connects widget functions to APIs and brokers

Relevant references:

• dsl.ui;
• dsl.dashboard;
• dsl.widget;
• dsl.widget-predefined-types.

---

9. Deployment Model

Logical deployable definitions and environment-specific deployment are separate:

@service / @ui / @broker
             │
             ▼
          @deploy
             │
             ▼
orchestrator and runtime artifacts

See dsl.deploy for replicas, configuration bindings, ports, environment values, volumes, dependencies, brokers, and deployment connections.

---

10. File Structure

An Ocean DSL file uses one top-level section header:

@<section>

Examples:

@datatype

@service

@deploy

Section parameters or metadata may be supported where defined by the applicable reference.

---

11. File Extensions

Recognized Ocean DSL file extensions include:

.ace
.ocean
.ocn

The canonical extension for a project may be narrowed by tooling or repository conventions.

---

12. Case Sensitivity

Ocean DSL keywords, identifiers, names, types, properties, aliases, and references are case-sensitive unless a specific reference explicitly states otherwise.

For example:

OrderService ≠ orderService
Table        ≠ table
Submit       ≠ submit

Authors should use the exact casing defined by the applicable DSL contract.

---

13. Comments

Comments begin with # and continue to the end of the line.

Full-line comment:

# Route newly created orders into the workflow.

End-of-line comment:

connect api.createOrder -> flow.create  # Start the order flow.

# inside a quoted string is treated as literal content:

url: "https://example.com/#/reset"  # Valid comment after the value.

Inline comments inserted between tokens and multi-line block comments are not supported.

---

14. Document Authority

Ocean-Atlas uses document metadata to communicate authority and maturity.

Current status convention:

• all established DSL references and concepts are Approved;
• dsl.asset remains WIP.

Normative DSL references govern syntax, validation, and semantics for their constructs. Concept documents explain cross-cutting models without replacing the normative grammar.

---

15. Suggested Reading Paths

Learning the language

1. Ocean DSL
2. Metadata
3. Datatype
4. Import and Include
5. Control Structure
6. Expression, FSM, Component, and Service

Building backend systems

1. Datatype
2. API, Broker, and Database
3. Expression, FSM, and Component
4. Service
5. Config and Vault
6. Deploy

Building user interfaces

1. Datatype
2. Widget and Predefined Widget Types
3. Dashboard
4. UI
5. Config
6. Deploy

---

16. Canonical Inventory

DSL IDs

dsl.info
dsl.metadata
dsl.datatype
dsl.context
dsl.config
dsl.vault
dsl.api
dsl.broker
dsl.database
dsl.integration
dsl.expression
dsl.fsm
dsl.component
dsl.service
dsl.dashboard
dsl.widget
dsl.widget-predefined-types
dsl.ui
dsl.deploy
dsl.import
dsl.include
dsl.asset
dsl.artifact

Concept IDs

concept.ocean-dsl
concept.ocean-repository
concept.control-structure

---

17. Maintenance

When adding or changing an Ocean-Atlas document:

• assign a stable ID;
• place DSL contracts in dsl/;
• place cross-cutting concepts in concepts/;
• declare semantic relationships in metadata;
• link the document from this index;
• avoid legacy numeric filename prefixes;
• keep examples aligned with the implemented grammar;
• distinguish implemented rules from future considerations;
• update related documents when an ID or contract changes.