title: MX Field Dictionary — Carrier Formats Companion
version: '5.0'
created: 2026-02-13T00:00:00.000Z
modified: '2026-04-15'
author: The Gathering
description: >-
  Open standard carrier-format metadata schemas for code (function/class/API/test/inline/dependency/repository).
  Companion to fields-data.yaml; implementations opt in as needed. Databases defer to DCAT and CSVW; media defers to
  Schema.org and EXIF/XMP.
mx:
  status: active
  license: MIT
  category: standard
  partOf: mx-the-gathering
  tags:
    - fields
    - metadata
    - carriers
    - code
    - database
    - media
  audience:
    - machines
    - humans
  contentType: field-dictionary
  runbook: >-
    Companion carrier-format dictionary. Implementations that annotate code, databases, or media content merge this with
    fields-data.yaml. Pure document-metadata systems do not need this file.
  fields:
    - name: runtime
      type: string
      definition: 'Execution environment. Values: node, browser, deno, bun.'
      example: node
      validValues:
        - node
        - browser
        - deno
        - bun
      notes: Required for script profile.
      status: canonical
      profile: script
      required: optional
    - name: dependencies
      type: array
      definition: Package dependencies. Array of package names or package@version strings.
      example:
        - markdownlint-cli2
        - gray-matter
      notes: Array of package names or package@version strings.
      status: canonical
      profile: script
      required: optional
    - name: project.name
      type: string
      definition: Project name for code repository metadata.
      example: My Project
      status: canonical
      profile: code-repository
      required: true
    - name: project.description
      type: string
      definition: Brief description of what this project does.
      example: API backend for order processing
      status: canonical
      profile: code-repository
      required: true
    - name: project.repository
      type: string
      definition: Source repository URL.
      example: https://github.com/example/my-project
      status: canonical
      profile: code-repository
      required: false
    - name: project.documentation
      type: string
      definition: Documentation site URL.
      example: https://docs.example.com/my-project
      status: canonical
      profile: code-repository
      required: false
    - name: context.domain
      type: string
      definition: Business or technical domain of the project.
      example: e-commerce
      status: canonical
      profile: code-repository
      required: false
    - name: context.purpose
      type: string
      definition: What the project does (operational purpose, not document description).
      example: API backend for order processing
      status: canonical
      profile: code-repository
      required: false
    - name: context.constraints
      type: array
      definition: Non-functional requirements and constraints.
      example:
        - Must handle 10,000 requests per second
        - GDPR compliant
      status: canonical
      profile: code-repository
      required: false
    - name: stack.language
      type: string
      definition: Primary programming language.
      example: typescript
      status: canonical
      profile: code-repository
      required: false
    - name: stack.runtime
      type: string
      definition: Execution environment.
      example: node
      status: canonical
      profile: code-repository
      required: false
    - name: stack.version
      type: string
      definition: Language or runtime version.
      example: 20.x
      status: canonical
      profile: code-repository
      required: false
    - name: stack.framework
      type: string
      definition: Primary framework.
      example: express
      status: canonical
      profile: code-repository
      required: false
    - name: conventions.style
      type: string
      definition: Code style tool or guide.
      example: prettier
      status: canonical
      profile: code-repository
      required: false
    - name: conventions.testing
      type: string
      definition: Testing framework.
      example: jest
      status: canonical
      profile: code-repository
      required: false
    - name: conventions.documentation
      type: string
      definition: Documentation format.
      example: jsdoc
      status: canonical
      profile: code-repository
      required: false
    - name: owner
      type: string
      definition: Team or person responsible for this file or resource.
      example: platform-team
      notes: Used at file and directory level in code metadata. Also applies to media rights and database tables.
      status: canonical
      profile:
        - code-file
        - media-rights
        - database-table
      required: false
    - name: pure
      type: boolean
      definition: Whether function has no side effects.
      example: true
      status: canonical
      profile: code-function
      required: false
    - name: idempotent
      type: boolean
      definition: Whether repeated calls produce the same result.
      example: true
      status: canonical
      profile:
        - code-function
        - code-api
      required: false
    - name: complexity
      type: string
      definition: Time complexity in Big O notation.
      example: O(n)
      status: canonical
      profile: code-function
      required: false
    - name: throws
      type: array
      definition: Exception types this function may throw. Use raises for Python.
      example:
        - InvalidDiscountError
        - NegativePriceError
      status: canonical
      profile: code-function
      required: false
    - name: since
      type: string
      definition: Version when this function was introduced.
      example: 1.2.0
      status: canonical
      profile: code-function
      required: false
    - name: see
      type: array
      definition: Related functions or documentation.
      example:
        - calculateSubtotal
        - docs/pricing.md
      status: canonical
      profile: code-function
      required: false
    - name: pattern
      type: string
      definition: Design pattern used by this class.
      example: singleton
      validValues:
        - singleton
        - factory
        - observer
        - strategy
        - builder
        - adapter
        - decorator
        - proxy
        - command
        - mediator
      status: canonical
      profile: code-class
      required: false
    - name: threadSafe
      type: boolean
      definition: Whether class is safe for concurrent access.
      example: false
      status: canonical
      profile: code-class
      required: false
    - name: invariants
      type: array
      definition: Conditions that must always be true for this class.
      example:
        - If currentUser is set, tokens must be valid
        - Token refresh happens before expiry
      status: canonical
      profile: code-class
      required: false
    - name: dependency.purpose
      type: string
      definition: Why this dependency exists.
      example: HTTP server framework
      status: canonical
      profile: code-dependency
      required: false
    - name: dependency.critical
      type: boolean
      definition: Whether this dependency is critical to the project.
      example: true
      status: canonical
      profile: code-dependency
      required: false
    - name: dependency.upgradePolicy
      type: string
      definition: How aggressively to upgrade this dependency.
      example: conservative
      validValues:
        - aggressive
        - conservative
        - locked
        - manual
      status: canonical
      profile: code-dependency
      required: false
    - name: dependency.alternativesConsidered
      type: array
      definition: Alternative packages considered before choosing this dependency.
      example:
        - fastify
        - koa
      status: canonical
      profile: code-dependency
      required: false
    - name: testType
      type: string
      definition: Type of test file.
      example: integration
      validValues:
        - unit
        - integration
        - e2e
        - performance
        - security
        - smoke
        - acceptance
      status: canonical
      profile: code-test
      required: true
    - name: coverageTarget
      type: number
      definition: Target code coverage percentage.
      example: 90
      status: canonical
      profile: code-test
      required: false
    - name: subject
      type: string
      definition: What this test file tests.
      example: src/services/pricing.ts
      status: canonical
      profile: code-test
      required: true
    - name: fixtures
      type: array
      definition: Test data files required.
      example:
        - __fixtures__/sample-cart.json
      status: canonical
      profile: code-test
      required: false
    - name: method
      type: string
      definition: HTTP method for API endpoint.
      example: POST
      validValues:
        - GET
        - POST
        - PUT
        - PATCH
        - DELETE
        - HEAD
        - OPTIONS
      status: canonical
      profile: code-api
      required: true
    - name: path
      type: string
      definition: API endpoint path.
      example: /api/v1/orders
      status: canonical
      profile: code-api
      required: true
    - name: auth
      type: string
      definition: Authentication requirement for API endpoint.
      example: bearer
      validValues:
        - none
        - basic
        - bearer
        - api-key
        - oauth2
        - session
      status: canonical
      profile: code-api
      required: false
    - name: rateLimit
      type: string
      definition: Rate limiting configuration.
      example: 100/minute
      status: canonical
      profile: code-api
      required: false
    - name: cache.enabled
      type: boolean
      definition: Whether API response is cacheable.
      example: true
      status: canonical
      profile: code-api
      required: false
    - name: cache.ttl
      type: number
      definition: Cache time-to-live in seconds.
      example: 300
      status: canonical
      profile: code-api
      required: false
  profiles:
    - name: script
      description: Fields for executable scripts and cog.js files.
      required:
        - runtime
      optional:
        - dependencies
    - name: code-repository
      description: Repository-level metadata. Lives in mx.yaml, .mx/config.yaml, or package.json[mx].
      required:
        - project.name
        - project.description
      optional:
        - project.repository
        - project.documentation
        - context.domain
        - context.purpose
        - context.constraints
        - stack.language
        - stack.runtime
        - stack.version
        - stack.framework
        - conventions.style
        - conventions.testing
        - conventions.documentation
    - name: code-file
      description: File-level metadata. Appears in @mx comment blocks at the top of source files.
      optional:
        - owner
        - reviewers
        - ai.contextRequired
        - ai.contextProvides
        - ai.generationNotes
        - ai.reason
    - name: code-function
      description: Function-level metadata. Appears in @mx blocks within JSDoc or docstrings.
      optional:
        - pure
        - idempotent
        - complexity
        - throws
        - since
        - see
        - ai.confidence
        - ai.testCoverage
        - ai.edgeCases
        - ai.refactorNotes
        - ai.doNotModify
        - ai.reason
    - name: code-class
      description: Class-level metadata. Appears in @mx blocks within class JSDoc or docstrings.
      optional:
        - pattern
        - threadSafe
        - invariants
        - ai.sensitive
        - ai.modificationImpact
        - ai.confidence
        - ai.doNotModify
        - ai.contextRequired
        - ai.reason
    - name: code-inline
      description: Inline code annotations. @mx:begin/@mx:end for blocks, @mx:tag for lines.
      fields:
        - mx:begin
        - mx:end
        - mx:sensitive
        - mx:intentional
        - mx:todo
        - mx:ai
    - name: code-dependency
      description: Dependency metadata. Extends package.json or pyproject.toml with MX properties.
      optional:
        - dependency.purpose
        - dependency.critical
        - dependency.upgradePolicy
        - dependency.alternativesConsidered
        - ai.replacementPermitted
        - ai.upgradePermitted
    - name: code-test
      description: Test file metadata.
      required:
        - testType
        - subject
      optional:
        - coverageTarget
        - fixtures
        - ai.generationPermitted
        - ai.mustCover
        - ai.edgeCases
        - ai.doNotMock
    - name: code-api
      description: API endpoint metadata. OpenAPI extensions or route annotations.
      required:
        - method
        - path
      optional:
        - auth
        - rateLimit
        - cache.enabled
        - cache.ttl
        - idempotent
        - ai.safeToCall
        - ai.sensitive
        - ai.testMode
        - ai.sensitiveRequestFields
        - ai.sensitiveResponseFields
        - ai.sideEffects