okf

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 26, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package okf parses and renders Open Knowledge Format v0.2 documents.

The package treats Attested Computation fields as inert metadata. It never resolves resources or executes computations, executors, or attesters.

Index

Constants

View Source 
const Version = "0.2"

Version is the Open Knowledge Format version implemented by this package.

Variables

View Source 
var ErrInvalid = errors.New("invalid OKF document")

ErrInvalid is matched by every OKF validation violation.

Functions

func Body 

func Body(relative string, content []byte, limits Limits) (string, error)

Body returns a validated concept's user-authored Markdown body.

func IsStale 

func IsStale(metadata Metadata, now time.Time) bool

IsStale reports whether now is on or after stale_after.

func RenderConcept 

func RenderConcept(relative string, document Document, limits Limits) ([]byte, error)

RenderConcept renders a concept deterministically and validates the result.

func RenderIndex 

func RenderIndex(relative string, index Index, limits Limits) ([]byte, error)

RenderIndex deterministically renders and validates a reserved index.

func RenderLog 

func RenderLog(relative string, logDocument Log, limits Limits) ([]byte, error)

RenderLog deterministically renders and validates a reserved log.

Types

type Attester 

type Attester struct {
	Resource   string         `json:"resource"`
	Extensions map[string]any `json:"extensions,omitempty"`
}

Attester describes an inert deterministic receipt checker.

type Document 

type Document struct {
	Metadata Metadata `json:"metadata"`
	Body     string   `json:"body"`
}

Document is a parsed OKF concept.

func ParseConcept 

func ParseConcept(relative string, content []byte, limits Limits) (Document, error)

ParseConcept parses and validates one non-reserved OKF concept.

func ParseConceptWithDefaultType 

func ParseConceptWithDefaultType(relative string, content []byte, defaultType string, limits Limits) (Document, error)

ParseConceptWithDefaultType parses a concept and supplies defaultType only when the input omits type or declares it as an empty string. It is intended for producers normalizing generic Markdown into conformant OKF.

type DocumentKind 

type DocumentKind string

DocumentKind identifies an OKF document's role within a bundle. 

const (
	// DocumentConcept is a non-reserved Markdown concept.
	DocumentConcept DocumentKind = "concept"
	// DocumentIndex is an index.md reserved document.
	DocumentIndex DocumentKind = "index"
	// DocumentLog is a log.md reserved document.
	DocumentLog DocumentKind = "log"
	// DocumentAsset is a non-Markdown bundle asset.
	DocumentAsset DocumentKind = "asset"
)

func ClassifyPath 

func ClassifyPath(relative string) (DocumentKind, error)

ClassifyPath classifies a canonical bundle-relative path. Reserved names are recognized by basename at every directory depth.

type Executor 

type Executor struct {
	Resource   string         `json:"resource"`
	Receipt    []string       `json:"receipt,omitempty"`
	Extensions map[string]any `json:"extensions,omitempty"`
}

Executor describes inert run instructions and the declared receipt shape.

type Generation 

type Generation struct {
	By         string         `json:"by"`
	At         *time.Time     `json:"at,omitempty"`
	Extensions map[string]any `json:"extensions,omitempty"`
}

Generation records how the current concept content was produced.

type Index 

type Index struct {
	ObservedVersion string `json:"observed_version,omitempty"`
	Body            string `json:"body"`
}

Index is a parsed reserved index document.

func ParseRootIndex 

func ParseRootIndex(content []byte, limits Limits) (Index, error)

ParseRootIndex parses the bundle-root index.md and observes its declared version. Missing and unknown versions are accepted for best-effort reading.

func ValidateIndex 

func ValidateIndex(relative string, content []byte, limits Limits) (Index, error)

ValidateIndex validates one reserved index.md at any bundle depth.

func (Index) EffectiveVersion 

func (index Index) EffectiveVersion() string

EffectiveVersion returns v0.2 when a root index does not declare a version.

type Limits 

type Limits struct {
	MaxBytes   int
	MaxNodes   int
	MaxAliases int
	MaxDepth   int
}

Limits bounds parsing and rendering work.

func DefaultLimits 

func DefaultLimits() Limits

DefaultLimits returns conservative per-document limits within Knowl's existing canonical page bounds.

type Log 

type Log struct {
	Title  string     `json:"title"`
	Groups []LogGroup `json:"groups"`
}

Log is a parsed reserved log document.

func ValidateLog 

func ValidateLog(relative string, content []byte, limits Limits) (Log, error)

ValidateLog parses and validates a newest-first, ISO-date-grouped log.md.

type LogGroup 

type LogGroup struct {
	Date    time.Time `json:"date"`
	Entries []string  `json:"entries"`
}

LogGroup contains entries for one ISO calendar date.

type Metadata 

type Metadata struct {
	Type           string         `json:"type"`
	Title          string         `json:"title,omitempty"`
	Description    string         `json:"description,omitempty"`
	Resource       string         `json:"resource,omitempty"`
	Tags           []string       `json:"tags,omitempty"`
	Sources        []Source       `json:"sources,omitempty"`
	UsageWindow    *UsageWindow   `json:"usage_window,omitempty"`
	Generated      *Generation    `json:"generated,omitempty"`
	Verified       []Verification `json:"verified,omitempty"`
	Status         Status         `json:"status,omitempty"`
	StaleAfter     *time.Time     `json:"stale_after,omitempty"`
	Runtime        string         `json:"runtime,omitempty"`
	Parameters     []Parameter    `json:"parameters,omitempty"`
	Computation    string         `json:"computation,omitempty"`
	Executor       *Executor      `json:"executor,omitempty"`
	Attester       *Attester      `json:"attester,omitempty"`
	Extensions     map[string]any `json:"extensions,omitempty"`
	TrustTier      TrustTier      `json:"trust_tier,omitempty"`
	ResolvedStatus Status         `json:"effective_status,omitempty"`
	Stale          bool           `json:"stale"`
}

