From: Phillip Tao <ptao@apple.com>
Content-type: multipart/alternative;
 boundary="Apple-Mail=_3CE72728-B99B-4490-A43A-CCB5030659EB"
MIME-version: 1.0 (Mac OS X Mail 16.0 \(3901.200.12\))
Message-id: <7CAB2414-6D44-4987-839B-87AA5EEA8CF4@apple.com>
Date: Fri, 04 Sep 2026 19:12:42 +0200
To: sml@ietf.org
Message-ID-Hash: M6FCDWH2D5K3GOKB72QCXSRM57FMKIRA
Precedence: list
Subject: =?utf-8?q?=5BSml=5D_Proposal=3A_define_a_new_Structured-Email_header_field?=
Archived-At: 
 <https://mailarchive.ietf.org/arch/msg/sml/PB84hCEaPCMJkv2JJKzga3lSWn8>


--Apple-Mail=_3CE72728-B99B-4490-A43A-CCB5030659EB
Content-Transfer-Encoding: quoted-printable
Content-Type: text/plain;
	charset=us-ascii

Hi all,

I would like to propose that a new header field be defined in the core =
draft. The reason is that MUAs may want to be able to make choices about =
how and when to download a given message, based on the presence of =
structured data inside the message.

Proposed format:

    Structured-Email: representation=3Dmachine-readable; =
content=3Dvacation-notice;

The body of the header would be a tag-value list as defined by DKIM, =
with two tags: representation and content.

The "representation" tag can have four values: "machine-readable", =
"full", "partial", or "non".

These map to the types of representation defined in the core doc. In my =
reading of the core draft, machine-readable messages are strictly a =
subset of "full representation", while non-machine-readable messages may =
be any of the three representation types. Therefore, I've chosen to =
collapse "machine-readable" into one of the four representation types =
here, rather than express that as a separate tag. Note that "non" =
specifies the "non-representation" case, not the absence of structured =
data.

The "content" tag would be a comma-separated list of values identifying =
the type of structured content in the message. A new IANA registry would =
be created to register these types.

I would propose that the header with at least a representation tag be =
required, while the content tag would be optional.

FAQ

Q: Why do we need this in addition to the message flags defined in =
section 6 of the core draft?
A: Two main reasons:
    1. The IMAP flags rely on mailbox provider implementation. For a MUA =
designed to interoperate with a variety of MBPs, a reliable signal is =
needed for whether a message has structured content or not. Because the =
sender is the one attaching the structured data, they're the natural =
party to also attach metadata about the presence of the structured data.
    2. The currently defined flags do not convey the type of structured =
data carried in the message. This is important because the MUA may not =
understand all possible structured data that can be in an email message, =
and may only care about certain types. Even among the types that it does =
care about, the representation type and content type may inform when and =
how it wants to download the message.
    For example, for a machine-readable one-time-code, a MUA might want =
to download it immediately, even when it would otherwise hold off on =
downloading message bodies due to power or network usage concerns. It =
may also just download the structured data part and not any other MIME =
part. For a message with a boarding pass or ticket, it may want to =
download just that part for now, and download the rest of the body parts =
according to its normal body download scheduling.

Q: Should this replace the message flags defined in section 6?
A: I lean toward yes, but I can also see some potential use cases for =
the message flags (like, maybe being better supported for IMAP SEARCH)?

Q: Why does this need to be a header? Can the same information not be =
derived from the BODYSTRUCTURE?
A: Currently, structured data is defined as being carried exclusively in =
application/ld+json or application/jose parts. However, the presence of =
MIME parts of those types alone are not sufficient to determine that =
they are actually structured data, as opposed to some an attachment =
which happens to use the same format. An alternative could be to define =
a new attribute on the Content-Type or Content-Disposition.
    More importantly, however, there has been discussion of allowing =
some cases of structured data being allowed to be carried in the =
text/html part. In that case, it is impossible to tell a message with =
structured data apart from any other HTML message.

Q: Why do we need a new IANA registry?
A: The current IANA registry defined by the core draft is for =
vocabularies. This new registry would be for content types. Some content =
types may share vocabularies. One content type may also use multiple =
vocabularies. Many content types may not need any vocabulary defined in =
the IANA registry, and may simply use schema.org <http://schema.org/>.
    The broader question of why the content-type is needed at all is =
addressed in question 1.

Open to any feedback, questions, or comments.

- Phillip


--Apple-Mail=_3CE72728-B99B-4490-A43A-CCB5030659EB
Content-Transfer-Encoding: quoted-printable
Content-Type: text/html;
	charset=us-ascii

