Ocean-Atlas Identity and Relationship Standards

• Ocean-Atlas Identity and Relationship Standards
  • Metadata
• 1. Purpose
• 2. Stable Knowledge Identity
• 3. ID Format
• 4. ID Naming Rules
  • 4.1 Lowercase
  • 4.2 Dotted Namespace
  • 4.3 Kebab-Case Within Segments
  • 4.4 Allowed Characters
  • 4.5 Semantic Names
• 5. Namespace Conventions
• 6. ID Immutability
• 7. When an ID May Change
• 8. ID Reuse
• 9. Aliases and Former Names
• 10. ADR and RFC IDs
• 11. Stable References
• 12. Relationship Principles
• 13. Core Relationship Types
  • 13.1 Structural Relationships
  • 13.2 Semantic Relationships
  • 13.3 Evolution Relationships
  • 13.4 Decision Relationships
  • 13.5 Technical Relationships
  • 13.6 Navigation Relationships
  • 13.7 Governance Relationships
• 14. Relationship Directionality
• 15. Inverse Relationships
• 16. Symmetric Relationships
• 17. Relationship Representation
• 18. Relationship Governance
• 19. Relationship Applicability
• 20. Relationship Validation
• 21. Circular Relationships
• 22. Relationship Authority
• 23. Technology Independence
• 24. Examples
  • DSL and Guide
  • Example and DSL
  • Pattern and Concept
  • Architecture and Decision
  • Evolution
  • Tutorial Sequence
• 25. Summary of Core Rules
  • Identity
  • Relationships
• 26. Future Refinement

---

1. Purpose

This document defines the standards for:

• stable knowledge identities;
• knowledge ID naming and lifecycle;
• references between knowledge items;
• typed knowledge relationships;
• relationship directionality;
• relationship governance;
• relationship validation.

These standards implement the identity and relationship principles established by the accepted Ocean-Atlas Knowledge Architecture.

The objective is to ensure that knowledge can be referenced reliably regardless of changes to:

• file names;
• repository structure;
• website URLs;
• page titles;
• presentation technologies;
• storage technologies.

Stable identities and explicit relationships form the foundation for navigation, search, APIs, semantic retrieval, knowledge graphs, RAG, and future AI capabilities.

---

2. Stable Knowledge Identity

Every independently addressable knowledge item must have a globally unique stable ID.

Example:

id: dsl.api

The stable ID represents the identity of the knowledge itself.

It must not be treated as:

• a file path;
• a URL;
• a page title;
• a navigation location.

For example:

Stable ID
dsl.api

Possible file
dsl/api.md

Possible URL
/docs/dsl/api

Possible title
API DSL Reference

The file, URL, and title may change.

The stable ID remains unchanged.

---

3. ID Format

Ocean-Atlas IDs use a hierarchical dotted namespace.

General form:

<namespace>.<identifier>

Examples:

atlas.knowledge-architecture

concept.package

dsl.api

guide.create-service

tutorial.first-ocean-service

pattern.primary-shared-resource

example.todo-rest-api

architecture.compiler

troubleshooting.compiler.unknown-type

Additional namespace levels may be used where they provide meaningful classification.

Example:

troubleshooting.compiler.unknown-type

IDs should remain as short as practical while still being clear and globally unique.

---

4. ID Naming Rules

Stable IDs must follow these rules.

4.1 Lowercase

IDs must use lowercase characters.

Correct:

dsl.api

Incorrect:

DSL.API
Dsl.Api

---

4.2 Dotted Namespace

Dots separate logical namespace segments.

Example:

architecture.generation-pipeline

The namespace expresses logical identity, not physical storage.

The following are independent concepts:

ID:
architecture.generation-pipeline

File:
architecture/generation-pipeline.md

The file may later move while the ID remains unchanged.

---

4.3 Kebab-Case Within Segments

Multi-word segments use kebab-case.

Correct:

guide.create-rest-api
pattern.primary-shared-resource
architecture.generation-pipeline

Incorrect:

guide.create_rest_api
guide.createRestApi
guide.create rest api

---

4.4 Allowed Characters

IDs should use only:

a-z
0-9
-
.

