Ocean-Atlas Validation Rules

Ocean-Atlas Validation Rules

1. Purpose

This document defines the validation rules for knowledge managed by Ocean-Atlas.

The objective is to ensure that knowledge remains:

structurally consistent;
correctly identified;
properly classified;
internally connected;
lifecycle-consistent;
searchable and machine-readable;
suitable for future automation, search, knowledge graphs, RAG, and AI-assisted use.

Validation rules define what can and should be checked. Their implementation may initially be manual and later automated.

2. Validation Principles

Ocean-Atlas validation follows these principles:

Validate rules that protect knowledge integrity.
Prefer deterministic rules that can eventually be automated.
Avoid excessive validation that prevents useful contribution.
Distinguish structural validity from content quality.
Validate knowledge relationships across the repository, not only individual files.
Validation technology must remain independent of the logical rules defined here.

A document passing automated validation does not necessarily mean its content is correct or complete.

Human review remains necessary for semantic quality.

3. Validation Severity

Validation findings should use consistent severity levels.

Error

An error represents a violation that makes the knowledge structurally invalid or unsafe to accept.

Examples:

missing required metadata;
duplicate stable ID;
malformed stable ID;
unknown required controlled value;
relationship to a nonexistent target;
invalid lifecycle transition.

Errors must be resolved before knowledge can become Accepted or Approved.

Warning

A warning identifies a likely quality, consistency, or maintainability problem that may still be valid.

Examples:

missing recommended metadata;
excessive use of related-to;
reference to deprecated knowledge;
missing recommended relationship;
unusually large document.

Warnings should be reviewed but do not always block acceptance.

Information

Informational findings provide non-blocking observations or improvement suggestions.

Examples:

optional metadata could improve discovery;
a document may benefit from additional relationships;
an alias may improve searchability.

4. Metadata Validation

Every independently addressable knowledge item must comply with the Metadata Schema.

Validation should check:

required fields are present;
field names are valid;
values use the expected format;
controlled fields use allowed values;
conditional fields exist when their conditions apply;
dates use the defined format;
version declarations use the defined version format;
metadata values are internally consistent.

Example:

status: deprecated

may require corresponding deprecation information.

Unknown metadata fields should produce a warning or error according to the extensibility rules of the Metadata Schema.

5. Stable ID Validation

Every independently addressable knowledge item must have exactly one stable ID.

Validation must ensure that IDs are:

globally unique;
syntactically valid;
lowercase;
composed only of allowed characters;
correctly namespace-qualified;
not reused from retired knowledge.

Example of a valid ID:

dsl.api

Invalid examples:

DSL.API
dsl/api
dsl.Api

Repository-wide validation is required to detect duplicate IDs.

6. Knowledge Type Validation

The declared knowledge type must:

exist in the controlled knowledge-type vocabulary;
use the appropriate metadata requirements;
follow the applicable lifecycle;
use the appropriate template expectations where defined.

Example:

type: glossary-entry

must follow the rules applicable to Glossary Entry knowledge.

Unknown knowledge types must not be introduced without governance approval.

7. Lifecycle Validation

Lifecycle state must be valid for the knowledge type.

Validation should detect:

unsupported status values;
invalid lifecycle transitions;
missing required review information;
accepted or approved knowledge with unresolved blocking errors;
deprecated knowledge without required deprecation information;
superseded knowledge without a valid replacement relationship.

Example of an invalid lifecycle relationship:

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

Lifecycle history should remain traceable where required by governance.

8. Relationship Validation

Every explicit relationship must contain:

a valid relationship type;
a valid target stable ID.

Validation should detect:

unknown relationship types;
malformed target IDs;
nonexistent targets;
prohibited source-target combinations;
invalid cycles;
duplicate relationships where inappropriate;
inconsistent explicitly stored inverse relationships.

Generic relationships such as:

related-to

may generate a warning when a more precise relationship type appears appropriate.

9. Reference Validation

Internal references should resolve to valid knowledge or repository resources.

Validation should detect:

broken internal links;
unknown stable IDs;
missing referenced files;
missing anchors where explicitly referenced;
references to removed knowledge.

References to deprecated or superseded knowledge may generate a warning when a current replacement exists.

External links may be checked separately because availability is outside Ocean-Atlas control.

10. Version and Applicability Validation

Where version or applicability metadata is used, validation should ensure that:

version syntax is valid;
ranges are valid;
source and target versions are distinguishable where required;
migration guides identify meaningful source and target states;
version-specific content does not contradict declared applicability.

Knowledge without version restrictions should not be assumed version-specific solely because of repository location.

11. Content Structure Validation

