Skip to main content

Shepherd writeup

(1) What type of RFC is being requested (BCP, Proposed Standard, Internet 
Standard, Informational, Experimental, or Historic)? Why is this the proper type of 
RFC? Is this type of RFC indicated in the title page header?

This document is being requested for publication as a Proposed Standard. The 
document was produced with the expectation that it would be widely used in 
conjunction with the JSON Web Algorithms (JWA), JSON Web Encryption (JWE), and 
JSON Web Key (JWK) documents as part of a suite of documents providing security  
services for JSON. As such, it is reasonable for these documents to progress on the 
standards track. The intended status is shown on the title page.  

(2) The IESG approval announcement includes a Document Announcement Write-
Up. Please provide such a Document Announcement Write-Up. Recent examples can 
be found in the "Action" announcements for approved documents. The approval 
announcement contains the following sections:

Technical Summary: 

This document, JSON Web Signature (JWS), represents content secured with digital 
signatures or Message Authentication Codes (MACs) using JavaScript Object 
Notation (JSON) based data structures.  Two serializations for JWS objects are 
defined, a compact, URL-safe representation and a JSON serialization. 
Working Group Summary:

The document has clear working group consensus for publication, and has been 
reviewed by several WG participants since its initial adoption as a working group 
Document Quality:
This document has been reviewed and revised many times. There are multiple 
implementations of this document. Some of these are listed at: (see the JWT/JWS/JWE/JWK/JWA 
Implementations section). There were no specific external expert reviews 
conducted; however, the WGLC notification was sent to the W3C WebCrypto 
working group. 

Karen O'Donoghue is acting as the Document Shepherd.  Kathleen Moriarty is the 
Responsible Area Director. 

(3) Briefly describe the review of this document that was performed by the 
Document Shepherd. If this version of the document is not ready for publication, 
please explain why the document is being forwarded to the IESG.
The document shepherd has followed the working group process and reviewed the 
final document and feels this document is ready for IESG review. Note, the 
document shepherd did not validate the examples in the appendices. 

 (4) Does the document Shepherd have any concerns about the depth or breadth of 
the reviews that have been performed?
The document shepherd does not have any concerns about the reviews that were 

(5) Do portions of the document need review from a particular or from broader 
perspective, e.g., security, operational complexity, AAA, DNS, DHCP, XML, or 
internationalization? If so, describe the review that took place.

This document registers two new Media Types in the MIME Media Types registry.  A 
request for review has been sent to the media type review mailing list. 
(6) Describe any specific concerns or issues that the Document Shepherd has with 
this document that the Responsible Area Director and/or the IESG should be aware 
of? For example, perhaps he or she is uncomfortable with certain parts of the 
document, or has concerns whether there really is a need for it. In any event, if the 
WG has discussed those issues and has indicated that it still wishes to advance the 
document, detail those concerns here.
The Document Shepherd is comfortable with this document as a stable specification 
of two serializations for JWS objects. This specification has been implemented and 
adopted in some communities (most especially OpenID). 

(7) Has each author confirmed that any and all appropriate IPR disclosures required 
for full conformance with the provisions of BCP 78 and BCP 79 have already been 
filed. If not, explain why?

All authors have confirmed that they have no relevant IPR disclosures.
(8) Has an IPR disclosure been filed that references this document? If so, summarize 
any WG discussion and conclusion regarding the IPR disclosures.

Certicom Corporation has filed an IPR discloser dealing with elliptical curve 
technologies.  These patents are the normal IPR disclosure from Certicom and 
received only a brief discussion. The group was notified of an additional possible 
patent from IBM, but no discloser was ever filed and no discussion was ever held on 
the patent. (The patent appears to be a mechanical transformation of XML digital 
signatures and mapping it onto JSON.)
(9) How solid is the WG consensus behind this document? Does it represent the 
strong concurrence of a few individuals, with others being silent, or does the WG as 
a whole understand and agree with it?

The document represents a solid WG consensus, however there are some issues for 
which consensus was difficult with strong proponents on both sides of the issues.
(10) Has anyone threatened an appeal or otherwise indicated extreme discontent? If 
so, please summarize the areas of conflict in separate email messages to the 
Responsible Area Director. 

There have been no threats of anyone appealing the documents.
(11) Identify any ID nits the Document Shepherd has found in this document. (See and the Internet-Drafts Checklist). Boilerplate 
checks are not enough; this check needs to be thorough. 

The following nit errors were identified. These nits are all related to downrefs to 
algorithm documents and are discussed further in (15). 

** Downref: Normative reference to an Historic RFC: RFC 1421
** Downref: Normative reference to an Informational RFC: RFC 2818
(12) Describe how the document meets any required formal review criteria, such as 
the MIB Doctor, media type, and URI type reviews.

This document defines two new media types for the MIME Media Types registry:
A request for review has been sent to the media type review mailing list.
(13) Have all references within this document been identified as either normative or 

All references are tagged as normative or informative.
(14) Are there normative references to documents that are not ready for 
advancement or are otherwise in an unclear state? If such normative references 
exist, what is the plan for their completion?

All normative references are on track for completion or are completed.
(15) Are there downward normative references (see RFC 3967)? If so, list these 
downward references to support the Area Director in the Last Call procedure.

There are a number of down-references to information documents.  These are all 
algorithm documents so this is normal procedure.  There is one down-reference to 
an Historic document.
      RFC 1421 - Privacy Enhancement for Internet Electronic Mail: Part I: Message 
Encryption and Authentication Procedures
      RFC 2818 - HTTP Over TLS
(16) Will publication of this document change the status of any existing RFCs? Are 
those RFCs listed on the title page header, listed in the abstract, and discussed in the 
introduction? If the RFCs are not listed in the Abstract and Introduction, explain 
why, and point to the part of the document where the relationship of this document 
to the other RFCs is discussed. If this information is not in the document, explain 
why the WG considers it unnecessary.

These documents are all first time documents.  They will not change the status of 
any existing documents.
(17) Describe the Document Shepherd's review of the IANA considerations section, 
especially with regard to its consistency with the body of the document. Confirm 
that all protocol extensions that the document makes are associated with the 
appropriate reservations in IANA registries. Confirm that any referenced IANA 
registries have been clearly identified. Confirm that newly created IANA registries 
include a detailed specification of the initial contents for the registry, that 
allocations procedures for future registrations are defined, and a reasonable name 
for the new registry has been suggested (see RFC 5226).
(18) List any new IANA registries that require Expert Review for future allocations. 
Provide any public guidance that the IESG would find useful in selecting the IANA 
Experts for these new registries.

This document defines the following IANA registry including a name, initial entries, 
and future allocation procedures:
      JSON Web Signature and Encryption Header Parameters Registry
(19) Describe reviews and automated checks performed by the Document Shepherd 
to validate sections of the document written in a formal language, such as XML code, 
BNF rules, MIB definitions, etc.

There are no formal language sections in these documents.