Unless a future standard explicitly introduces additional characters.

Whitespace is not allowed.

---

4.5 Semantic Names

IDs should describe the identity of the knowledge rather than its current title.

Preferred:

concept.package

Avoid unnecessarily presentation-oriented IDs such as:

concept.what-is-a-package

because page titles and presentation styles may change.

---

5. Namespace Conventions

The first segment should normally identify the primary knowledge type or logical namespace.

Initial namespaces include:

atlas
concept
dsl
architecture
guide
tutorial
pattern
example
adr
rfc
troubleshooting
faq
glossary
migration
roadmap

Examples:

concept.service
dsl.integration
architecture.compiler
guide.create-package
pattern.shared-resource

Namespaces must not be introduced arbitrarily.

New top-level namespaces should correspond to a recognized knowledge type or an explicitly governed platform-level namespace.

---

6. ID Immutability

Once a knowledge item is published with a stable ID, that ID must not change merely because:

• the title changes;
• the file is renamed;
• the file moves;
• the website structure changes;
• the navigation hierarchy changes;
• terminology is improved;
• the implementation technology changes.

Example:

Original:

ID:
concept.package

Title:
Ocean Package

Later:

ID:
concept.package

Title:
Reusable Ocean Packages

The ID remains:

concept.package

---

7. When an ID May Change

An ID should change only when the identity of the knowledge itself has fundamentally changed.

A new ID is appropriate when:

• one knowledge item is split into independently meaningful concepts;
• multiple knowledge items are merged into a new canonical concept;
• a concept is replaced by a semantically different concept;
• the previous item is intentionally superseded by a new knowledge item.

In such cases, lifecycle and relationship metadata should preserve the historical connection.

Example:

concept.old-package-model

    superseded-by

concept.package

Renaming alone is not sufficient reason to create a new ID.

---

8. ID Reuse

Stable IDs must never be reused for different knowledge.

If a knowledge item is:

• deleted;
• deprecated;
• superseded;
• archived;

its ID remains permanently associated with that historical knowledge item.

For example:

dsl.legacy-service

must never later be assigned to an unrelated DSL feature.

This prevents broken historical references and semantic ambiguity.

---

9. Aliases and Former Names

Aliases provide alternative human-facing names for a knowledge item.

Example:

id: concept.package
title: Ocean Package
aliases:
  - Reusable Package
  - Ocean Module

Aliases:

• support search and discovery;
• preserve former terminology;
• assist migration;
• do not create additional identities;
• must not be used as relationship targets.

Relationships always reference the stable ID:

concept.package

not an alias.

---

10. ADR and RFC IDs

ADR and RFC identities may use stable numeric identifiers.

Examples:

adr.0019-data-service-database-owner

rfc.0003-package-resolution

The numeric portion provides:

• stable historical sequencing;
• easy human reference;
• compatibility with established ADR/RFC practices.

The descriptive suffix improves readability.

Once assigned, the numeric identifier must not be reused.

Renaming an ADR or RFC title should not require changing its stable ID.

---

11. Stable References

Internal semantic references should use stable IDs wherever practical.

Example:

dsl.package

rather than relying exclusively on:

../dsl/package.md

or:

/docs/dsl/package

The physical implementation may resolve stable IDs into:

• repository links;
• website URLs;
• API resources;
• IDE navigation;
• search results.

This allows physical organization to evolve independently from knowledge identity.

---

12. Relationship Principles

Relationships represent semantic connections between knowledge items.

They are not merely hyperlinks.

For example:

guide.create-package
    --references-->
dsl.package

means that the guide semantically references the canonical package DSL knowledge.

The relationship remains meaningful even if no visible hyperlink is rendered.

Relationships must be:

• explicit;
• typed;
• directional where applicable;
• based on stable IDs;
• machine-readable;
• governed by a controlled vocabulary.

---

13. Core Relationship Types

Ocean-Atlas uses a controlled vocabulary of relationship types.

New relationship types should only be introduced when they represent a distinct semantic meaning that cannot be expressed clearly using an existing relationship.

---

13.1 Structural Relationships

Describe logical containment or hierarchy.

