title: MX Field Dictionary — Open Standard (Core)
version: '5.0'
created: 2026-02-13T00:00:00.000Z
modified: '2026-04-15'
author: The Gathering
description: >-
Open standard canonical MX metadata fields. The Gathering-owned core dictionary covering identity, classification,
relationships, machine-readability infrastructure, folder metadata, cog contract, and non-YAML markup carriers. For
carrier-format schemas (code/database/media) see fields-data-carriers.yaml. For CogNovaMX vendor extensions see
cognovamx-fields.yaml.
mx:
status: active
license: MIT
category: standard
partOf: mx-the-gathering
tags:
- fields
- metadata
- yaml
- frontmatter
- dictionary
- vocabulary
- standard
- open
audience:
- machines
- humans
contentType: field-dictionary
runbook: >-
This is the universal metadata registry. Parse the fields array for every canonical field with name, type,
definition, status, and profile. The blockTypes array defines block types and their fields. The carrierFormats array
maps metadata to file types. The overlap-resolution section declares which field wins when two seem similar. The
namespace-policy section defines three levels: standard (no prefix), MX-public (x-mx-), and MX-private (x-mx-p-).
The prefix IS the policy.
namespacePolicy:
description: >-
Three-level attribute namespace. Standard fields belong to The Gathering open standard. Extensions are namespaced
to prevent pollution.
adr: mx-canon/mx-maxine-lives/thinking/decisions/2026-02-14-attribute-namespace-policy.cog.md
levels:
- level: standard
prefix: ''
owner: The Gathering
visibility: Universal — all implementations use these fields
example: title, author, created, version, tags
rule: No prefix. Defined by the open standard. All implementations honour them.
- level: mx-public
prefix: x-mx-
owner: CogNovaMX
visibility: Visible in published cogs. Implementation extension, not the open standard.
example: x-mx-audience-segment, x-mx-pipeline-stage
rule: x- signals extension. mx- signals whose. Visible to anyone reading the cog.
- level: mx-private
prefix: x-mx-p-
owner: CogNovaMX
visibility: Obfuscated. Only $MX_HOME registry holders can decode the value.
example: x-mx-p-*
rule: >-
p- signals private. Values are hashed, encoded, or tokenised. The decode registry lives in $MX_HOME. Field
names and their meanings are not documented publicly.
convention: >-
x- follows HTTP extension header convention. mx- identifies CogNovaMX. p- identifies private/obfuscated. The
prefix is the policy — no additional visibility markers needed.
namingConvention:
rule: All field names use camelCase. Aligns with Schema.org and Dublin Core vocabulary conventions.
ndr: mx-canon/mx-maxine-lives/registers/NDR/2026-02-16-camelcase-naming.cog.md
date: 2026-02-16T00:00:00.000Z
examples:
correct:
- readingLevel
- buildsOn
- blogState
- contentType
- partOf
banned-snake:
- reading_level
- builds_on
- blog_state
banned-kebab:
- reading-level
- builds-on
- blog-state
unchanged:
- title
- author
- created
- version
- tags
- name
enforcement:
audit: npm run audit:metadata — reports violations in Section 9
validator: node scripts/mx-validator.js — warns on new violations
rationale: >-
MX metadata is a vocabulary (like Schema.org), not markup (like HTML attributes). Vocabularies use camelCase.
YAML has no preference — the convention comes from the consuming ecosystem.
spelling-neutrality:
rule: >-
Prefer spelling-neutral field names. Where US/UK spelling differs, use an abbreviation or synonym that avoids
the conflict.
ndr: mx-canon/mx-maxine-lives/registers/NDR/2026-02-16-spelling-neutrality.cog.md
date: 2026-02-16T00:00:00.000Z
strategy:
- 'Abbreviate: org (not organisation/organization). W3C Organization Ontology precedent.'
- 'Follow standards: license (SPDX universal). Not licence.'
- 'Use neutral synonyms: imagesAudited (not imagesAnalysed/imagesAnalyzed).'
exceptions:
- license — SPDX standard spelling. Universal across npm, GitHub, every package manager.
rationale: >-
MX is a global standard. Spelling-neutral names prevent regional debates and follow the Schema.org principle:
when a neutral term is available, use it.
context-specific-naming:
rule: >-
Context determines syntax. YAML frontmatter uses camelCase. HTML/JS/CSS contexts use kebab-case with mx: prefix.
Same field, different representation.
alignment: mx-canon/mx-maxine-lives/deliverables/mx-standards-alignment.cog.md
contexts:
yaml:
syntax: camelCase
example: 'buildsOn: [cog-unified-spec]'
rationale: Schema.org precedent. YAML is a data format — use the vocabulary's native naming.
enforcement: mandatory
html:
syntax: 'kebab-case with mx: prefix'
example:
rationale: HTML attribute convention. Follows data-* pattern (data-user-name in HTML, dataset.userName in JS).
enforcement: mandatory
jsdoc:
syntax: 'kebab-case with @mx: tag'
example: '@mx:runtime node'
rationale: 'JSDoc at-rule convention. @param, @returns, @mx: all follow same pattern.'
enforcement: flexible (kebab preferred, validated by linter not spec)
css:
syntax: 'kebab-case with @mx: comment'
example: /* @mx:type utility */
rationale: 'CSS at-rule convention. @media, @supports, @mx: all use hyphens.'
enforcement: flexible (kebab preferred, validated by linter not spec)
shell:
syntax: 'camelCase in # key: value lines'
example: '# buildsOn: [script-helper]'
rationale: 'Comment-block frontmatter strips # prefix to produce valid YAML. Same naming as YAML context.'
enforcement: mandatory
xmp:
syntax: 'mx: namespace prefix'
example: mx:contentType, mx:audience
rationale: XMP custom namespace convention. Registered namespace URI for MX metadata.
enforcement: mandatory
sidecar:
syntax: camelCase in YAML (same as yaml context)
example: '{ mx: { contentType: image, aiTraining: prohibited } }'
rationale: Sidecar files are standard YAML. Same naming rules as YAML frontmatter.
enforcement: mandatory
sql-comment:
syntax: camelCase in -- @mx comment blocks
example: |-
-- @mx
-- purpose: User account storage
-- @mx:end
rationale: SQL comment block stripped of -- prefix produces valid YAML.
enforcement: mandatory
namespace-equivalence:
description: >-
The mx: object in YAML is equivalent to mx:* prefix in HTML/JS/CSS. Both represent The Gathering's standard
namespace.
yaml-form: |
mx:
contentType: field-dictionary
runbook: "Parse the fields array"
html-form: |
note: >-
The mx: namespace belongs to The Gathering (open standard), not CogNovaMX. See governance section in
mx-standards-alignment.cog.md.
precedents:
- standard: Schema.org
pattern: camelCase properties (datePublished, servesCuisine)
mx-applies: YAML frontmatter fields
- standard: Dublin Core
pattern: 'dc: object in YAML, in HTML'
mx-applies: 'mx: object in YAML, in HTML'
- standard: Open Graph
pattern: 'og: object in frontmatter, in HTML'
mx-applies: Same pattern — context determines syntax
- standard: HTML dataset API
pattern: data-user-name (HTML) → dataset.userName (JS)
mx-applies: mx:content-type (HTML) → contentType (YAML under mx:)
enforcement-levels:
mandatory:
- 'YAML frontmatter: camelCase required'
- 'HTML meta tags: kebab-case required'
flexible:
- 'JSDoc comments: kebab-case preferred, enforce via ESLint'
- 'CSS comments: kebab-case preferred, enforce via stylelint'
rationale: Strict where machines parse (YAML, HTML). Flexible where humans read (code comments).
sources:
merged-from:
- path: datalake/knowledge/reference/mx-metadata-standards.md
contribution: Field definitions, validation rules, audience/purpose semantics
status: absorbed — file removed 2026-03-03
- path: datalake/knowledge/reference/frontmatter-field-audit.md
contribution: Usage counts across 1,065 files, naming inconsistencies, profile groupings
status: absorbed — file removed 2026-03-03
- path: datalake/knowledge/specifications/index-of-yaml-attributes-used.md
contribution: Auto-generated attribute index from .mx.yaml.md folder metadata files
- path: mx-canon/mx-the-gathering/field-dictionary-guide.cog.md
contribution: How to add new fields procedure, vendor extension guidance
date: 2026-03-01T00:00:00.000Z
status: absorbed — file removed 2026-03-03
- path: mx-canon/ssot/writing-guides/mx-yaml-md-guide.md
contribution: Folder metadata inheritance model, identity vs inheritable fields, allowed values
date: 2026-03-01T00:00:00.000Z
- path: explain.md
contribution: Metadata architecture overview — two-zone model, inheritance, profiles, namespace policy
date: 2026-03-03T00:00:00.000Z
status: absorbed — file removed 2026-03-03
- path: mx-canon/mx-the-gathering/specifications/mx-code-metadata-spec.md
contribution: >-
Code metadata — repository, file, function, class, inline annotations, dependency, environment, test, API
fields and carrier formats
date: 2026-03-03T00:00:00.000Z
- path: mx-canon/mx-the-gathering/specifications/mx-media-metadata-spec.md
contribution: >-
Media metadata — sidecar files, embedded metadata alignment, image, video, audio, document, rights,
collections fields and carrier formats
date: 2026-03-03T00:00:00.000Z
- path: mx-canon/mx-the-gathering/specifications/mx-database-metadata-spec.md
contribution: >-
Database metadata — database, schema, table, column, relationship, index, view, query, procedure, dictionary,
classification fields
date: 2026-03-03T00:00:00.000Z
defaultsPolicy:
description: >-
Two-zone frontmatter model. Zone 1 (top-level): title, description, author, created, modified, version — always
explicit, never inside mx: block. Zone 2 (mx: block): all other fields. Optional Zone 2 fields with defined
defaults may be omitted; tools treat absent optional fields as their documented default value.
rule: >-
Only optional fields may have defaults. If an optional field's value matches its default, the field may be omitted
to reduce frontmatter size. Tools must handle absent optional fields by applying the documented default.
zones:
top-level:
fields:
- title
- description
- author
- created
- modified
- version
rule: Always explicit. These are document identity fields and never move under mx:.
mx:
fields: >-
All other MX-operational fields (status, contentType, category, tags, audience, runbook, execute, ai* fields,
etc.)
rule: Optional fields with documented defaults may be omitted when matching their default value.
always-explicit:
- field: title
requirement: required
reason: Identity — every document needs a name
- field: description
requirement: required
reason: Discovery — search engines and AI agents need this
- field: author
requirement: required
reason: Attribution — immutable provenance
- field: created
requirement: required
reason: Timestamp — immutable creation date
- field: modified
requirement: required
reason: Timestamp — last modification date
- field: version
requirement: recommended
reason: Version tracking — explicit is safer than assumed
- field: status
requirement: recommended
reason: Lifecycle — always declare your document state
fields-with-defaults:
- field: confidential
default: false
absent-means: Document is public
- field: aiAssistance
default: welcome
absent-means: AI agents are welcome to assist
- field: aiEditable
default: false
absent-means: AI agents should not edit this content
- field: aiGenerationAllowed
default: true
absent-means: AI generation is permitted
- field: aiGenerationReviewRequired
default: true
absent-means: AI-generated content requires human review
contentTypeToProfile:
info-doc: core
field-dictionary: core
specification: core
briefing-doc: core
guide: core
action-doc: cog
cog: cog
eds-block: cog
certificate-of-genuineness: cog
book-chapter: book
book-appendix: book
blog-post: blog
blog: blog
contact: contact
direct-message: contact
personal-message: contact
folder-metadata: folder
report: report
session-report: report
audit: audit
event: event
migration: migration
script: script
error-page: core
validationPolicy:
descriptionMaxLength: 160
dateFields:
- created
- modified
- publicationDate
- lastContact
- movedDate
- expires
- maintainedDate
scoreFields:
- performanceScore
- llmSuitabilityScore
- seoScore
lenientEnums:
- field: blocks
reason: >-
Many cogs use `blocks:` as free-text prose description. The spec reserves it for block-type declarations.
Clean up cogs, then remove this lenient entry.
excludeFromTopLevel:
rule: 'Auto: any field whose name contains ''.'''
deprecations:
- old: name
replacement: title
notes: Use `title` for document identity; `name` is reserved for nested field definitions.
- old: type
replacement: contentType or cogType
notes: '`type` was ambiguous — split into contentType (what the content is) and cogType (action vs info vs routing).'
- old: confidentiality
replacement: confidential
notes: Noun form confused readers; boolean flag is clearer.
- old: inherit
replacement: inherits
notes: Plural form matches the shape (a list of inheritance sources).
- old: inheritFrom
replacement: inherits
- old: issued
replacement: publicationDate
notes: Explicit semantic name.
- old: venue
replacement: location
notes: Generic term covers more cases.
- old: prose-source
replacement: inherits
- old: proseSource
replacement: inherits
- old: lastVerified
replacement: maintainedDate
- old: verifiedBy
replacement: maintainedBy
blockTypes:
- name: prose
implicit: true
description: Human-readable narrative. The markdown body of every cog. Never declared in YAML — it is implicit.
- name: essence
implicit: false
description: Binary content (images, PDFs, audio, video, compiled assets). Encoded as base64 or a pointer.
sizeRule: 2kb or smaller = embedded base64. Over 2kb = pointer with checksum.
fields:
- name: type
type: string
required: true
description: MIME type (e.g., image/png, application/pdf, audio/mpeg)
- name: encoding
type: string
required: true
validValues:
- base64
- pointer
description: How binary content is stored
- name: size
type: number
required: true
description: Content size in bytes
- name: content
type: string
required: false
description: Base64-encoded content (when encoding is base64)
- name: location
type: string
required: false
description: File path to binary content (when encoding is pointer)
- name: checksum
type: string
required: false
description: SHA-256 checksum for verification (when encoding is pointer)
- name: definition
implicit: false
description: Standards conformance declarations. The cog's backward-compatibility statement and contract with readers.
hierarchical: true
hierarchyNote: Document-level definition applies to all blocks. Per-block definition overrides for that block only.
fields:
- name: standards
type: array
required: true
description: Array of conformance declarations
- name: standards[].name
type: string
required: true
description: Standard name (e.g., The Gathering, Schema.org, WebMCP)
- name: standards[].version
type: string
required: true
description: Standard version (semantic versioning)
- name: standards[].scope
type: string
required: true
description: What this standard applies to (e.g., cog metadata format, product metadata)
- name: action
implicit: false
description: >-
Executable instructions. Presence of an execute object makes a cog into an action-doc. See execute fields in the
fields array.
note: The action block IS the execute object in YAML frontmatter. Documented as execute.* fields in this dictionary.
- name: code
implicit: false
description: >-
Source code embedded in the cog. Machine-addressable — a reader can extract and execute it. Unlike fenced code
blocks in prose (display only).
fields:
- name: language
type: string
required: true
description: Programming language (e.g., javascript, python, bash)
- name: content
type: string
required: true
description: Source code content
- name: purpose
type: string
required: false
description: What this code does
- name: html
implicit: false
description: >-
HTML content. May reference WebMCP for embedded routines. Can carry interactive widgets, forms, or
visualisations.
interBlockAccess: >-
An HTML block using WebMCP can access all other blocks in the cog — reading essence content, querying code
blocks, rendering provenance. Governed by security block and SOP policy.
fields:
- name: content
type: string
required: true
description: HTML markup
- name: standards
type: array
required: false
description: Conformance declarations (e.g., WebMCP)
- name: security
implicit: false
description: >-
Trust and execution policy. Readers consult the security block to determine whether to execute action blocks or
render HTML blocks.
fields:
- name: attestation
type: string
required: false
validValues:
- required
- optional
description: Whether cryptographic attestation is required
- name: execution
type: string
required: false
validValues:
- sandboxed
- unrestricted
description: Execution environment constraint
- name: trustLevel
type: number
required: false
description: Numeric trust tier (1-3)
- name: policy
type: string
required: false
description: Free text policy statement
- name: riskLevel
type: string
required: false
validValues:
- low
- medium
- high
- critical
description: >-
Execution danger classification. Distinct from trustLevel (provenance quality). low = read-only, no side
effects. medium = writes files or calls APIs. high = modifies system state, handles credentials. critical =
destructive operations, financial transactions — SHOULD have a guardrail gate.
- name: scope
type: object
required: false
description: >-
Runtime scope constraints. Declares what the cog is permitted to touch when it executes. Omission means
unspecified (reader applies its own policy), not unrestricted.
fields:
- name: filesystem
type: array
required: false
description: Glob patterns of allowed filesystem paths (e.g. [scripts/**, mx-outputs/pdf/**])
- name: network
type: string
required: false
validValues:
- none
- local
- external
description: Network access permitted during execution
- name: dataBoundary
type: string
required: false
validValues:
- user
- team
- organisation
description: Whose data the cog may access
- name: maxRecords
type: number
required: false
description: Maximum records per operation — prevents bulk extraction
- name: allowedOperations
type: array
required: false
validValues:
- read
- write
- create
- delete
- execute
description: Permitted filesystem operations
- name: audit
type: object
required: false
description: Audit trail requirements. Declares what should be logged when the cog executes.
fields:
- name: logLevel
type: string
required: false
validValues:
- full
- standard
- minimal
- none
description: Granularity of audit logging
- name: retention
type: string
required: false
description: How long to retain audit records (e.g. 30d, 90d, 1y, permanent)
- name: includeInputs
type: boolean
required: false
description: Whether to log input parameters
- name: includeOutputs
type: boolean
required: false
description: Whether to log output results
- name: dataProtection
type: object
required: false
description: Data protection policy for cog outputs. Declares sensitivity classification and redaction rules.
fields:
- name: outputClassification
type: string
required: false
validValues:
- public
- internal
- confidential
- restricted
description: Sensitivity classification of the cog's outputs
- name: prohibitedFields
type: array
required: false
description: Field names that must never appear in outputs (e.g. [ssn, creditCard, apiKey, password])
- name: redaction
type: string
required: false
validValues:
- auto
- manual
- none
description: Redaction mode for sensitive content in outputs
- name: piiHandling
type: string
required: false
validValues:
- mask
- hash
- omit
- pass-through
description: How personally identifiable information is treated in outputs
- name: rateLimit
type: object
required: false
description: Rate limiting constraints. Prevents runaway execution and abuse.
fields:
- name: maxCalls
type: number
required: false
description: Maximum number of invocations within the time window
- name: window
type: string
required: false
description: Time window for rate limiting (e.g. 1h, 1d, 1w)
- name: cooldown
type: string
required: false
description: Minimum gap between consecutive calls (e.g. 5m, 1h)
- name: scope
type: string
required: false
validValues:
- perUser
- perAgent
- global
description: Scope of rate limit tracking
- name: allowedRoles
type: array
required: false
description: >-
Roles permitted to execute this cog. Bridges the guardrail pattern — declares which roles the gate should
verify.
- name: sop
implicit: false
virtual: true
description: >-
Standard Operating Procedures. Merged at read-time from the uber doc (UBER.cog.md). Does not exist in the cog
file on disk.
fields:
- name: scope
type: string
required: true
description: What this SOP applies to (all-cogs, html-blocks, domain-specific)
- name: instructions
type: string
required: true
description: Procedure instructions (multi-line text)
- name: provenance
implicit: false
description: Origin and lineage — where the content came from, how it was derived, what transformations were applied.
fields:
- name: origin
type: string
required: false
description: URL of original source
- name: derivedFrom
type: string
required: false
description: Source cog reference
- name: method
type: string
required: false
description: Transformation description
- name: date
type: string
required: false
description: Derivation date (ISO 8601)
- name: version
implicit: false
description: Version history and changelog within the cog. Complements the top-level version field with detailed history.
fields:
- name: history
type: array
required: true
description: Array of version entries
- name: history[].version
type: string
required: true
description: Version number (semver)
- name: history[].date
type: string
required: true
description: Release date (ISO 8601)
- name: history[].changes
type: string
required: true
description: Description of changes
carrierFormats:
- format: .cog.md
metadataLocation: YAML frontmatter between --- delimiters
mxIdentity: Standard cog fields in YAML
nativeBlocks: Markdown body = prose block
parsingRule: Standard YAML parser reads frontmatter
backwardCompatible: true
narrativeSection: 'Carrier: YAML Frontmatter'
- format: .cog.html
metadataLocation: tags in
mxIdentity: tags, data-mx-* attributes on elements
nativeBlocks: Schema.org JSON-LD = definition, = prose excerpt, = essence
parsingRule: 'Parse tags; strip mx: prefix; apply kebab-to-camelCase conversion'
backwardCompatible: true
note: Browsers ignore unknown names. Can embed