<html aria-label=3D"message body"><head><meta http-equiv=3D"content-type" =
content=3D"text/html; charset=3Dus-ascii"></head><body =
style=3D"overflow-wrap: break-word; -webkit-nbsp-mode: space; =
line-break: after-white-space;"><div>Hi all,</div><div><br></div>I would =
like to propose that a new header field be defined in the core draft. =
The reason is that MUAs may want to be able to make choices about how =
and when to download a given message, based on the presence of =
structured data inside the message.<div><br></div><div><b>Proposed =
format:</b><br><div><br></div><div><font face=3D"Menlo">&nbsp; &nbsp; =
Structured-Email: representation=3Dmachine-readable; =
content=3Dvacation-notice;</font></div></div><div><br></div><div>The =
body of the header would be a tag-value list as defined by DKIM, with =
two tags: representation and content.</div><div><br></div><div>The =
"representation" tag can have four values: "machine-readable", "full", =
"partial", or "non".</div><div><br></div><div>These map to the types of =
representation defined in the core doc. In my reading of the core draft, =
machine-readable messages are strictly a subset of "full =
representation", while non-machine-readable messages may be any of the =
three representation types. Therefore, I've chosen to collapse =
"machine-readable" into one of the four representation types here, =
rather than express that as a separate tag. Note that "non" specifies =
the "non-representation" case, not the absence of structured =
data.</div><div><br></div><div>The "content" tag would be a =
comma-separated list of values identifying the type of structured =
content in the message. A new IANA registry would be created to register =
these types.</div><div><br></div><div>I would propose that the header =
with at least a representation tag be required, while the content tag =
would be =
optional.</div><div><br></div><div><b>FAQ</b></div><div><br></div><div><b>=
Q: </b>Why do we need this in addition to the message flags defined in =
section 6 of the core draft?</div><div><b>A: </b>Two main =
reasons:</div><div>&nbsp; &nbsp; 1. The IMAP flags rely on mailbox =
provider implementation. For a MUA designed to interoperate with a =
variety of MBPs, a reliable signal is needed for whether a message has =
structured content or not. Because the sender is the one attaching the =
structured data, they're the natural party to also attach metadata about =
the presence of the structured data.</div><div>&nbsp; &nbsp; 2. The =
currently defined flags do not convey the <i>type</i>&nbsp;of structured =
data carried in the message. This is important because the MUA may not =
understand all possible structured data that can be in an email message, =
and may only care about certain types. Even among the types that it does =
care about, the representation type and content type may inform when and =
how it wants to download the message.</div><div>&nbsp; &nbsp; For =
example, for a machine-readable one-time-code, a MUA might want to =
download it immediately, even when it would otherwise hold off on =
downloading message bodies due to power or network usage concerns. It =
may also just download the structured data part and not any other MIME =
part. For a message with a boarding pass or ticket, it may want to =
download just that part for now, and download the rest of the body parts =
according to its normal body download =
scheduling.</div><div><br></div><div><b>Q: </b>Should this replace the =
message flags defined in section 6?</div><div><b>A:</b>&nbsp;I lean =
toward yes, but I can also see some potential use cases for the message =
flags (like, maybe being better supported for IMAP =
SEARCH)?</div><div><br></div><div><b>Q: </b>Why does this need to be a =
header? Can the same information not be derived from the =
BODYSTRUCTURE?</div><div><b>A:</b>&nbsp;Currently, structured data is =
defined as being carried exclusively in application/ld+json or =
application/jose parts. However, the presence of MIME parts of those =
types alone are not sufficient to determine that they are actually =
structured data, as opposed to some an attachment which happens to use =
the same format. An alternative could be to define a new attribute on =
the Content-Type or Content-Disposition.</div><div>&nbsp; &nbsp; More =
importantly, however, there has been discussion of allowing some cases =
of structured data being allowed to be carried in the text/html part. In =
that case, it is impossible to tell a message with structured data apart =
from any other HTML message.</div><div><br></div><div><b>Q:</b>&nbsp;Why =
do we need a new IANA registry?</div><div><b>A:</b>&nbsp;The current =
IANA registry defined by the core draft is for <i>vocabularies</i>. This =
new registry would be for <i>content types</i>. Some content types may =
share vocabularies. One content type may also use multiple vocabularies. =
Many content types may not need any vocabulary defined in the IANA =
registry, and may simply use <a =
href=3D"http://schema.org">schema.org</a>.</div><div>&nbsp; &nbsp; The =
broader question of why the content-type is needed at all is addressed =
in question 1.</div><div><br></div><div>Open to any feedback, questions, =
or comments.</div><div><br></div><div>- =
Phillip</div><div><br></div><div><br></div><div><br></div><div><br></div><=
div><br></div><div><br></div><div><br></div></body></html>=

--Apple-Mail=_3CE72728-B99B-4490-A43A-CCB5030659EB--