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

There is clearly a fundamental difference of opinion here on how media types should be interpreted and there is a variety of precedent that is clouding what is the "right" path forward.

This is a vnd. registration and not a standards tree registration, and therefore my concerns about setting a wrong precedent are somewhat mitigated.  While I don't think this is the best choice, the registrant is convicted that it will provide the most desirable behaviour for consumers of their media type. The strongest of which being that existing browser based applications will render the content in the page rather then making users download the file.

With that perspective, I am going to withdraw my objection to this being registered as text/* media type.  With that out of the way, the registration can proceed.

Darrel


________________________________________
From: Amanda Baber via RT <[email protected]>
Sent: Friday, May 22, 2026 6:27 PM
Cc: [email protected] <[email protected]>; [email protected] <[email protected]>; [email protected] <[email protected]>; Darrel Miller <[email protected]>
Subject: [IANA #1445779] text/vnd.gist.mx registration request


Hi Darrel,

We have a response from Sachin:

===

Thank you for sharing the detailed feedback. The reviewer is right about the signature block. JWS, EdDSA, DID keys — none of that is human-readable prose and it doesn't belong in the core spec. We will remove it entirely. The core spec will now only has natural language prose fields plus two plain SHA-256 hash scalars for source integrity and tamper detection. We should have caught this earlier and we concede to this point fully.

On the suggestion to just use text/markdown, we've heard this couple of times now from the reviewer and want to be direct about why it doesn't work. The text/markdown tells a receiver it has a markdown document. It says nothing about whether comprehension layers are present or what produced them. Without a registered type, there's no stable identifier for third-party tools to implement .mx support against, and no way for any tool to know this file is anything other than plain markdown without parsing it first. That defeats the whole purpose of having a media type. text/calendar doesn't exist because machines can't read iCal, it exists so machines can identify it and present it correctly to humans. Same logic applies here.

On the vendor tree precedent concern, the RFC 6838 section 3.2 defines the vendor tree specifically for media types associated with commercially available products. That is exactly what this is. There are already dozens of vnd. registrations extending existing text formats. We're not doing anything unusual.

On text/calendar and text/vcard, we accept that the email inline rendering argument is weak, but those registrations have not been moved to application/ in 28 years and are still listed as text/ in the IANA registry. Our updated spec contains more natural language content than vCard and is less structurally complex than iCalendar. The standing precedent supports our registration.

The updated spec will be uploaded at https://github.com/gistmx/spec later today. We're happy to get on a call with the reviewer if that would help move this forward.

===

If you wanted to set up a Zoom call or something, I don't think IANA needs to be on it, but I could try to help set one up, if you wanted to suggest some times (without the list in copy). 

thanks,
Amanda

On Sat May 09 20:56:00 2026, [email protected] wrote:
> Sachin,
> 
> We should probably get other reviewers to weigh in because I don't
> think we are going to get alignment here.
> 
> Let's ignore the CR/LF issue because it is a fairly esoteric
> historical thing because as you say these things can be normalized
> during transmission.
> 
> You state,
> 
> > YAML frontmatter — structured metadata containing AI-generated
> > comprehension layers (summaries, voice script, ELI5 explanation).
> > These are all plain natural language prose. They are not structured
> > data
> 
> From the specification https://github.com/gistmx/spec#quick-overview
> 
> 
> mx_version: "1.1"
> generated: "2026-03-05T12:00:00Z"
> source: "README.md"
> source_hash:
> "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
> model: "qwen3-8b-instruct"
> 
> ...
> 
> signature:
>   type: "jws"
>   alg: "EdDSA"
>   kid: "did:web:gist.mx#mx-signing-key-1"
>   issuer: "https://gist.mx"
>   issued_at: "2026-03-05T12:00:01Z"
>   claims_version: "mxsig-1"
> 
> That really doesn't look like "natural language prose". I acknowledge
> that some of the key/value pairs use natural language as a value, but
> that doesn't remove the fact that the key name carries semantics that
> are expected to be understood by a consuming application.
> 
> > But in the frontmatter convention, YAML is simply a structured
> > container for human-readable text fields — not executable
> > instructions, not binary data, not application-specific processing
> > directives.
> 
> From this site https://www.markdownlang.com/advanced/frontmatter.html
> > Frontmatter is a way to add metadata to your Markdown documents using
> > YAML, TOML, or JSON at the beginning of the file. It's widely used in
> > static site generators and content management systems.
> 
> To paraphrase, frontmatter is metadata used by applications that
> understand that metadata. Yes, frontmatter is used by Gatsby, Hugo,
> Jeykll. The difference is, they are not trying to register a media
> type to communicate that a specific document contains a specific set
> of metadata.
> 
> > 2.2 The text/calendar and text/vcard precedents directly refute this
> > argument
> 
> text/calendar and text/vcard were first registered back in 1998 when
> the primary mode of transfer of these types was via MIME.  XML has a
> text/xml media type because early clients didn't know how to render
> application/xml. Early drafts of JSON referred to text/json because
> the argument was made that a human can read the text. But both JSON
> and YAML are only registered as an application type because those
> formats are defined for applications to read.  If the semantics of
> gist.mx were only intended for a human, or LLM, then the content could
> be written in prose with a markdown heading ## gist. Or it could be
> put in an appendix of the document. Frontmatter yaml would not be
> necessary and the media type could simply be text/markdown.
> 
> > Use case 1: AI agent HTTP content negotiation.
> 
> I'm a bit confused by the example you show with this accept header:
> 
> > Accept: text/markdown, text/plain;q=0.9, */*;q=0.1
> 
> This isn't the accept header that the acceptmarkdown.com site is
> suggesting, and what is shown above would actually allow a site to
> return application/gist.mx because it includes *.*.  Unless agents
> start sending text/* then no content negotiation is going to return
> text/vnd.gist.mx.  I see no indication that that is a plan from the
> site you shared.
> 
> > Use case 2: Git and version control systems.
> 
> Yes, the fact that some applications only render types they know of
> and text/* types is definitely an advantage using a text type.
> However, if that is an important use case for you, and as you claim,
> only humans are going to consume this front matter, then it is not
> clear to me why  you want to register a media type at all and why you
> wouldn't just use text/markdown as your media type.
> 
> > Use case 3: Email and messaging systems.
> 
> While the argument for email systems showing text/* content inline
> does have an appeal, it highlights why vCard or iCal should not have
> been text/* types because every time I have received a vCard or
> iCalendar in email they have been delivered as an attachment.
> 
> > Use case 4: The format is designed to be read by humans in plain text
> > editors
> 
> If so, then use text/markdown because the media type is providing zero
> value, because the human will almost never see it. And I don't know
> what value the front matter is bringing because, for example, plain
> text editors won't do text to speech on the "voice_brief" metadata.
> 
> > Use case 5: The format is an open standard, not an application
> > format.
> 
> You seem to be misunderstanding the meaning of the application type.
> It does not mean that the type is defined for use by a single
> application.  That majority of the media type registrations under the
> application type are open standards.
> 
> My pushback on this registration is not specific to this scenario.
> This registration would set an undesirable precedent for anyone else
> that decided they had some specific metadata they wanted to add to a
> markdown document.  Based on the feedback so far, I would suggest not
> creating a media type, but instead use text/markdown. It might be
> viable to follow the convention set here
> https://www.markdownlang.com/advanced/frontmatter.html#seo-and-social-
> media where a "og:" prefix is used to namespace properties.  It seems
> like a "gist:" prefix could be used in frontmatter properties to
> identify the specific semantics.  This would allow markdown documents
> to contain other frontmatter as well as gist related frontmatter.
> 
> Darrel
> 
> ________________________________
> From: Amanda Baber via RT <[email protected]>
> Sent: Monday, May 4, 2026 10:31 PM
> Cc: [email protected] <[email protected]>; Darrel Miller
> <[email protected]>
> Subject: [IANA #1445779] text/vnd.gist.mx registration request
> 
> Hi Darrel,
> 
> The requester has sent an argument for not moving to application. See
> below.
> 
> =====
> 
> * Response to Objection 1: CRLF / Line Ending Constraint
> 
> The first reviewer (April 8) noted that our specification states both
> LF and CRLF are supported, which is inconsistent with RFC 2046 §4.1.1
> for text/* types.
> 
> We accept this point and will correct the specification.
> 
> We will update the specification to state:
> 
> MX files use LF (0x0A) line endings. CRLF line endings MUST be
> normalized to LF before processing. Implementations generating MX
> files MUST use LF. Implementations receiving MX files via protocols
> that canonicalize to CRLF (e.g., SMTP) MUST accept CRLF but SHOULD
> normalize to LF for storage.
> 
> This is the same approach used by text/markdown (RFC 7763) and
> text/calendar (RFC 5545), both of which are text/* types that in
> practice encounter both line ending conventions but specify
> normalization behavior rather than rejecting the text/ tree. We are
> willing to update the published specification before the registration
> is finalized.
> 
> This objection is resolvable and should not be the basis for moving to
> application/.
> 
> * Response to Objection 2: "All semantic value is in the frontmatter,
> not in the natural language text"
> 
> This is the substantive disagreement and we would like to address it
> carefully.
> 
> - 2.1 The reviewer's premise is incorrect
> 
> The reviewer states: "All of the semantic value of the proposed media
> type vnd.gist.mx is in the frontmatter, not in the natural language
> text."
> 
> This mischaracterizes the format. An MX file has two parts:
> 
> YAML frontmatter — structured metadata containing AI-generated
> comprehension layers (summaries, voice script, ELI5 explanation).
> These are all plain natural language prose. They are not structured
> data in the sense of machine-executable instructions, schema
> definitions, or binary-encoded information. They are sentences and
> paragraphs written in human language, stored in YAML scalar fields.
> Markdown body — the complete original source document, unchanged.
> Both parts are natural language text. The YAML frontmatter contains
> metadata fields whose values are plain prose. This is functionally
> identical to the YAML frontmatter convention used by Jekyll, Hugo,
> GitHub Docs, Obsidian, and hundreds of other tools — a convention so
> widespread that it is explicitly documented by GitHub as their own
> authoring standard (https://docs.github.com/en/contributing/writing-
> for-github-docs/using-yaml-frontmatter).
> 
> The reviewer may be thinking of YAML as inherently application-type
> because of its use in configuration files and data exchange. But in
> the frontmatter convention, YAML is simply a structured container for
> human-readable text fields — not executable instructions, not binary
> data, not application-specific processing directives.
> 
> - 2.2 The text/calendar and text/vcard precedents directly refute this
> argument
> 
> If the reviewer's argument were applied consistently, it would
> invalidate two long-standing text/* registrations:
> 
> text/calendar (RFC 5545): iCalendar is registered as text/calendar.
> Its content is highly structured — it defines events, recurrences,
> time zones, alarms, attendees, organizer roles, and scheduling
> semantics. Every calendar application must parse and interpret this
> structured data to be useful; a plain text display of a .ics file is
> essentially meaningless to a human reader. The reviewer's argument —
> "the application cannot provide value without understanding the
> structured content" — applies identically to iCalendar. Yet it is
> text/calendar, not application/calendar.
> 
> text/vcard (RFC 6350): vCard is registered as text/vcard. It defines
> structured contact information: names, phone numbers, email addresses,
> postal addresses, organizational roles, photographs (as base64). Like
> iCalendar, a plain text display of a vCard file is navigable but
> requires structured parsing to be useful for its primary purpose
> (importing contacts). The RFC 6350 registration notes that
> applications include "mail user agents, instant messaging clients,
> address book applications, directory servers, and customer
> relationship management software" — all of which must structurally
> interpret the content. Yet it is text/vcard.
> 
> The MX format is less structurally complex than either of these. Our
> frontmatter fields are plain prose values in simple scalar YAML
> fields. If text/calendar and text/vcard belong in text/,
> text/vnd.gist.mx belongs there too.
> 
> - 2.3 The reviewer's suggested alternative is technically incorrect
> 
> The reviewer suggests: "application/vnd.gist.mx+markdown if such a
> suffix existed."
> 
> The +markdown structured syntax suffix does not exist in the IANA
> Structured Syntax Suffixes registry. Registering a type that
> references a non-existent suffix would introduce ambiguity rather than
> clarify semantics. We are not in a position to simultaneously register
> a new structured syntax suffix and a media type that uses it — that
> would be a multi-year standards process, not a vendor-tree
> registration.
> 
> Furthermore, application/ is the wrong signal for this content. Per
> RFC 2046 §4, the application/ type is appropriate for "data to be
> processed by some type of application program." MX files are not
> application-processed data in that sense — they are human-readable
> documents. The markdown body is written to be read by humans. The
> frontmatter summaries are written in natural language to be read by
> humans. The voice brief script is written to be spoken aloud to
> humans. This is a writing and reading format, precisely as RFC 7763
> describes markdown: "Markdown is a writing format."
> 
> - 2.4 The text/ prefix is essential for ecosystem adoption — and this
> is not merely a convenience argument
> 
> The reviewer's final question is: "Maybe it would be helpful if the
> requestor can explain why it would be better for their users if this
> media type had the text/ prefix."
> 
> We will answer this directly and concretely.
> 
> Use case 1: AI agent HTTP content negotiation.
> 
> AI agents and LLM-based tools routinely send Accept: text/markdown
> (per RFC 7763) to request markdown versions of resources. An emerging
> convention (documented at https://acceptmarkdown.com
> <https://acceptmarkdown.com/>) has agents sending:
> 
> Accept: text/markdown, text/plain;q=0.9, */*;q=0.1
> 
> The .mx format is a superset of text/markdown — it is the natural
> upgrade path. If .mx is registered as application/, it will never
> appear in these Accept headers without explicit effort, because agents
> are looking for text/* content types. text/vnd.gist.mx fits naturally
> into the established Accept: text/markdown negotiation ecosystem.
> application/vnd.gist.mx does not, and would require every agent
> implementation to be specifically updated to request it.
> 
> Use case 2: Git and version control systems.
> 
> Git, GitHub, GitLab, and Gitea use the Content-Type or file extension
> to determine how to render files in pull requests, code review
> interfaces, and file browsers. These systems treat text/* files as
> renderable text with diffs. An application/* type is typically treated
> as a binary blob — shown as "Binary file not shown" in git diffs. MX
> files are intended to be committed alongside .md files in version-
> controlled repositories and reviewed in pull requests. Registering as
> application/ would break this workflow entirely.
> 
> Use case 3: Email and messaging systems.
> 
> The iCalendar ecosystem (text/calendar) demonstrated that text/*
> registrations for structured formats enable email clients, messaging
> systems, and collaboration tools to render content inline rather than
> as attachments. If a developer sends an .mx file via email or attaches
> it in a Slack message, text/* hints to the client that the content is
> human-readable and can be rendered inline. application/* hints that
> specialized software is required to interpret it, discouraging inline
> rendering.
> 
> Use case 4: The format is designed to be read by humans in plain text
> editors — not consumed by applications.
> 
> The core design principle of .mx is backward compatibility. Any plain
> text editor — Vim, Emacs, VS Code, Notepad — can open an .mx file and
> a human can read it. The YAML frontmatter fields are labeled oneliner,
> gist, eli5, voice_brief — they are self-evidently human-readable
> prose. The format specification explicitly states: "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."
> 
> This is the opposite of an application/* type. The content is human-
> readable at rest, by design, without any application-specific
> processing.
> 
> Use case 5: The format is an open standard, not an application format.
> 
> The reviewer says: "If the authors believe that the important part of
> the document is the natural language content then they should
> encourage people to use the text/markdown media type and allow
> applications to detect the front matter independently of media type."
> 
> We understand this perspective, but it defeats the purpose of media
> type registration. If we do not register a media type, there is no
> standard way for any two implementations to agree on what an .mx file
> is. The entire point of registering text/vnd.gist.mx is so that any
> third-party tool — a markdown editor, a documentation generator, a
> content management system, a static site generator — can add .mx
> support by implementing against a stable, registered media type. The
> gist.mx service is one implementation, but the format is open (CC BY
> 4.0) and intended for widespread implementation. Registering as text/
> signals that this is a text-based, human-readable format that any text
> tool can participate in. Registering as application/ signals that only
> specialized applications should handle it, which directly contradicts
> the open-format vision.
> 
> We respectfully request that the reviewer reconsider the objection to
> text/ in light of the text/calendar, text/vcard precedents, and the
> practical adoption considerations above. We are happy to update the
> specification to address the CRLF constraint and to provide any
> additional clarification requested.
> 
> Thank you for your continued assistance with this registration.
> 
> Thanks.
> 
> Sachin
> 
> =====
> 
> thanks,
> Amanda
> 
> On Wed Apr 15 12:06:17 2026, [email protected] wrote:
> > From the specification:
> >
> > > The Markdown Experience (.mx) format extends standard markdown with
> > > structured AI-generated comprehension layers embedded in YAML
> > > frontmatter. It makes markdown documents accessible by providing
> > > multiple levels of understanding
> >
> > An application cannot provide these multiple levels of understanding
> > without understanding the structured content.  The fact that
> > applications can fall back to simple markdown rendering doesn't lead
> > us to register this as a text/* type.  It would suggest
> > application/vnd.gist.mx+markdown if such a suffix existed.
> >
> > All of the semantic value of the proposed media type vnd.gist.mx is
> > in
> > the frontmatter, not in the natural language text.  If the authors
> > believe that the important part of the document is the natural
> > language content then they should encourage people to use the
> > text/markdown media type and allow applications to detect the front
> > matter independently of media type.  As soon as the decision is made
> > to create a new media type to convey new semantics, then we should
> > focus on those semantics.  All of those semantics are in YAML
> > frontmatter.
> >
> > Maybe It would be helpful if the requestor can explain why it would
> > be
> > better for their users if this media type had the text/ prefix.
> >
> > Darrel
> > ________________________________
> > From: Amanda Baber via RT <[email protected]>
> > Sent: Monday, April 13, 2026 14:29
> > Cc: [email protected] <[email protected]>; Darrel Miller
> > <[email protected]>
> > Subject: [IANA #1445779] text/vnd.gist.mx registration request
> >
> > Hi Darrel,
> >
> > Response from the author:
> >
> > "We would like to keep it under text since all the contents of the mx
> > files are markup text. If we should remove support for CrLF line
> > endings we can add that to be reviewed under text. The mx conversion
> > is not application specific, any application can use this framework
> > to
> > create mx files."
> >
> > Can this continue to use text? If so, do they need to make changes to
> > the registration template?
> >
> > thanks,
> > Amanda
> >
> > On Wed Apr 08 12:14:32 2026, [email protected] wrote:
> > > 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]