{"id":51231104,"url":"https://github.com/harehare/okf.mq","last_synced_at":"2026-06-28T16:30:31.915Z","repository":{"id":366095978,"uuid":"1274893681","full_name":"harehare/okf.mq","owner":"harehare","description":"An OKF (Open Knowledge Format) reader/writer implemented as an mq module","archived":false,"fork":false,"pushed_at":"2026-06-20T07:23:50.000Z","size":16,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-20T09:14:51.762Z","etag":null,"topics":["markdown","mq","okf","okf-format"],"latest_commit_sha":null,"homepage":"https://mqlang.org","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/harehare.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-20T02:21:22.000Z","updated_at":"2026-06-20T07:23:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/harehare/okf.mq","commit_stats":null,"previous_names":["harehare/okf.mq"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/harehare/okf.mq","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harehare%2Fokf.mq","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harehare%2Fokf.mq/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harehare%2Fokf.mq/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harehare%2Fokf.mq/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/harehare","download_url":"https://codeload.github.com/harehare/okf.mq/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harehare%2Fokf.mq/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34896652,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["markdown","mq","okf","okf-format"],"created_at":"2026-06-28T16:30:31.242Z","updated_at":"2026-06-28T16:30:31.909Z","avatar_url":"https://github.com/harehare.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eokf.mq\u003c/h1\u003e\n\nAn [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog) (Open Knowledge Format) reader/writer implemented as an [mq](https://github.com/harehare/mq) module.\n\nOKF represents knowledge as a directory (\"bundle\") of Markdown files with YAML\nfrontmatter — concept documents, plus the reserved `index.md` and `log.md`\nfiles. This module parses and builds those documents, validates conformance,\nand works with cross-links, citations, and log/index entries.\n\n## Features\n\n- Parse/build concept documents (`{frontmatter, body}`)\n- Validate a single document, or a whole bundle, against the OKF conformance rules\n- Classify and extract cross-links (`external` / `absolute` / `relative`), and find broken internal links\n- Parse, format, and append entries in the `# Citations` list\n- Parse and build date-grouped `log.md` sections (newest-first)\n- Parse and build `index.md` entries, including the bundle-root `okf_version` frontmatter\n- Summarize a bundle's concept documents for an overview table\n\n## Installation\n\nCopy `okf.mq` to your mq module directory, or place it anywhere and reference it with `-L`.\n\n```sh\ncp okf.mq ~/.local/mq/config/\n```\n\n### HTTP Import (no local installation needed)\n\nIf `mq` was built with the `http-import` feature, you can import directly from GitHub without any local setup:\n\n```sh\nmq -I raw 'import \"github.com/harehare/okf.mq\" | okf::okf_parse(.)' concept.md\n```\n\nPin to a specific release with `@vX.Y.Z`:\n\n```sh\nmq -I raw 'import \"github.com/harehare/okf.mq@v0.1.0\" | okf::okf_parse(.)' concept.md\n```\n\n## Usage\n\n```sh\nmq -L /path/to/modules -I raw \\\n  'include \"okf\" | okf_parse(.)' concept.md\n```\n\nIf you copied it to the mq built-in module directory:\n\n```sh\nmq -I raw 'include \"okf\" | okf_parse(.)' concept.md\n```\n\n## API\n\n### Concept documents\n\n| Function | Description |\n|---|---|\n| `okf_parse(input)` | Splits a Markdown string into `{frontmatter, body}`. Documents without a leading `---` block get an empty `frontmatter` dict. |\n| `okf_stringify(doc)` | Renders a `{frontmatter, body}` doc back into a Markdown string. |\n| `okf_new(type, fields, body)` | Builds a new doc; `fields` holds the rest of the frontmatter and `type` always wins. |\n| `okf_type(doc)` | Returns the doc's `type`, or `None`. |\n| `okf_validate(doc)` | Returns an array of `{rule, field, message}` conformance errors (empty = conformant). `rule` is a stable machine-readable code (`invalid_frontmatter`, `missing_required_field`, `empty_required_field`); `field` names the offending frontmatter key, or `None`. |\n| `okf_is_conformant(doc)` | `true` if `okf_validate(doc)` is empty. |\n| `okf_format_validation_error(error)` / `okf_format_validation_errors(errors)` | Render one or many validation errors as human-readable strings, e.g. `\"/tables/orders.md: ... [field: type]\"`. |\n\n### Reserved filenames\n\n| Function | Description |\n|---|---|\n| `okf_reserved_filenames()` | `[\"index.md\", \"log.md\"]`. |\n| `okf_is_reserved_filename(path)` | `true` if `path`'s basename is reserved. |\n\n### Cross-links\n\n| Function | Description |\n|---|---|\n| `okf_link_kind(url)` | `\"external\"`, `\"absolute\"` (starts with `/`), or `\"relative\"`. |\n| `okf_extract_links(body)` | Extracts `[text](url)` links as `{text, url, kind}`. |\n| `okf_check_broken_links(body, known_paths)` | Internal links whose `url` is missing from `known_paths`. |\n\n### Citations\n\n| Function | Description |\n|---|---|\n| `okf_citation_entry(number, text, url)` | Formats `\"[n] [text](url)\"`. |\n| `okf_extract_citations(body)` | Parses the `# Citations` list into `{number, text, url}`. |\n| `okf_add_citation(body, text, url)` | Appends an auto-numbered citation, creating the section if needed. |\n\n### Log files (`log.md`)\n\n| Function | Description |\n|---|---|\n| `okf_log_entry(kind, text)` | Formats `\"**Kind**: text\"`. |\n| `okf_log_section(section)` | Formats one `{date, entries}` section. |\n| `okf_build_log(sections)` | Renders `log.md` content, newest date first. |\n| `okf_parse_log(input)` | Parses `log.md` content into `[{date, entries: [{kind, text}]}]`. |\n\n### Index files (`index.md`)\n\n| Function | Description |\n|---|---|\n| `okf_index_entry(entry)` | Formats one `{path, title?, description?}` list item. |\n| `okf_build_index(entries, version = \"\")` | Renders `index.md`; pass `version` for the bundle-root `okf_version` frontmatter. |\n| `okf_parse_index(input)` | Parses `index.md` content into `[{path, title, description}]`. |\n\n### Loading files from disk\n\nmq has no built-in directory walk, but OKF bundles are meant to be\nself-describing via `index.md` — so discovering a bundle's files doesn't\nrequire listing directories at all, only following the index(es) it already\nhas.\n\n| Function | Description |\n|---|---|\n| `okf_load_concept(path)` | Reads and parses a single concept document. |\n| `okf_load_bundle(paths, root = \"\")` | Reads `[{name, content}]` for an array of paths. With `root`, rewrites `name` to a bundle-relative absolute path (e.g. `/tables/x.md`), matching `okf_link_kind`. |\n| `okf_discover_bundle(root, index_path = \"/index.md\")` | Returns every concept document's filesystem path reachable from `root`'s `index.md`, following nested `index.md` entries. Pure `read_file` — no directory listing. |\n\n### Bundles\n\n| Function | Description |\n|---|---|\n| `okf_validate_bundle(files)` | Validates every file in `[{name, content}]`: concept documents via `okf_validate`, and `index.md`/`log.md` against the reserved-file structure rules (no frontmatter, except `okf_version` on the bundle-root `index.md`; `log.md` date headings must be ISO `YYYY-MM-DD` and sections newest-first). Returns an array of `{rule, field, message, file}` dicts. |\n| `okf_is_bundle_conformant(files)` | `true` if `okf_validate_bundle(files)` is empty. |\n| `okf_check_bundle(root, index_path = \"/index.md\")` | One-call bundle health check: discovers, loads, runs `okf_validate_bundle`, and checks every file's internal links with `okf_check_broken_links`. Returns the combined array of `{rule, field, message, file}` dicts (`broken_link` errors also carry `url`/`text`). |\n| `okf_summarize(files)` | Summarizes concept documents as `[{path, type, title, description}]`. |\n\n### Validation rule reference\n\nEvery error from `okf_validate`, `okf_validate_bundle`, and `okf_check_bundle` has a stable `rule` code you can branch on:\n\n| Rule | Meaning |\n|---|---|\n| `invalid_frontmatter` | A concept document's frontmatter did not parse into a YAML mapping. |\n| `missing_required_field` | A concept document's frontmatter has no `type` field. |\n| `empty_required_field` | A concept document's `type` field is present but empty or blank. |\n| `frontmatter_not_allowed` | `index.md`/`log.md` has frontmatter (only the bundle-root `index.md`'s `okf_version` is exempt). |\n| `invalid_date_heading` | A `log.md` `##` heading isn't an ISO 8601 `YYYY-MM-DD` date. |\n| `log_not_newest_first` | A `log.md`'s date sections aren't ordered newest first. |\n| `broken_link` | An internal (non-external) link's target isn't among the bundle's known files (`okf_check_bundle` only). |\n\n## Example\n\nGiven `customers.md`:\n\n```md\n---\ntype: BigQuery Table\ntitle: Customers\ndescription: Customer records table.\nresource: bigquery://project/dataset/customers\ntags: [pii, core]\n---\n\n# Schema\n\n| Column | Type |\n| --- | --- |\n| id | INT64 |\n| email | STRING |\n\n# Citations\n\n[1] [Data dictionary](https://example.com/dict)\n```\n\n```sh\nmq -L . -I raw 'include \"okf\" | okf_parse(.)[\"frontmatter\"][\"title\"]' customers.md\n# =\u003e \"Customers\"\n\nmq -L . -I raw 'include \"okf\" | okf_validate(okf_parse(.))' customers.md\n# =\u003e []\n\nmq -L . -I raw 'include \"okf\" | okf_extract_citations(okf_parse(.)[\"body\"])' customers.md\n# =\u003e [{\"number\": 1, \"text\": \"Data dictionary\", \"url\": \"https://example.com/dict\"}]\n```\n\nBuilding a bundle-root `index.md`:\n\n```sh\nmq -I null -F text 'include \"okf\" |\n  okf_build_index([\n    {path: \"/tables/customers.md\", title: \"Customers\", description: \"Customer records table.\"}\n  ], \"0.1\")'\n# =\u003e ---\n#    okf_version: 0.1\n#    ---\n#\n#    - [Customers](/tables/customers.md) — Customer records table.\n```\n\n## Working with a bundle directory\n\n`okf_discover_bundle` follows the bundle's own `index.md` (and any nested\n`index.md` it links to) to find every concept document — purely via\n`read_file`, no directory listing. `okf_check_bundle` builds on it to run\nthe whole health check (discover, load, validate, broken-link check) in\none call:\n\n```sh\nmq -I null 'include \"okf\" | okf_check_bundle(\"./bundle\")'\n# =\u003e [{\"rule\": \"missing_required_field\", \"field\": \"type\", \"message\": \"frontmatter must have a 'type' field, but it is missing\", \"file\": \"/tables/orders.md\"}, ...]\n```\n\nRender errors as plain text with `okf_format_validation_errors`:\n\n```sh\nmq -I null 'include \"okf\" | okf_format_validation_errors(okf_check_bundle(\"./bundle\"))'\n# =\u003e [\"/tables/orders.md: frontmatter must have a 'type' field, but it is missing [field: type]\", ...]\n```\n\nIf you only need one piece — e.g. validation without the link check, or a\ncustom file list instead of `okf_discover_bundle` — compose the smaller\nfunctions `okf_check_bundle` itself is built from:\n\n```sh\nmq -I null 'include \"okf\" |\n  let root = \"./bundle\"\n  | okf_validate_bundle(okf_load_bundle(okf_discover_bundle(root), root))'\n# =\u003e [...same validation errors, without the broken-link check]\n```\n\nThis only finds documents the index actually lists — keep `index.md` files\nup to date for `okf_discover_bundle`/`okf_check_bundle` to see everything.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharehare%2Fokf.mq","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fharehare%2Fokf.mq","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharehare%2Fokf.mq/lists"}