MIME API

A Collection of Interesting Ideas,

Editor:
(GoDaddy)
Issues:
https://github.com/bmeck/node-proposal-mime-api/issues

Abstract

The MIME API Standard defines an API for interacting with MIME Types.

Goals

The MIME standard takes the following approach towards making MIMEs easier to use:

1. Infrastructure

This specification depends on the Infra Standard. [INFRA]

Some terms used in this specification are defined in the following standards and specifications:

To set the type given a mime and type, run these steps:

  1. If type is empty or does not consist entirely of HTTP token code points, throw a TypeError.

  2. Set type to type, in ASCII lowercase.

  3. Set mime’s type to the value of type.

To set the subtype given a mime and subtype, run these steps:

  1. If subtype is empty or does not consist entirely of HTTP token code points, throw a TypeError.

  2. Set subtype to subtype, in ASCII lowercase.

  3. Set mime’s subtype to the value of subtype.

To set a parameter given a parameters, name, and value, run these steps:

  1. If name is empty or does not consist entirely of HTTP token code points, throw a TypeError.

  2. If value is empty or does not consist entirely of HTTP quoted-string token code points, throw a TypeError.

  3. Set name to name, in ASCII lowercase.

  4. Set parameters’ property whose name is name to the value of value.

2. API

2.1. MIMEType class

[Constructor(USVString mime),
	Exposed=(Window,Worker)]
 interface MIMEType {
						attribute USVString type;
						attribute USVString subtype;
						attribute USVString essence;
	 [SameObject] readonly attribute MIMEParams params;
 
	 stringifier USVString toJSON();
 };
 

A MIMEType object has an associated mime that is a MIME and parameters that is a MIMEParams object.


The MIMEType(mime) constructor, when invoked, must run these steps:

  1. Let mimeType be null.

  2. Let mimeType be the result of running the parse a mime type on mime.

  3. If mimeType is failure, then throw a TypeError.

  4. Let params be mimeType’s parameters.

  5. Let result be a new MIMEType object.

  6. Set result’s mime to mimeType.

  7. Set result’s parameters object to a new MIMEParams, and then set that parameters object’s parameters object to params.

  8. Return result.

To parse a string into a MIME, invoke the MIMEType constructor with a single argument:

var input = "text/javascript; charset=utf-8;",
		 mime = new MIMEType(input)
 mime.subtype // "javascript"

This throws an exception if the input is not a valid MIME:

try {
	 var mime = new MIMEType("/")
 } catch(e) {
	 // that happened
 }

A MIMEType object can be used as input (while IDL requires a string as argument, a MIMEType object stringifies to its serialized form):

var mime = new MIMEType(new MIMEType("text/plain"))
 mime.type // "text"

The href attribute’s getter and the toJSON() method, when invoked, must return the serialize a mime type algorithm on context object’s mime.

The type attribute’s getter must run these steps:

  1. Return context object’s mime’s type.

The type attribute’s setter must run these steps:

  1. set the type given context object’s mime and the given value.

The subtype attribute’s getter must run these steps:

  1. Return context object’s mime’s subtype.

The subtype attribute’s setter must run these steps:

  1. set the subtype given context object’s mime and the given value.

The params attribute’s getter must return context object’s parameters object.

2.2. MIMEParams class

[Constructor(),
	Exposed=(Window,Worker)]
 interface MIMEParams {
	 void delete(USVString name);
	 USVString? get(USVString name);
	 boolean has(USVString name);
	 void set(USVString name, USVString value);
 
	 iterable<USVString, USVString>;
 };
 

A MIMEParams object has an associated parameters object parameters, which is initially null.

To create a new MIMEParams object using init, run these steps:

  1. Let params be a new MIMEParams object.

  2. Return params.

The MIMEParams() constructor, when invoked, must run these steps:

  1. Return the result of running create a new MIMEParams object.

The delete(name) method, when invoked, must run these steps:

  1. If there is not a property whose name is name in parameters, return false.

  2. Delete the property whose name is name in parameters.

  3. Return true.

The get(name) method, when invoked, must return the value of the property whose name is name in parameters, if there is such a property, and null otherwise.

The has(name) method, when invoked, must return true if there is a property whose name is name in parameters, and false otherwise.

The set(name, value) method, when invoked, must return the result of performing set a parameter given parameters, name, and value


2.3. MIME APIs elsewhere

A standard that exposes MIMEs, should expose the MIME as a string (by running serialize a mime type for an internal MIME’s mime). A standard should not expose a MIME using a MIMEType object. MIMEType objects are meant for MIME manipulation and reflection. In IDL the USVString type should be used.

The higher-level notion here is that values are to be exposed as immutable data structures.

If a standard decides to use a variant of the name "MIME" for a feature it defines, it should name such a feature "mime" (i.e., lowercase and not media type. Names such as "MIME", "MediaType", and "MIMEType" should not be used. However, if the name is a compound, "MIME" (i.e., uppercase) is preferred, e.g., "newMIME" and "oldMIME".

The EventSource and HashChangeEvent interfaces in HTML are examples of proper naming. [HTML]

Acknowledgments

This standard is written by Bradley Farias (GoDaddy, bradley.meck@gmail.com).

Conformance

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[DOM]
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[HTML]
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[INFRA]
Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
[MIMESNIFF]
Gordon P. Hemsley. MIME Sniffing Standard. Living Standard. URL: https://mimesniff.spec.whatwg.org/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[WebIDL]
Boris Zbarsky. Web IDL. 15 December 2016. ED. URL: https://heycam.github.io/webidl/

IDL Index

[Constructor(USVString mime),
	Exposed=(Window,Worker)]
 interface MIMEType {
						attribute USVString type;
						attribute USVString subtype;
						attribute USVString essence;
	 [SameObject] readonly attribute MIMEParams params;
 
	 stringifier USVString toJSON();
 };
 
 [Constructor(),
	Exposed=(Window,Worker)]
 interface MIMEParams {
	 void delete(USVString name);
	 USVString? get(USVString name);
	 boolean has(USVString name);
	 void set(USVString name, USVString value);
 
	 iterable<USVString, USVString>;
 };