Ocean-Atlas Metadata Schema

Ocean-Atlas Metadata Schema

1. Purpose

This document defines the metadata schema for knowledge managed by Ocean-Atlas.

It translates the metadata architecture defined in the accepted knowledge-architecture.md into concrete metadata fields, rules, controlled vocabularies, applicability requirements, and validation expectations.

The schema applies to all independently addressable knowledge items managed by Ocean-Atlas.

2. Metadata Principles

Metadata must be:

explicit where it affects identity, lifecycle, authority, retrieval, or governance;
consistent across knowledge types;
minimal enough to remain maintainable;
machine-readable where practical;
based on controlled vocabularies where consistency is important;
extensible without breaking existing knowledge;
independent of physical file paths and presentation technologies.

Not every metadata field is required for every knowledge type.

Each field is classified as one of:

Required — must exist on every independently addressable knowledge item.
Conditional — required when a defined condition applies.
Optional — may be provided when useful.
Derived — may be generated from source control, build systems, or other authoritative sources rather than maintained manually.

3. Metadata Model

The Ocean-Atlas metadata model includes the following concepts.

Identity and Classification

stable ID
title
knowledge type
domain area

Description and Discovery

summary
tags
aliases or former names
intended audience
language or locale

Lifecycle and Governance

lifecycle status
authority level
owners or maintainers
creation information
modification information
review information
deprecation information
supersession information

Applicability

applicable Ocean version or version range
applicability scope

Trust and Provenance

source or provenance
content origin
canonicality

Access

visibility or access classification

Knowledge Relationships

related knowledge

Relationships are part of the overall knowledge model and may be serialized alongside metadata, but they are treated as first-class typed relationships rather than ordinary descriptive metadata.

4. Field Definitions

`id`

Requirement: Required
Purpose: Stable identity

Example:

id: atlas.knowledge-architecture

The id is the permanent machine identity of a knowledge item.

It must be:

globally unique within Ocean-Atlas;
stable and immutable once published;
independent of filename, path, URL, and title;
suitable for machine references;
never reused for another knowledge item.

Detailed ID conventions are defined separately.

`title`

Requirement: Required
Purpose: Human-readable identity

Example:

title: Ocean-Atlas Knowledge Architecture

The title may change without changing the stable identity of the knowledge item.

`type`

Requirement: Required
Purpose: Knowledge classification
Vocabulary: Controlled

Example:

type: architecture

Initial knowledge types include:

concept
reference
guide
tutorial
pattern
example
architecture
adr
rfc
troubleshooting
faq
glossary
migration-guide
roadmap

The exact controlled vocabulary must remain aligned with the accepted Knowledge Architecture.

`area`

Requirement: Required or controlled by taxonomy
Purpose: Logical domain placement

Example:

area: architecture

The domain area identifies the primary logical knowledge area to which the item belongs.

Initial areas include:

getting-started
concepts
dsl
architecture
guides
tutorials
patterns
examples
decisions
migration
troubleshooting
glossary
roadmap
atlas

The domain area is logical and must not be inferred solely from the physical file path.

`summary`

Requirement: Recommended; may become required for selected knowledge types
Purpose: Discovery and retrieval

Example:

summary: Defines the logical architecture and governing principles of knowledge managed by Ocean-Atlas.

The summary should provide a concise description of the knowledge item’s purpose and content.

It supports:

search results;
previews;
navigation;
AI retrieval;
semantic indexing.

`status`

Requirement: Required
Purpose: Lifecycle state
Vocabulary: Controlled and potentially type-dependent

Example:

status: accepted

Allowed lifecycle states may vary by knowledge type.

Examples include:

draft
review
accepted
approved
rejected
withdrawn
deprecated
superseded
archived

Detailed lifecycle rules are defined in the governance standards.

`authority`

Requirement: Required or strongly recommended depending on knowledge type
Purpose: Trust and retrieval priority
Vocabulary: Controlled

Example:

authority: normative

Authority indicates how strongly the knowledge should be trusted or followed.

Possible categories may include:

normative
authoritative
guidance
informational
illustrative
proposed
historical

The exact vocabulary must be finalized separately.

Lifecycle and authority are distinct:

status describes where an item is in its lifecycle;
authority describes how strongly its content should be treated.

`appliesTo`

Requirement: Conditional
Purpose: Version applicability

Example:

appliesTo:
  ocean: ">=2.0"

This field identifies the Ocean version or version range to which the knowledge applies.

It must not be confused with the version of the knowledge item itself.

Version applicability may be omitted when the knowledge is version-independent.

`scope`

Requirement: Conditional
Purpose: Applicability boundaries

Example:

scope:
  - compiler
  - ocean-lab

Applicability scope identifies where the knowledge applies when version information alone is insufficient.

Possible scopes may include:

ecosystem;
product;
component;
runtime;
DSL section;
package;
environment;
deployment target.

The detailed representation requires further definition.

`audience`

Requirement: Conditional or optional
Purpose: Intended consumers

Example:

audience:
  - users
  - contributors
  - architects

Audience metadata helps tailor navigation, search, and retrieval.

A controlled vocabulary should be used where practical.

`tags`

Requirement: Optional
Purpose: Secondary classification and discovery

Example:

tags:
  - knowledge-model
  - governance

Tags must supplement, not replace:

