JSON Type Definition
RFC 8927

Document Type RFC - Experimental (November 2020; No errata)
Author Ulysse Carion 
Last updated 2020-11-06
Replaces draft-ucarion-jddf
Stream ISE
Formats plain text html xml pdf htmlized bibtex
IETF conflict review conflict-review-ucarion-json-type-definition
Stream ISE state Published RFC
Consensus Boilerplate Unknown
Document shepherd Adrian Farrel
Shepherd write-up Show (last changed 2020-05-06)
IESG IESG state RFC 8927 (Experimental)
Telechat date
Responsible AD (None)
Send notices to Adrian Farrel <rfc-ise@rfc-editor.org>
IANA IANA review state Version Changed - Review Needed
IANA action state No IANA Actions


Independent Submission                                         U. Carion
Request for Comments: 8927                                       Segment
Category: Experimental                                     November 2020
ISSN: 2070-1721

                          JSON Type Definition

Abstract

   This document proposes a format, called JSON Type Definition (JTD),
   for describing the shape of JavaScript Object Notation (JSON)
   messages.  Its main goals are to enable code generation from schemas
   as well as portable validation with standardized error indicators.
   To this end, JTD is intentionally limited to be no more expressive
   than the type systems of mainstream programming languages.  This
   intentional limitation, as well as the decision to make JTD schemas
   be JSON documents, makes tooling atop of JTD easier to build.

   This document does not have IETF consensus and is presented here to
   facilitate experimentation with the concept of JTD.

Status of This Memo

   This document is not an Internet Standards Track specification; it is
   published for examination, experimental implementation, and
   evaluation.

   This document defines an Experimental Protocol for the Internet
   community.  This is a contribution to the RFC Series, independently
   of any other RFC stream.  The RFC Editor has chosen to publish this
   document at its discretion and makes no statement about its value for
   implementation or deployment.  Documents approved for publication by
   the RFC Editor are not candidates for any level of Internet Standard;
   see Section 2 of RFC 7841.

   Information about the current status of this document, any errata,
   and how to provide feedback on it may be obtained at
   https://www.rfc-editor.org/info/rfc8927.

Copyright Notice

   Copyright (c) 2020 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (https://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.

Table of Contents

   1.  Introduction
     1.1.  Terminology
     1.2.  Scope of Experiment
   2.  Syntax
     2.1.  Root vs. Non-root Schemas
     2.2.  Forms
       2.2.1.  Empty
       2.2.2.  Ref
       2.2.3.  Type
       2.2.4.  Enum
       2.2.5.  Elements
       2.2.6.  Properties
       2.2.7.  Values
       2.2.8.  Discriminator
     2.3.  Extending JTD's Syntax
   3.  Semantics
     3.1.  Allowing Additional Properties
     3.2.  Errors
     3.3.  Forms
       3.3.1.  Empty
       3.3.2.  Ref
       3.3.3.  Type
       3.3.4.  Enum
       3.3.5.  Elements
       3.3.6.  Properties
       3.3.7.  Values
       3.3.8.  Discriminator
   4.  IANA Considerations
   5.  Security Considerations
   6.  References
     6.1.  Normative References
     6.2.  Informative References
   Appendix A.  Rationale for Omitted Features
     A.1.  Support for 64-Bit Numbers
     A.2.  Support for Non-root Definitions
   Appendix B.  Comparison with CDDL
   Appendix C.  Example
   Acknowledgments
   Author's Address

1.  Introduction

   This document describes a schema language for JSON [RFC8259] called
   JSON Type Definition (JTD).

   There exist many options for describing JSON data.  JTD's niche is to
   focus on enabling code generation from schemas; to this end, JTD's
   expressiveness is intentionally limited to be no more powerful than
   what can be expressed in the type systems of mainstream programming
   languages.

   The goals of JTD are to:

   *  Provide an unambiguous description of the overall structure of a
      JSON document.

   *  Be able to describe common JSON data types and structures (that
      is, the data types and structures necessary to support most JSON
      documents and that are widely understood in an interoperable way
      by JSON implementations).

   *  Provide a single format that is readable and editable by both
      humans and machines and that can be embedded within other JSON
      documents.  This makes JTD a convenient format for tooling to
      accept as input or produce as output.

   *  Enable code generation from JTD schemas.  JTD schemas are meant to
      be easy to convert into data structures idiomatic to mainstream
      programming languages.

   *  Provide a standardized format for error indicators when data does
      not conform with a schema.

   JTD is intentionally designed as a rather minimal schema language.
   Thus, although JTD can describe some categories of JSON, it is not
   able to describe its own structure; this document uses Concise Data
   Definition Language (CDDL) [RFC8610] to describe JTD's syntax.  By
   keeping the expressiveness of the schema language minimal, JTD makes
   code generation and standardized error indicators easier to
   implement.
Show full document text