Metadata contains the standard OKF v0.2 concept fields and extensions. Empty optional fields remain absent when rendered. Extensions contain transport-safe YAML values: nil, bool, string, int64, uint64, float64, []any, and map[string]any.

func WithDerivedSemantics 

func WithDerivedSemantics(metadata Metadata, now time.Time) Metadata

WithDerivedSemantics returns a metadata copy with advisory trust, effective status, and staleness evaluated at now. It does not mutate the input.

func (Metadata) EffectiveStatus 

func (m Metadata) EffectiveStatus() Status

EffectiveStatus returns stable when status is absent, as required by OKF.

type Parameter 

type Parameter struct {
	Name       string         `json:"name"`
	Type       string         `json:"type"`
	Required   bool           `json:"required"`
	Extensions map[string]any `json:"extensions,omitempty"`
}

Parameter declares one typed, named Attested Computation input.

type Rule 

type Rule string

Rule identifies a stable OKF validation rule. 

const (
	// RuleLimitsInvalid rejects an invalid parser or renderer limit set.
	RuleLimitsInvalid Rule = "okf.limits.invalid"
	// RulePathInvalid rejects unsafe or non-canonical bundle-relative paths.
	RulePathInvalid Rule = "okf.path.invalid"
	// RuleSizeExceeded rejects a document beyond the configured byte limit.
	RuleSizeExceeded Rule = "okf.size.exceeded"
	// RuleUTF8Invalid rejects non-UTF-8 content.
	RuleUTF8Invalid Rule = "okf.utf8.invalid"
	// RuleFrontmatterMissing rejects a concept without leading frontmatter.
	RuleFrontmatterMissing Rule = "okf.frontmatter.missing"
	// RuleFrontmatterMalformed rejects malformed or unsafe YAML frontmatter.
	RuleFrontmatterMalformed Rule = "okf.frontmatter.malformed"
	// RuleTypeMissing rejects an absent or empty concept type.
	RuleTypeMissing Rule = "okf.type.missing"
	// RuleMetadataInvalid rejects malformed standard metadata.
	RuleMetadataInvalid Rule = "okf.metadata.invalid"
	// RuleTimestampInvalid rejects a timestamp without an explicit UTC offset.
	RuleTimestampInvalid Rule = "okf.timestamp.invalid"
	// RuleIndexInvalid rejects a malformed reserved index document.
	RuleIndexInvalid Rule = "okf.index.invalid"
	// RuleLogInvalid rejects a malformed reserved log document.
	RuleLogInvalid Rule = "okf.log.invalid"
)

type Source 

type Source struct {
	ID           string         `json:"id,omitempty"`
	Resource     string         `json:"resource"`
	Title        string         `json:"title,omitempty"`
	Author       string         `json:"author,omitempty"`
	UsageCount   *uint64        `json:"usage_count,omitempty"`
	LastModified *time.Time     `json:"last_modified,omitempty"`
	UsageWindow  *UsageWindow   `json:"usage_window,omitempty"`
	Extensions   map[string]any `json:"extensions,omitempty"`
}

Source records material from which a concept derives.

type Status 

type Status string

Status is an explicitly declared OKF lifecycle state. 

const (
	// StatusDraft identifies possibly incomplete content.
	StatusDraft Status = "draft"
	// StatusStable identifies content ready for consumption.
	StatusStable Status = "stable"
	// StatusDeprecated identifies retained but no-longer-current content.
	StatusDeprecated Status = "deprecated"
)

type TrustTier 

type TrustTier string

TrustTier is the advisory trust tier derived from verification actors. 

const (
	// TrustUnverified means the concept has no verification event.
	TrustUnverified TrustTier = "unverified"
	// TrustMachineConfirmed means only non-human actors verified the concept.
	TrustMachineConfirmed TrustTier = "machine-confirmed"
	// TrustHumanReviewed means at least one human actor verified the concept.
	TrustHumanReviewed TrustTier = "human-reviewed"
)

func DeriveTrustTier 

func DeriveTrustTier(metadata Metadata) TrustTier

DeriveTrustTier derives the advisory tier solely from verification actors.

type UsageWindow 

type UsageWindow struct {
	From       time.Time      `json:"from"`
	To         time.Time      `json:"to"`
	Extensions map[string]any `json:"extensions,omitempty"`
}

UsageWindow frames source usage counts.

type Verification 

type Verification struct {
	By         string         `json:"by"`
	At         time.Time      `json:"at"`
	Extensions map[string]any `json:"extensions,omitempty"`
}

Verification records one confirmation of concept content.

type Violation 

type Violation struct {
	Path string
	Rule Rule
}

Violation is a redacted validation error containing no document content or host filesystem path.

func (*Violation) Error 

func (v *Violation) Error() string

Error returns the stable relative path and rule code.

func (*Violation) Unwrap 

func (v *Violation) Unwrap() error

Unwrap makes all violations match ErrInvalid.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.