• contains
• contained-by
• parent-of
• child-of

Examples:

concept.api
    --contains-->
concept.api.rest

Structural relationships should represent meaningful knowledge structure rather than reproduce repository folders.

---

13.2 Semantic Relationships

Describe conceptual connections between knowledge items.

• explains
• references
• demonstrates
• example-of
• applies-to
• requires
• related-to

Examples:

guide.create-package
    --references-->
dsl.package

example.todo-rest-api
    --demonstrates-->
dsl.api

pattern.primary-shared-resource
    --applies-to-->
concept.broker

related-to should be used sparingly.

A more specific relationship must be preferred whenever one accurately describes the connection.

---

13.3 Evolution Relationships

Describe how knowledge changes over time.

• supersedes
• superseded-by
• replaces
• deprecated-by
• derived-from

Examples:

architecture.package-resolution-v2
    --supersedes-->
architecture.package-resolution-v1

architecture.package-resolution-v1
    --superseded-by-->
architecture.package-resolution-v2

Evolution relationships are especially important for historical traceability and version-aware retrieval.

---

13.4 Decision Relationships

Connect proposals, decisions, specifications, and implementations.

• proposed-by
• decided-by
• implements-decision
• affected-by

Examples:

architecture.package-resolution
    --decided-by-->
adr.0042-package-resolution

dsl.package
    --affected-by-->
adr.0042-package-resolution

These relationships preserve the rationale behind current knowledge.

---

13.5 Technical Relationships

Describe technical dependencies or implementation-oriented relationships.

• uses
• depends-on
• implements
• extends
• generates
• configures
• integrates-with

Examples:

concept.service
    --uses-->
concept.component

architecture.generator
    --generates-->
concept.artifact

Technical relationships should only be used when the relationship is part of the knowledge being represented.

They should not attempt to reproduce the entire runtime or source-code dependency graph inside Ocean-Atlas.

---

13.6 Navigation Relationships

Support intentional navigation and learning flow.

• see-also
• alternative
• next
• previous

Examples:

tutorial.first-service
    --next-->
tutorial.add-persistence

Navigation relationships do not imply semantic dependency unless another explicit relationship also exists.

---

13.7 Governance Relationships

Describe responsibility and stewardship.

• owned-by
• maintained-by

These relationships may complement ownership metadata when owners or maintainers are represented as addressable Atlas entities.

Simple ownership values may remain metadata when no separate knowledge entity exists.

---

14. Relationship Directionality

Relationships should have a clearly defined direction.

Example:

example.audit-service
    --demonstrates-->
dsl.package

The source is:

example.audit-service

The target is:

dsl.package

Direction must reflect the semantic meaning of the relationship.

---

15. Inverse Relationships

Some relationships naturally have inverse forms.

Examples:

contains
↔
contained-by

parent-of
↔
child-of

supersedes
↔
superseded-by

Ocean-Atlas should avoid requiring contributors to manually maintain both directions when one can be derived reliably.

For example:

architecture.package-v2
    --supersedes-->
architecture.package-v1

may allow Atlas to derive:

architecture.package-v1
    --superseded-by-->
architecture.package-v2

The exact rules for stored versus derived inverse relationships may be implementation-specific.

The semantic result must remain consistent.

---

16. Symmetric Relationships

Some relationships may be symmetric.

For example:

related-to

If:

concept.package
    --related-to-->
concept.service

then the inverse relationship may be interpreted as equivalent.

Symmetry must be defined per relationship type and must not be assumed universally.

---

17. Relationship Representation

A relationship should minimally identify:

• relationship type;
• target stable ID.

Conceptual example:

relationships:
  - type: references
    target: dsl.package

  - type: decided-by
    target: adr.0042-package-resolution

Optional relationship metadata may later include:

• context;
• version applicability;
• source;
• notes.

The exact serialization format may evolve, but the semantic model must remain stable.

---

18. Relationship Governance

Relationship types form a controlled vocabulary.

Contributors must not introduce arbitrary relationship names such as:

kind-of-related-to
works-with
sort-of-uses
associated

when an existing governed relationship expresses the intended meaning.

New relationship types should be introduced only when:

