ExOKF.Concept (ex_okf v0.1.0)

A single OKF concept document (OKF §4).

The concept ID is the file path within the bundle with the .md suffix removed (OKF §2). Unknown frontmatter keys are preserved in meta for lossless round-trips.

Fields

Field	Type	Description
`id`	`String.t()`	Stable concept identifier — path without `.md`. Example: `"tables/orders"`.
`path`	`String.t()`	Bundle-relative file path. Example: `"tables/orders.md"`.
`type`	`String.t() \| nil`	Required by OKF. Kind of concept, e.g. `"BigQuery Table"`, `"Playbook"`. Open vocabulary.
`title`	`String.t() \| nil`	Human-readable display name. Example: `"Customer Orders"`.
`description`	`String.t() \| nil`	One-line summary for indexes and search snippets.
`resource`	`String.t() \| nil`	Canonical URI of the underlying asset (console URL, API, etc.).
`tags`	`[String.t()]`	Cross-cutting labels. Example: `["sales", "orders"]`.
`timestamp`	`String.t() \| nil`	ISO 8601 last-modified time. Example: `"2026-05-28T14:30:00Z"`.
`meta`	`map()`	Producer extension keys (string keys). Example: `%{"owner" => "data-eng"}`.
`body`	`String.t()`	Markdown body after the frontmatter fence.
`links`	`[ExOKF.Link.t()]`	Links extracted from `body`.
`raw_frontmatter`	`String.t() \| nil`	Original YAML text between fences when available (for lossless tooling).

Example

%ExOKF.Concept{
  id: "tables/orders",
  path: "tables/orders.md",
  type: "BigQuery Table",
  title: "Orders",
  description: "One row per completed customer order.",
  resource: "https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders",
  tags: ["sales", "orders"],
  timestamp: "2026-05-28T00:00:00Z",
  meta: %{"sla_minutes" => 30},
  body: "# Schema\n\n| Column | Type |\n",
  links: [
    %ExOKF.Link{
      text: "customers",
      target: "/tables/customers.md",
      kind: :internal,
      concept_id: "tables/customers",
      source_path: "tables/orders.md"
    }
  ],
  raw_frontmatter: "type: BigQuery Table\ntitle: Orders\n"
}

Summary

Types

t()

An OKF concept.

Functions

display_title(concept)

Returns a display title for the concept.

from_parsed(rel_path, frontmatter, body, links \\ [], raw_frontmatter \\ nil)

Builds a concept from a relative path and parsed frontmatter/body.

frontmatter_map(c)

Returns a frontmatter map suitable for serialization.

known_fields()

Returns the known OKF frontmatter field names as atoms.

Types

t()

@type t() :: %ExOKF.Concept{
  body: String.t(),
  description: String.t() | nil,
  id: String.t(),
  links: [ExOKF.Link.t()],
  meta: map(),
  path: String.t(),
  raw_frontmatter: String.t() | nil,
  resource: String.t() | nil,
  tags: [String.t()],
  timestamp: String.t() | nil,
  title: String.t() | nil,
  type: String.t() | nil
}

An OKF concept.

See the module documentation for field meanings and a full structural example.

Functions

display_title(concept)

@spec display_title(t()) :: String.t()

Returns a display title for the concept.

Uses title when present and non-empty; otherwise derives a humanized name from the basename of id (e.g. "tables/customer_orders" → "Customer Orders").

Parameters

concept (t/0) — concept to title

Examples

iex> ExOKF.Concept.display_title(%ExOKF.Concept{id: "tables/orders", path: "tables/orders.md", title: "Orders"})
"Orders"

iex> ExOKF.Concept.display_title(%ExOKF.Concept{id: "foo/bar_baz", path: "foo/bar_baz.md"})
"Bar Baz"

from_parsed(rel_path, frontmatter, body, links \\ [], raw_frontmatter \\ nil)

@spec from_parsed(
  String.t(),
  map() | nil,
  String.t(),
  [ExOKF.Link.t()],
  String.t() | nil
) :: t()

Builds a concept from a relative path and parsed frontmatter/body.

Used by ExOKF.Parser. Known OKF keys are lifted onto struct fields; everything else lands in meta.

Parameters

rel_path (String.t()) — bundle-relative path, e.g. "tables/orders.md"
frontmatter (map() \| nil) — parsed YAML map (string or atom keys)
body (String.t()) — markdown body after the closing ---
links ([ExOKF.Link.t()]) — optional pre-extracted links (default [])
raw_frontmatter (String.t() \| nil) — optional original YAML text

Examples

iex> c = ExOKF.Concept.from_parsed(
...>   "tables/orders.md",
...>   %{"type" => "BigQuery Table", "title" => "Orders", "owner" => "sales"},
...>   "# Schema\n"
...> )
iex> {c.id, c.type, c.meta["owner"]}
{"tables/orders", "BigQuery Table", "sales"}

frontmatter_map(c)

@spec frontmatter_map(t()) :: map()

Returns a frontmatter map suitable for serialization.

Includes known OKF fields (when present) and all extension keys from meta. Used by ExOKF.Writer for lossless round-trips.

Parameters

concept (t/0) — concept to serialize

Examples

iex> c = %ExOKF.Concept{
...>   id: "x",
...>   path: "x.md",
...>   type: "Metric",
...>   title: "Revenue",
...>   meta: %{"unit" => "USD"}
...> }
iex> ExOKF.Concept.frontmatter_map(c)
%{"type" => "Metric", "title" => "Revenue", "unit" => "USD"}

known_fields()

@spec known_fields() :: [atom()]

Returns the known OKF frontmatter field names as atoms.

These are the fields defined by the OKF v0.1 spec (type required; the rest recommended). Any other frontmatter key is treated as an extension and stored in meta.

Examples

iex> ExOKF.Concept.known_fields()
[:type, :title, :description, :resource, :tags, :timestamp]