Proposal: Lightweight mechanism to include RDF in OKF

[nonodename]

RDF is well known and used (for example via schema.org) for describing semantics in a formalized manner that permits, amongst other things

• global uniqueness of concepts (via use of domain names in identifiers)
• expression of equivalence (via sameAs etc)
• complex assertions such as disjoint membership, transitive properties etc (via OWL etc)

Permitting the embedding of RDF into OKF markdown files would allow inclusion of assertions
out to wider RDF Graphs that can be included in any resulting graph created by extraction
from the OKF files.

Happily we can combine the two using concepts from the RDFa standard
Since markdown permits HTML fragments, we propose using RDFa inline in the markdown to achieve
this. Further we suggest defining an ontology for OKF such that the YAML members bind to
predicates within that ontology.

All this is probably best shown with an example. Given this OKF file:

---
type: BigQuery Table
title: Company Fundamentals
description: One row per company
resource: https://console.cloud.google.com/bigquery?p=acme&d=marketdata&t=latest_fundamentals
tags: [fundamentals, marketdata]
timestamp: 2026-06-17T14:30:00Z
base: https://catalog.nonodename.com/tables/marketdata/latest_fundamentals
prefixes:
  okf:   https://okf.dev/ns#
  owl:   http://www.w3.org/2002/07/owl#
  rdfs:  http://www.w3.org/2000/01/rdf-schema#
  qudt:  http://qudt.org/schema/qudt/
  qkind: http://qudt.org/vocab/quantitykind/
  so:    https://schema.org/
  dcterms: http://purl.org/dc/terms/
  fibo:  https://spec.edmcouncil.org/fibo/ontology/FND/OwnershipAndControl/Ownership/
---

# Schema

| Column | Type | Description |
|--------|------|-------------|
| `company_id` | STRING | Globally unique company identifier. |
| `company_name` | STRING | Name of the <a rel="so:rangeIncludes" href="https://schema.org/Organization">company</a>. |
| `total_assets` | NUMERIC | The total value of everything a company owns. See <a rel="rdfs:seeAlso" href="https://spec.edmcouncil.org/fibo/ontology/FND/OwnershipAndControl/Ownership/Asset">FIBO Asset</a>. |
| `reporting_currency` | STRING | The currency the company reports in, as the <a rel="qudt:hasQuantityKind" href="http://qudt.org/vocab/quantitykind/Currency">QUDT currency kind</a>. |

# Joins

Joined with
  <a rel="okf:joinsWith" href="https://catalog.nonodename.com/tables/marketdata/prices">marketdata prices</a>
  on `company_id`.

# Data Steward

Contact
  <a rel="so:owner" href="https://github.com/nonodename">nonodename</a>.

# Citations

[1]<a rel="dcterms:source" href="https://console.cloud.google.com/bigquery?p=acme&amp;d=marketdata&amp;t=latest_fundamentals">BigQuery table schema</a>

We could map directly to RDF, expressed as turtle here:

@base <https://catalog.nonodename.com/tables/marketdata/latest_fundamentals> .
@prefix okf:     <https://okf.dev/ns#> .
@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix so:      <https://schema.org/> .
@prefix owl:     <http://www.w3.org/2002/07/owl#> .
@prefix rdfs:    <http://www.w3.org/2000/01/rdf-schema#> .
@prefix qudt:    <http://qudt.org/schema/qudt/> .
@prefix qkind:   <http://qudt.org/vocab/quantitykind/> .
@prefix fibo:    <https://spec.edmcouncil.org/fibo/ontology/FND/OwnershipAndControl/Ownership/> .
@prefix xsd:     <http://www.w3.org/2001/XMLSchema#> .

<>  a okf:BigQueryTable ;
    dcterms:title        "Company Fundamentals" ;
    dcterms:description   "One row per company" ;
    okf:resource          <https://console.cloud.google.com/bigquery?p=acme&d=marketdata&t=latest_fundamentals> ;
    so:keywords           "fundamentals", "marketdata" ;
    dcterms:modified      "2026-06-17T14:30:00Z"^^xsd:dateTime ;
    okf:hasColumn         <#company_id>, <#company_name>, <#total_assets>, <#reporting_currency> ;
    okf:joinsWith         <https://catalog.nonodename.com/tables/marketdata/prices> ;
    so:owner              <https://github.com/nonodename> ;
    dcterms:source        <https://console.cloud.google.com/bigquery?p=acme&d=marketdata&t=latest_fundamentals> .

<#company_id> a okf:Column ;
    okf:name "company_id" ;
    okf:nativeType "STRING" ;
    dcterms:description "Globally unique company identifier." .

<#company_name> a okf:Column ;
    okf:name "company_name" ;
    okf:nativeType "STRING" ;
    dcterms:description "Name of the company." ;
    so:rangeIncludes so:Organization .

<#total_assets> a okf:Column ;
    okf:name "total_assets" ;
    okf:nativeType "NUMERIC" ;
    dcterms:description "The total value of everything a company owns (both current and long-term assets)." ;
    rdfs:seeAlso fibo:Asset .

<#reporting_currency> a okf:Column ;
    okf:name "reporting_currency" ;
    okf:nativeType "STRING" ;
    dcterms:description "The currency the company reports in." ;
    qudt:hasQuantityKind qkind:Currency .

The only real handwaving here is around how columns are found (not explicity tagged, found by convention).
Could also use existing ontologies for some of the invented OKF ontology, for example CSVW

[DeaconDesperado]

I have been using similar to link information asserted in my "personal brain" to an organization-wide graph. It has been useful to keep concepts coherent, especially since naming of individuals and classes can differ but still refer to the same entity (and as the issue points out, OWL provides existing mechanisms for resolving that kind of ambiguity).

It's worth also highlighting that allowing for ontology-defined types solves also the need to formally spec out into OKF the various different discipline-specific shapes of knowledge that may exist, see issue: #131

It seems possible to do this entirely as an optional extension of the base specification?