Overview

OkfParsingLibrary implements Google Cloud's Open Knowledge Format (OKF) v0.2 specification for OutSystems Developer Cloud. OKF represents data and analytics assets as Markdown files with YAML frontmatter, organised into linked bundles of concepts.

This library handles parsing and serialisation only. It reads OKF bundles into structured data and writes structured data back out as conformant OKF files. It does not store anything or decide anything about trust or status, that's the job of an app built on top of it, such as OKF Store.

Design principles

• Never throws. Every action reports failure through its own result field (ParseError or Message), never an exception. No try/catch needed anywhere.
• Stateless. No persistence, no HTTP calls, no dependencies beyond the OutSystems SDK. Output depends only on input.
• Lossless. Frontmatter keys outside the documented OKF fields round-trip through ExtraJson instead of being dropped.

Installation

Via Forge (recommended): click Install on this page. ODC handles everything.

From a release package: download OkfParsingLibrary-ODC.zip from the latest GitHub release and upload it in ODC Portal under External Logic > Upload.

From source: the library targets net10.0 and builds with the standard .NET SDK. See the repository README for exact commands.

Actions

UnzipBundle — Extracts every .md entry from a zip archive.

• archive (Binary Data): the zip file's raw bytes
• Returns Files: a list of OkfFileEntry
• A corrupt or empty zip yields an empty list, never an error
• A single shared top-level wrapper folder is stripped automatically

BuildBundleArchive — Builds a zip archive from a list of files.

• filesJson (Text): a JSON array of {"path": "...", "content": "..."} objects
• Returns Archive (Binary Data)
• Has no awareness of OKF structure, packs whatever it's given

SplitFrontmatter — Splits a concept file into its frontmatter block and body.

• fileContent (Text): the full raw file content
• Returns a FrontmatterSplitResult
• No frontmatter is not an error: HasFrontmatter is false, Body holds the whole file
• Only an unterminated block sets ParseError

ParseFrontmatter — Parses an OKF v0.2 frontmatter block.

• frontmatterRaw (Text): raw YAML between the --- delimiters
• Returns a ParsedFrontmatter
• A malformed construct sets ParseError, but every field parsed before that point stays populated

ExtractLinks — Extracts markdown inline links from a concept body.

• body (Text)
• Returns Links: a list of LinkRef
• Excludes image syntax and external http/https/mailto links
• Classifies each link as bundle-absolute, relative, or cross-bundle (okf://)

ExtractBodySection — Returns the content under a given heading.

• body (Text), heading (Text): heading text without # characters
• Returns SectionContent (Text)
• Empty text if the heading isn't found

ParseCitationsSection — Parses a legacy v0.1 # Citations block.

• citationsBlock (Text)
• Returns SourcesJson (Text): matching ParsedFrontmatter.SourcesJson
• Non-matching lines are skipped, not errors

SerializeConcept — Serialises frontmatter fields plus body into a complete Markdown file.

• conceptJson (Text): mirrors ParsedFrontmatter field names plus a body string
• Returns MarkdownFile (Text)
• Empty fields are omitted, not written blank
• Guarantees an equivalent parse result, not byte-identical output

ValidateConformance — Runs SPEC conformance checks against a set of files.

• files (List of OkfFileEntry)
• Returns Issues: a list of ConformanceIssue
• Checks only SPEC-9.1, SPEC-9.2, SPEC-4.1, and SPEC-6

Structures

OkfFileEntryOS — Path, Content, ReservedKind ("", "index", or "log")

FrontmatterSplitResultOs — HasFrontmatter, FrontmatterRaw, Body, ParseError

ParsedFrontmatterOs — Type, Title, Description, Resource, TagsCsv, Status, StaleAfter, GeneratedBy, GeneratedAt, LegacyTimestamp, OkfVersion, VerifiedJson, SourcesJson, ExtraJson, ParseError

LinkRefOS — LinkText, RawPath, IsCrossBundle, TargetBundleName, TargetPath

ConformanceIssueOS — FilePath, Severity ("error" or "warning"), Rule, Message

Support

Source and issues are on the library's GitHub repository, linked from this listing.