Skip to content

manifest.md

Latest commit

 

History

History
282 lines (211 loc) · 7.86 KB

manifest.md

File metadata and controls

282 lines (211 loc) · 7.86 KB
Raw

Manifest reference

opencontext.yaml is the control plane. It declares what context exists, where it is loaded from, who may read it, how authority is ranked, how freshness is judged, and what is audited.

It is not the database. It points at systems that remain the sources of truth.

Schema: https://logicsrc.com/schemas/opencontext/manifest.schema.json

Discovery searches upward from the working directory, the way git finds .git, so commands work from anywhere inside a project. opencontext.json and opencontext.yml are also accepted.

Minimal

opencontext: "1.0"
id: example

opencontext and id are the only required fields.

Identity

Field Type Notes
opencontext string Spec version, e.g. "1.0". A major version the runtime does not support is refused, never partially parsed.
id slug Namespace. Object ids are unique within it.
name string Human-readable organization or project name.
description string One paragraph on what this repository covers.

context — single documents

Each key becomes a resolvable object id; each value is a path or URI.

context:
  mission: ./context/mission.md
  glossary: ./context/glossary.md
  handbook: https://intranet.example.com/handbook.md

A document may declare its own id in front matter, which wins over the key.

collections — globs

The key namespaces the ids of everything the collection loads, so ./context/policies/refunds.md under policies resolves as policies.refunds.

collections:
  policies: ./context/policies/**
  procedures:
    source: ./context/sops/**
    type: procedure
    layer: L4
    owner: support
    ttl: 180d

A bare string is the glob. The object form adds defaults applied to members that omit them.

Glob syntax. ** crosses directories; * and ? never do. Files are picked up only with a context extension (.md, .markdown, .yaml, .yml, .json) unless the pattern names one explicitly. node_modules, .git, dist, build, and dot-directories are skipped.

Derived ids. A member that declares no id gets one derived from its path relative to the collection base: support/refund.md in policies becomes policies.support.refund. index.md and readme.md resolve to the directory itself.

A document that declares an id outside its collection's namespace keeps that id. policies loading a file that declares id: pricing.enterprise produces pricing.enterprise, which policies.* will not match. Declare ids that match the collection, or rely on derivation.

roles — scopes

roles:
  everyone:
    include: [mission, glossary]

  support:
    description: Front-line customer support.
    inherits: [everyone]
    include:
      - policies.*
      - customers.*
    exclude:
      - policies.internal.*
      - customers.*.churn-risk
    permissions: [customer.read, ticket.write]
    max_classification: internal
    redact:
      - path: ssn
        mode: remove
        reason: PII

See permissions and scopes for the full model. In short: scope is opt-in, deny always overrides allow, and inheritance can only narrow.

agents — consumers

agents:
  support-agent:
    roles: [support]
  dev-agent:
    roles: [engineering]
    description: Ships product code.

An agent holds no rights of its own beyond the roles listed. A role named here that the manifest does not define is a validation error — a typo silently denying access is exactly the failure this catches.

authority

authority:
  precedence:
    - canonical
    - approved
    - reference
    - observed
    - inferred
    - historical
  tie_breakers: [version, updated, confidence, id]

precedence may be reordered but must remain a permutation of all six levels. Omitting one would leave objects at that level unrankable; adding one would let a repository define something that outranks canonical.

tie_breakers apply when authority does not settle it. id is always appended so ordering is total and resolution deterministic.

freshness

freshness:
  default_ttl: 30d
  stale_is_error: false
  exclude_expired: true

Durations use fixed unit lengths — y = 365d, w = 7d, d = 24h — so "stale after 30d" means the same number of milliseconds in every timezone. Calendar-aware arithmetic would make resolution non-deterministic.

Stale context still resolves and is reported. stale_is_error makes --strict fail on it.

provenance

provenance:
  required: true
  digest: sha256
  require_digest: false

When required, every resolved object must declare a source or canonical_source: true. The check runs against what the author wrote, not against the file:// source the loader attaches — otherwise it would always pass.

audit

audit:
  context_reads: true
  context_writes: true
  decisions: true
  conflicts: false
  sink: file://./context/.audit/events.ndjson

The specification defines the event shape and leaves storage open. The reference implementation writes file:// sinks; anything else is returned for the caller to ship.

redact — repository-wide

redact:
  - path: payment.card
    mode: mask
    replacement: "[REDACTED]"
    reason: PAN is never needed to answer a question about an account

Applied above every role, including roles that could otherwise read the field. Stating it once here beats repeating it per role.

review

review:
  interval: 180d
  required_approvers: 2
  next_review: 2027-02-09

Default cadence for objects that declare none. Overdue reviews are reported by doctor.

adapters

adapters:
  https:
    enabled: true
    trust: untrusted
    timeout_ms: 5000
  http:
    allow_insecure: false
  git:
    repos:
      github.com/acme/context: ../acme-context

Configuration per URI scheme. A configured trust is a deliberate operator statement and overrides the adapter's own assertion — but only here, never by the content itself. See adapters.

defaults

defaults:
  classification: internal
  trust: trusted
  owner: platform
  ttl: 365d

Applied to objects that omit a field. Defaults describe house style; they never launder authority. An object with no declared authority is reference — useful but not binding — because defaulting unlabelled context to canonical would let an unreviewed note outrank a reviewed policy simply by existing.

health

health:
  minimum_score: 90
  fail_on: error
  require_owner: true
  weights:
    stale: 0.2

Configures doctor. See lifecycle for the formula.

related

related:
  prd: ./openprd.yaml
  topology: ./opentopology.yaml
  ontology: ./openontology.yaml

Optional links to sibling LogicSRC specifications. OpenContext is independently usable without them.

extensions

extensions:
  com.acme.region:
    primary: eu-west-1

Keys must be reverse-DNS namespaced so independent tools never collide. Unknown extensions are preserved and do not invalidate the document unless --strict requires known ones.

Full example

opencontext: "1.0"
id: acme
name: ACME Corporation

context:
  mission: ./context/mission.md
  organization: ./context/organization.md
  glossary: ./context/glossary.md

collections:
  products: ./context/products/**
  policies: ./context/policies/**
  procedures: ./context/sops/**
  decisions: ./context/decisions/**

roles:
  support:
    include: [mission, products.*, policies.support.*, procedures.support.*]
    exclude: [finance.payroll.*, legal.privileged.*]
    permissions: [customer.read, ticket.read, ticket.write]

authority:
  precedence: [canonical, approved, reference, observed, inferred, historical]

freshness:
  default_ttl: 30d

provenance:
  required: true

audit:
  context_reads: true
  context_writes: true
  decisions: true