Elyra.DotNet

Elyra.DotNet is the .NET implementation of the Elyra document layer.

Elyra is intended as a document-centered format and library for self-describing, versioned, format-agnostic documents. The current implementation focuses on the lowest layer: a single Elyra document as the source of truth, including metadata, source content, hashes, revision information, generated views and validation.

This repository does not define a CMS, editor, publishing system or rendering framework. Those can be built on top of Elyra, but they are intentionally outside the core library.

Current status

The current implementation supports the basic v0.1 document lifecycle:

• create a plain-text Elyra document
• normalize source content
• calculate canonical source hashes
• calculate source state hashes
• generate a plain text view
• validate document consistency
• serialize and deserialize JSON
• read and write .edf files as UTF-8 without BOM and LF line endings
• read and write streams
• update source content with revision increment
• regenerate generated views without changing the revision
• register content adapters
• prepare schema migration through a migration pipeline skeleton

The currently supported built-in source format is:

plain-text/1.0

Additional source formats are expected to be implemented through content adapters.

Document model

An Elyra document contains a canonical editable source and optional generated views.

Conceptually:

source
  canonical editable content

views
  generated representations, such as plain text

revision
  current document revision and source hash binding

compatibility
  minimum reader/schema compatibility information

extensions
  preserved or custom data

The source is the truth. Generated views must be treated as derived data and can become stale when the source changes.

Minimal example

using Elyra.ContentAdapters;
using Elyra.Serialization;
using Elyra.Validation;

var factory = new ElyraDocumentFactory();
var writer = new ElyraDocumentWriter();
var reader = new ElyraDocumentReader();
var validator = new ElyraDocumentValidator();

var document = factory.CreatePlainTextDocument(
    documentId: "doc_hello",
    content: "Hello Elyra.",
    revisionId: "rev_1");

var validation = validator.Validate(document);

if (!validation.IsValid)
{
    throw new InvalidOperationException("Document is not valid.");
}

writer.WriteFile("hello.edf", document);

var loaded = reader.ReadFile("hello.edf");

Console.WriteLine(loaded.Source.Content);

Updating a document

Updating the source creates a new document instance with:

• normalized source content
• recalculated hashes
• incremented revision number
• updated revision hash bindings
• regenerated plain text view

using Elyra.ContentAdapters;

var updater = new ElyraDocumentUpdateService();

var updated = updater.UpdateSourceContent(
    document,
    "Hello Elyra.\nThis document was updated.",
    revisionId: "rev_2");

Changing the source content is a revision-relevant operation.

Regenerating views

Generated views can be regenerated without changing the source or revision.

using Elyra.ContentAdapters;

var viewService = new ElyraGeneratedViewService();

var regenerated = viewService.RegenerateTextView(document);

This is useful when a generated view is stale, missing or was produced by an older generator.

Regenerating a view does not repair invalid source hashes. If the source hash is wrong, the document is invalid and should be treated as such.

Reading with validation

ElyraDocumentReader validates documents by default.

var reader = new ElyraDocumentReader();

var document = reader.ReadFile("hello.edf");

For detailed validation information:

var result = reader.ReadFileDetailed(
    "hello.edf",
    new ElyraDocumentReadOptions
    {
        Validate = true,
        ThrowOnValidationError = false
    });

Console.WriteLine(result.Validation.IsValid);

Content adapters

Elyra is format-agnostic. Source formats are supported through adapters.

The built-in default registry currently includes:

plain-text/1.0

A host application can register additional adapters:

var registry = ElyraContentAdapterRegistry.CreateDefault();

registry.Register(new MyCustomContentAdapter());

var factory = new ElyraDocumentFactory(registry);

Adapters are responsible for source-format-specific behavior such as:

• normalization
• plain text extraction
• roundtrip capability
• format-specific diagnostics

The Elyra core does not know or own every possible content format.

Plain text and generated views

Plain text is stored as a generated view, not as the canonical source unless the source content type itself is plain-text.

For a plain-text source, the generated text view will usually match the source content. For richer formats such as HTML, Confluence storage XHTML or future Elyra languages, the text view will be extracted from the canonical source.

Storage rules

Native Elyra file output follows these storage rules:

Encoding: UTF-8 without BOM
Line endings: LF
Unicode normalization for source content: NFC
Hashing: SHA-256 over canonical UTF-8 source content

Legacy encodings and original import bytes are not native Elyra storage. They should be represented as import/origin metadata in future extensions.

Migration

The repository contains a migration pipeline skeleton.

Current schema version:

0.1

Since only v0.1 currently exists, no real migration steps are implemented yet. The migration pipeline exists as the designated location for future schema-version transitions.

Language and adapter strategy

The existing Elyra PoC Markdown syntax from earlier Eltheon/DemoCMS experiments should be treated as an experimental content type, for example:

elyra-poc-markdown/0.1

It is not the final Elyra language.

A future native Elyra authoring language should be designed separately and implemented as its own optional project/package when its syntax and role are clear.

Recommended separation:

Elyra.ContentAdapters.PocMarkdown
  Experimental adapter for the old PoC syntax.

Elyra.Language.<FinalName>
  Future native Elyra authoring language.

Neither should be required by Elyra.Core.

Scope boundaries

Elyra.DotNet currently focuses on the document layer.

In scope:

• document model
• source metadata
• hashing
• canonicalization
• validation
• generated views
• serialization
• content adapter contracts
• migration preparation

Out of scope for the core:

• CMS behavior
• editor UI
• publishing pipelines
• rendering frameworks
• Eltheon integration
• database storage
• search indexing infrastructure
• embedding storage

Those can be implemented as separate host integrations or optional packages.

Sample

The repository includes a basic console sample:

dotnet run --project .\samples\Elyra.Samples.BasicConsole\Elyra.Samples.BasicConsole.csproj

The sample demonstrates:

• document creation
• validation
• file writing
• file reading
• source update
• generated view regeneration
• writing an updated .edf file

Build and test

dotnet build .\Elyra.DotNet.slnx
dotnet test .\Elyra.DotNet.slnx