1. no existing relationship accurately represents the semantics;
2. the relationship has a clear reusable meaning;
3. its directionality is defined;
4. its inverse or symmetry behavior is defined;
5. its allowed source and target knowledge types can be described.

---

19. Relationship Applicability

Not every relationship type is valid for every knowledge type.

For example:

An example may:

demonstrate

a DSL reference.

An ADR may:

supersede

another ADR.

A guide may:

require

another guide.

A tutorial may:

next

another tutorial.

However, arbitrary combinations should not automatically be considered valid.

The detailed source/relationship/target applicability matrix may be refined as the knowledge base grows.

The model should avoid excessive restrictions before sufficient real-world content exists.

---

20. Relationship Validation

Ocean-Atlas should eventually validate relationships automatically.

Validation should detect:

• unknown target IDs;
• malformed IDs;
• invalid relationship types;
• duplicate relationships where inappropriate;
• invalid source/target combinations;
• prohibited circular relationships;
• broken lifecycle relationships;
• references to removed knowledge;
• inconsistent inverse relationships where explicitly stored.

Validation may also identify:

• orphaned knowledge;
• missing expected relationships;
• excessive use of generic related-to;
• references to deprecated knowledge where a replacement exists.

---

21. Circular Relationships

Some circular relationships are valid.

Example:

concept.api
    --related-to-->
concept.service

concept.service
    --related-to-->
concept.api

Other cycles may indicate an error.

For example:

A --supersedes--> B
B --supersedes--> A

is invalid.

Cycle rules must therefore be defined by relationship type rather than globally prohibited.

---

22. Relationship Authority

A relationship does not change the authority of the knowledge items it connects.

For example:

example.todo-api
    --demonstrates-->
dsl.api

does not make the example equivalent in authority to the DSL specification.

Consumers such as:

• search;
• APIs;
• RAG;
• AI assistants;

must continue to consider the authority, lifecycle, version, and canonicality of each knowledge item independently.

---

23. Technology Independence

Stable IDs and relationships are part of the logical Ocean-Atlas knowledge model.

They must remain independent of:

• Markdown;
• YAML;
• repository layout;
• website framework;
• relational databases;
• graph databases;
• vector databases;
• search engines;
• API technologies.

A future implementation may store or index identities and relationships differently without changing their semantic meaning.

---

24. Examples

DSL and Guide

guide.create-rest-api
    --references-->
dsl.api

---

Example and DSL

example.todo-rest-api
    --demonstrates-->
dsl.api

---

Pattern and Concept

pattern.primary-shared-resource
    --applies-to-->
concept.broker

---

Architecture and Decision

architecture.package-resolution
    --decided-by-->
adr.0042-package-resolution

---

Evolution

architecture.package-resolution-v2
    --supersedes-->
architecture.package-resolution-v1

---

Tutorial Sequence

tutorial.first-service
    --next-->
tutorial.add-persistence

---

25. Summary of Core Rules

Identity

• Every independently addressable knowledge item has one globally unique stable ID.
• IDs use dotted namespaces and lowercase kebab-case segments.
• IDs are independent of filenames, URLs, titles, and repository paths.
• Published IDs are immutable.
• Retired IDs are never reused.
• Aliases do not create new identities.
• ADRs and RFCs may use stable numeric identifiers.

Relationships

• Relationships represent semantics, not merely hyperlinks.
• Relationships use stable IDs.
• Relationship types use a controlled vocabulary.
• Relationships are directional unless explicitly defined as symmetric.
• Inverse relationships may be derived automatically.
• Generic relationships such as related-to should be used sparingly.
• Relationship applicability may depend on knowledge type.
• Relationships should be machine-validatable.
• Relationship semantics remain independent of storage technology.

---

26. Future Refinement

As real Ocean-Atlas content is introduced, the following may be refined:

• exact namespace registry;
• ID validation grammar;
• ADR and RFC numbering rules;
• relationship source/target applicability matrix;
• inverse relationship rules;
• symmetric relationship rules;
• relationship-specific validation;
• optional relationship metadata;
• physical serialization format.

These refinements must preserve the identity and relationship principles defined by this standard.