type;
area;
relationships.

Uncontrolled tag growth should be avoided.

`aliases`

Requirement: Optional
Purpose: Alternative and historical terminology

Example:

aliases:
  - Knowledge Model Architecture
  - Atlas Knowledge Model

Aliases support:

search;
renamed concepts;
historical terminology;
migration from former names.

Aliases do not change the canonical title or stable ID.

`owners`

Requirement: Required or conditional
Purpose: Governance responsibility

Example:

owners:
  - Ocean-Atlas

Ownership identifies the logical person, team, project, or domain responsible for the knowledge.

`maintainers`

Requirement: Optional or conditional
Purpose: Operational maintenance responsibility

Example:

maintainers:
  - Ocean Architecture Team

The owner and maintainer may differ.

Owner represents accountability.
Maintainer represents day-to-day responsibility for updates.

`created`

Requirement: Required or derived
Purpose: Creation history

Example:

created: 2026-07-17

The creation date may be maintained explicitly or derived from an authoritative source such as version control.

`updated`

Requirement: Required or derived
Purpose: Modification history

Example:

updated: 2026-07-19

The last meaningful content modification date should be distinguishable from incidental repository changes where possible.

`review`

Requirement: Conditional
Purpose: Review governance

Possible information includes:

review:
  status: approved
  reviewedBy:
    - Ocean Architecture
  reviewedAt: 2026-07-19

Review metadata should only be required for knowledge types governed by an explicit review process.

The exact structure belongs to the governance standard.

`deprecation`

Requirement: Conditional
Purpose: Lifecycle transition

Example:

deprecation:
  deprecatedAt: 2027-01-10
  reason: Replaced by the new package resolution model.

Deprecation metadata is required when status: deprecated.

It may include:

date;
reason;
migration guidance;
replacement reference.

`supersession`

Requirement: Conditional
Purpose: Knowledge evolution

Example:

supersededBy:
  - architecture.package-resolution-v2

Supersession metadata identifies replacement knowledge.

Supersession should use stable IDs.

The inverse relationship, such as supersedes, may be derived or explicitly represented depending on the relationship model.

`provenance`

Requirement: Conditional or recommended
Purpose: Trust, traceability, and attribution

Example:

provenance:
  source: Ocean architecture repository

Provenance identifies where the knowledge originated or what evidence supports it.

This is especially important for:

imported content;
generated knowledge;
derived knowledge;
externally sourced material;
AI-assisted or automated ingestion.

`origin`

Requirement: Recommended
Purpose: Content production classification
Vocabulary: Controlled

Example:

origin: manually-maintained

Initial values may include:

manually-maintained
generated
imported
derived

Additional values should only be added deliberately.

`canonicality`

Requirement: Recommended
Purpose: Identify the canonical role of the item
Vocabulary: Controlled

Example:

canonicality: canonical

Possible values may include:

canonical
summary
derived

Canonicality helps distinguish the authoritative representation of knowledge from summaries or generated derivatives.

This concept must remain distinct from authority:

authority describes how strongly the content should be trusted;
canonicality describes whether this item is the primary representation of that knowledge.

`language`

Requirement: Optional, with a default
Purpose: Localization

Example:

language: en

The default language may be defined globally, avoiding repetition on every page.

Locale-specific knowledge may use a more specific value, for example:

language: en-GB

`visibility`

Requirement: Conditional; default may be inherited
Purpose: Access classification
Vocabulary: Controlled

Example:

visibility: public

Possible values may include:

public
internal
restricted

Visibility must only be used where access classification is relevant.

`related`

Requirement: Optional or type-dependent
Purpose: Knowledge relationships

Example:

related:
  - type: implements
    target: adr.0019-data-service-database-owner

Related knowledge must use typed relationships and stable IDs.

Relationships are governed by the dedicated relationship standard and should not be treated as arbitrary hyperlinks.

5. Metadata Classification Summary

Metadata	Initial Classification
Stable ID	Required
Title	Required
Knowledge type	Required
Domain area	Required
Summary	Recommended / type-dependent
Lifecycle status	Required
Authority level	Required or type-dependent
Applicable Ocean version/range	Conditional
Applicability scope	Conditional
Intended audience	Conditional / optional
Tags	Optional
Aliases / former names	Optional
Owner	Required
Maintainer	Optional / conditional
Related knowledge	Optional / type-dependent
Creation information	Required or derived
Modification information	Required or derived
Review information	Conditional
Deprecation information	Conditional
Supersession information	Conditional
Source / provenance	Conditional / recommended
Content origin	Recommended
Canonicality	Recommended
Language / locale	Optional with default
Visibility / access classification	Conditional with default

This classification is preliminary and must be refined by knowledge type before the metadata schema is considered complete.

6. Next Step

The next step is to define the exact applicability matrix:

Metadata Field × Knowledge Type

For example:

                 Architecture  ADR  Guide  Tutorial  DSL Reference  Glossary
id                    R         R     R       R            R           R
title                 R         R     R       R            R           R
status                R         R     R       R            R           R
version               ?         ?     ?       ?            ?           ?
authority             ?         ?     ?       ?            ?           ?
...

Where:

R = Required
C = Conditional
O = Optional
D = Derived

That matrix should determine the final rules instead of making every field mandatory for every knowledge type.