[media-types] Re: [IANA #1445779] text/vnd.gist.mx registration request

Hi Amanda,

Here is my review of this registration request.

1. The author should change the type from text/ to application/. The text/ top-level type carries CRLF and charset constraints (RFC 2046 §4.1.1, RFC 6657 §3) that are unnecessarily burdensome for this format. application/vnd.gist.mx avoids those issues. Specifically the specification states that both LF and CR/LF are supported which is not consistent with the definition of text/* types.

Darrel

________________________________
From: Amanda Baber via RT <[email protected]>
Sent: Wednesday, April 01, 2026 19:09
Cc: [email protected] <[email protected]>; Darrel Miller <[email protected]>
Subject: [IANA #1445779] text/vnd.gist.mx registration request

Hi Darrel,

Sending a reminder for this request from March 9th.

thanks,
Amanda

On Mon Mar 09 23:32:21 2026, amanda.baber wrote:
> Hi Darrel,
>
> Would it be possible to review this for us by March 23rd?
>
> thanks,
> Amanda
>
> =====
>
> Name: Sachin Nagda
>
> Email: [email protected]
>
> Media type name: text
>
> Media subtype name: vnd.gist.mx
>
> Required parameters: N/A
>
> Optional parameters: charset: Specifies the character encoding of the
> content. If omitted, UTF-8 is
> assumed, consistent with modern markdown processing. The charset
> parameter
> follows the same conventions defined in RFC 6657 for textual media
> types.
>
> version: Indicates the version of the MX format specification that the
> file
> conforms to. The value is a dotted decimal version number (e.g.,
> "1.0").
> If omitted, version "1.0" is assumed.
>
> Encoding considerations: 8bit
>
> MX files are UTF-8 encoded plain text consisting of YAML frontmatter
> delimited
> by "---" lines, followed by a standard markdown document body. The
> format does
> not contain NUL octets, binary data, or lines exceeding 998 octets
> under normal
> usage. Content is line-oriented text separated by CRLF or LF line
> endings.
>
> In rare cases where the embedded markdown body contains very long
> lines (e.g.,
> base64-encoded inline images in markdown or extremely long URLs),
> lines may
> exceed 998 octets. Implementations generating such content should use
> Content-Transfer-Encoding of "binary" or "quoted-printable" when
> transmitting
> via protocols that impose line length limits (e.g., SMTP).
>
> Security considerations: 1. Active/executable content: MX files do not
> contain active or executable
> content. The format consists entirely of UTF-8 text: YAML frontmatter
> metadata fields followed by a markdown document body. No scripting,
> macros, or executable instructions are defined by the format. However,
> the markdown body may contain raw HTML if the source markdown includes
> it. Consumers that render embedded HTML should apply the same
> sanitization practices used for standard markdown rendering (e.g.,
> stripping <script> tags, disallowing event handlers).
>
> 2. Privacy and integrity: MX files may contain AI-generated
> comprehension
> layers (summaries, voice scripts, explanatory text) derived from the
> source markdown. These layers could inadvertently disclose sensitive
> information from the source document in a more accessible form. The
> format itself includes a source_hash field (SHA-256) that allows
> consumers to verify whether the comprehension layers correspond to
> a specific source document, providing a basic integrity check.
> The format does not provide encryption or digital signature
> mechanisms.
>
> 3. External privacy/integrity services: For documents requiring
> confidentiality or tamper detection, standard transport-layer security
> (TLS) should be used for transmission, and external signing mechanisms
> (e.g., PGP, S/MIME) can be applied to the file as with any text
> document.
>
> 4. Underlying format considerations: MX files use YAML (in the
> frontmatter)
> and markdown (in the body), both of which are well-established text
> formats. YAML parsing carries known security considerations: consumers
> MUST use safe YAML loading (e.g., YAML.safeLoad or equivalent) to
> prevent code execution through YAML deserialization attacks. The
> frontmatter section is constrained to simple scalar values, sequences,
> and mappings; no YAML tags, anchors, or aliases are used in the format
> specification.
>
> 5. The format may reference an external audio file via the
> voice_brief.audio_hash field. This is a content hash, not a URL;
> it does not create an automatic external reference. Consumers that
> resolve audio files should verify the hash matches the retrieved
> content.
>
> 6. The guidance section (in version 2.0 of the format) may contain
> author-attributed metadata including the author's name and editorial
> guidance. This constitutes personal data and should be handled in
> accordance with applicable data protection regulations.
>
> Interoperability considerations: MX files are designed for maximum
> backward compatibility with existing
> markdown tooling. An MX file is structurally identical to a markdown
> file
> with YAML frontmatter, a pattern widely supported by static site
> generators
> (Jekyll, Hugo, Gatsby), documentation tools (MkDocs, Docusaurus), and
> text
> editors (VS Code, Obsidian, Typora).
>
> Any application that processes standard markdown with YAML frontmatter
> can
> open and render an MX file, displaying the frontmatter as metadata and
> the
> body as rendered markdown. MX-unaware applications will simply ignore
> the
> comprehension layer fields in the frontmatter.
>
> MX-aware applications additionally parse the frontmatter to extract
> and
> display the structured comprehension layers (oneliner, gist,
> voice_brief,
> eli5) and may resolve the associated audio content.
>
> The YAML frontmatter conforms to the YAML 1.2 specification and uses
> only
> the JSON-compatible subset (scalars, sequences, mappings). The
> markdown
> body follows the CommonMark specification with GitHub Flavored
> Markdown
> (GFM) extensions.
>
> Line endings may be either CRLF or LF. Consumers should accept both.
>
> Published specification: The MX format specification is published and
> maintained at:
>
> https://www.gist.mx/#spec
>
> The specification defines:
> - The YAML frontmatter schema (required and optional fields)
> - The five comprehension layers and their constraints
> - The source hash verification mechanism
> - The multi-file project MX variant
> - JSON Schema for frontmatter validation
>
> The specification source is additionally available in the project's
> public GitHub repository:
>
> https://github.com/gistmx/spec/tree/main/v1
>
> Applications which use this media: The MX format is used by the
> gist.mx platform and associated tools for
> creating, distributing, and consuming AI-enriched markdown documents.
>
> Applications that produce MX files:
> - gist.mx web application (https://gist.mx)
> - @gistmx/cli command-line tool (published on npm)
> - gistmx/convert-action GitHub Action
> - gist.mx REST API
>
> Applications that consume MX files:
> - gist.mx web viewer (renders all comprehension layers with audio
> playback)
> - gist.mx mobile applications (iOS and Android)
> - Any standard markdown editor or viewer (backward-compatible
> rendering)
> - Any YAML-aware text editor (frontmatter is valid YAML)
>
> The format is also designed for use in CI/CD pipelines where MX files
> are
> auto-generated alongside source markdown files in version-controlled
> repositories.
>
> Fragment identifier considerations: Fragment identifiers for MX files
> follow the same conventions as for
> text/markdown (RFC 7763). Fragment identifiers reference sections of
> the
> rendered markdown body using heading-derived anchors (e.g., #section-
> name).
>
> Additionally, MX-aware consumers may recognize the following fragment
> identifiers for navigating to specific comprehension layers:
>
> #mx-oneliner - Navigate to the one-liner layer
> #mx-gist - Navigate to the core gist layer
> #mx-voice - Navigate to the voice brief layer
> #mx-eli5 - Navigate to the ELI5 layer
> #mx-full - Navigate to the full document body
>
> These layer fragment identifiers are advisory. MX-unaware consumers
> will
> ignore them, consistent with standard fragment identifier handling for
> unknown fragments.
>
> Restrictions on usage: N/A. The MX format may be used in any context
> where text/markdown is
> appropriate. No restrictions on protocol or application context.
>
> Provisional registration? (standards tree only): No
>
> Additional information:
>
> 1. Deprecated alias names for this type: N/A
> 2. Magic number(s): The byte sequence 0x2D 0x2D 0x2D 0x0A (ASCII: "---
> \n") at position 0 followed by the string "mx_version:" within the
> first 256 bytes. The leading "---" is the YAML frontmatter delimiter,
> and the presence of "mx_version" within the frontmatter distinguishes
> MX files from standard markdown with YAML frontmatter.
> 3. File extension(s): .mx
> 4. Macintosh file type code: TEXT
> 5. Object Identifiers: N/A
>
> General Comments: The MX (Markdown Experience) format extends standard
> markdown with
> structured AI-generated comprehension layers embedded in YAML
> frontmatter.
> It is designed to make markdown documents more accessible by providing
> multiple levels of understanding: a single-sentence summary, a short
> gist,
> a conversational voice-ready script, and a simplified explanation.
>
> The format prioritizes backward compatibility: any tool that reads
> markdown
> with YAML frontmatter can process MX files without modification. The
> additional comprehension layers are purely additive metadata.
>
> The MX format specification is versioned (starting at 1.0) and
> includes
> provisions for future extensions including guided authoring metadata
> and
> edit history tracking.
>
> The ".mx" file extension does not conflict with any currently
> registered
> IANA media type file extension.
>
> Person to contact for further information:
>
> 1. Name: Sachin Nagda
> 2. Email: [email protected]
>
> Intended usage: COMMON
>
> Author/Change controller: Sachin Nagda, gist.mx

_______________________________________________
media-types mailing list -- [email protected]
To unsubscribe send an email to [email protected]