Where a knowledge type has a standard template, validation may check for required structural elements.

Examples:

exactly one top-level title;
metadata appears near the beginning of the document;
required sections exist;
heading hierarchy is valid;
template placeholders have been removed.

Accepted or approved knowledge must not contain unresolved placeholders such as:

<owner>
<YYYY-MM-DD>
<stable-id>
<Describe...>

Optional template sections may be omitted when not applicable.

12. Terminology and Naming Validation

Where controlled terminology exists, validation should encourage consistent usage.

Validation may detect:

deprecated terminology;
known former names used as canonical terms;
invalid filename conventions;
invalid namespace conventions;
inconsistent capitalization of Ocean-specific terms.

Terminology validation should avoid attempting to enforce general writing quality mechanically.

13. Asset and Diagram Validation

Referenced local assets should exist.

Validation may check:

missing image files;
invalid asset paths;
missing alternative text;
malformed Mermaid diagrams;
unsupported asset types.

Essential knowledge should not exist only inside an image.

Semantic correctness of diagrams generally requires human review.

14. Example Validation

Structured Ocean examples may contain:

multiple DSL directories;
DSL files;
artifact code;
configuration;
supporting resources.

Validation should ensure, where practical, that:

documented files exist;
referenced DSL files are valid;
example structure matches its documentation;
generated or executable examples can be validated using the appropriate Ocean tooling;
examples do not reference missing resources.

Where supported, examples should eventually participate in automated regression validation against compatible Ocean versions.

This helps prevent documentation examples from silently becoming obsolete.

15. Supersession and Deprecation Validation

When knowledge is superseded:

the replacement target must exist;
the replacement should be current or intentionally pending;
circular supersession is prohibited;
stable historical identity must be preserved.

When knowledge is deprecated:

the reason should be provided;
replacement knowledge should be identified when one exists;
migration guidance should be referenced when necessary.

Search and retrieval systems should be able to distinguish current knowledge from deprecated and superseded knowledge.

16. Repository-Wide Validation

Some rules cannot be validated at the individual file level.

Repository-wide validation should eventually detect:

duplicate stable IDs;
orphaned relationship targets;
invalid relationship graphs;
supersession cycles;
inconsistent inverse relationships;
missing canonical targets;
broken cross-document references;
duplicate or conflicting canonical knowledge;
knowledge with no meaningful discoverability path.

Not every isolated knowledge item is invalid.

Orphan detection should therefore produce findings based on knowledge type and context rather than applying a universal prohibition.

17. Human Review

Some qualities cannot be reliably validated automatically.

Human review remains responsible for evaluating:

factual correctness;
architectural correctness;
semantic consistency;
clarity;
completeness;
usefulness;
appropriateness of examples;
quality of explanations;
validity of architectural trade-offs;
whether relationships accurately represent meaning.

Automated validation supports review; it does not replace it.

18. Validation Timing

Validation should occur at appropriate stages of the contribution workflow.

Recommended flow:

Create or Modify
      ↓
Local / Author Validation
      ↓
Repository Validation
      ↓
Review
      ↓
Acceptance / Approval

As tooling evolves, validation may run:

during authoring;
in Ocean-Lab;
before commits;
during pull requests;
in CI/CD;
during Atlas indexing.

The same logical validation rules should apply regardless of where they are executed.

19. Validation Extensibility

Validation rules will evolve as Ocean-Atlas grows.

New rules may be introduced when they:

protect knowledge integrity;
enforce an accepted standard;
prevent recurring defects;
improve reliable machine consumption.

Validation rules must not silently redefine the knowledge model.

Changes that affect identity, metadata, lifecycle, relationships, or other foundational semantics must first be reflected in the corresponding governing standard.

20. Technology Independence

These rules define what must be validated, not how validation is implemented.

Validation may eventually be implemented using:

repository scripts;
Ocean tooling;
CI/CD pipelines;
schema validators;
Markdown tooling;
graph validation;
custom Atlas services.

The validation model must remain independent of any specific implementation technology.

21. Summary

Ocean-Atlas validation operates at multiple levels:

Knowledge Item
    │
    ├── Metadata
    ├── Identity
    ├── Type
    ├── Lifecycle
    ├── Structure
    └── Content references

Repository
    │
    ├── ID uniqueness
    ├── Relationships
    ├── Supersession
    ├── Cross-references
    └── Knowledge consistency

Human Review
    │
    ├── Correctness
    ├── Meaning
    ├── Clarity
    └── Quality

The objective is not merely to validate Markdown files, but to preserve the integrity of the Ocean-Atlas knowledge model as the platform grows.