okf-cli-0.5.0.0: help/ids.md

DOCUMENT IDS

A concept's canonical identity is its path -- tables/orders.md is the concept
tables/orders. A document ID is a second, shorter handle such as ADR-7 that a
house profile can require, for corpora where people cite decisions and requests
by number.

Document IDs are entirely a profile convention. Core OKF has no such notion, so
a bundle validated without a profile never gains or needs one.

DECLARING THEM IN A PROFILE

  A profile names the frontmatter key that holds the handle, and gives selected
  type rules the prefix their concepts must use:

    idField  = Some "docId"        -- profile-wide: which key holds the handle
    idPrefix = Some "ADR"          -- on a TypeRule: which prefix its concepts use

  Concepts of that type must then carry a canonical handle -- PREFIX-N, with
  the prefix compared case-sensitively. Duplicate handles are reported as a
  profile deviation.

  A profile with no idField, or a type rule with no idPrefix, simply performs
  no document-ID checks.

ALLOCATING AND LISTING

  okf id list BUNDLE --profile PROFILE.dhall
  okf id next BUNDLE PREFIX --profile PROFILE.dhall

  Both subcommands require a profile, because the profile is what declares the
  ID field and the allowed prefixes. Neither writes to the bundle.

    okf id list decisions --profile profiles/decisions.dhall
    ADR-1  decisions/use-markdown
    ADR-2  decisions/use-postgres
    ADR-3  decisions/adopt-okf

    okf id next decisions ADR --profile profiles/decisions.dhall
    ADR-4

  id list prints "<handle>  <concept-id>" in prefix-and-number order and omits
  malformed values. id next returns one more than the highest number for the
  requested prefix; it does not fill gaps, so a deleted ADR-2 is never reissued.

  An undeclared prefix, or a profile with no idField, is a hard error.

RESOLVING ONE

  okf show BUNDLE ADR-7
  okf show BUNDLE ADR-7 --profile PROFILE.dhall

  Path lookup runs first, because the path is the canonical OKF identity. If no
  path matches and the argument has document-ID form, show searches frontmatter
  for that exact handle and prints both identities:

    id: decisions/use-postgres
    docId: ADR-2
    type: Decision Record

  --profile narrows the search to the profile's idField. Without it, every
  string-valued frontmatter key is considered, which is why resolution works
  without a profile but is less precise. Duplicate handles are rejected as
  ambiguous and every matching concept ID is listed.

REFERENCING ONE FROM ANOTHER CONCEPT

  A profile field rule may declare that a frontmatter value holds a handle
  rather than free text, so a stale reference is caught:

    field.localReference "supersedes" "ADR"

  okf then checks that the handle exists in this bundle and belongs to a
  profile-governed concept. See "okf help profiles" for external URI schemes,
  self-reference, and the DocumentHandle field format.

SEE ALSO

  okf help profiles     idField, idPrefix, and reference rules in full.
  okf help format       Concept IDs, the canonical identity.