Concise Problem Details: Body Error Position
draft-amsuess-core-pd-body-error-position-00

CoRE                                                           C. Amsüss
Internet-Draft                                           4 February 2023
Intended status: Informational                                          
Expires: 8 August 2023

              Concise Problem Details: Body Error Position
              draft-amsuess-core-pd-body-error-position-00

Abstract

   This defines a single standard problem detail for use with the
   Concise Problem Details format: Request Body Error Position.  Using
   this detail, the server can point at the position inside the client's
   request body that induced the error.

Discussion Venues

   This note is to be removed before publishing as an RFC.

   Discussion of this document takes place on the Constrained RESTful
   Environments Working Group mailing list (core@ietf.org), which is
   archived at https://mailarchive.ietf.org/arch/browse/core/.

   Source for this draft and an issue tracker can be found at
   https://gitlab.com/chrysn/problem-detail-body-error-position.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at https://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on 8 August 2023.

Copyright Notice

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

Amsüss                    Expires 8 August 2023                 [Page 1]
Internet-Draft  Concise Problem Details: Body Error Posi   February 2023

   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.  Code Components
   extracted from this document must include Revised BSD License text as
   described in Section 4.e of the Trust Legal Provisions and are
   provided without warranty as described in the Revised BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
     1.1.  Terminology . . . . . . . . . . . . . . . . . . . . . . .   2
     1.2.  Document lifecycle  . . . . . . . . . . . . . . . . . . .   2
   2.  Request Body Error Position . . . . . . . . . . . . . . . . .   3
   3.  Usage example . . . . . . . . . . . . . . . . . . . . . . . .   3
   4.  IANA considerations . . . . . . . . . . . . . . . . . . . . .   4
   5.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   4
     5.1.  Normative References  . . . . . . . . . . . . . . . . . .   4
     5.2.  Informative References  . . . . . . . . . . . . . . . . .   4
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .   5

1.  Introduction

   Concise Problem Details for CoAP APIs [RFC9290] describes how a
   server can provide details about an error processing a client
   request, and how to extend these error messages.  This document uses
   that extension mechanism and adds the Request Body Error Position
   detail.

1.1.  Terminology

   The description of the problem detail uses the term "body" as defined
   in [RFC7959].

1.2.  Document lifecycle

   Registering a standard problem detail merely requires a
   specification, not an RFC (let alone of a particular track).

   It is the author's opinion that an Interned Draft can provide
   sufficient specification, and is more suitable than an informal note
   published at some arbitrary website due to its archival through the
   draft submission process.

   It is not expected that this draft will proceed all the way to an
   RFC; instead, once sufficiently mature, it will be used as a
   reference in a request to IANA, and updated with the assigned number.

Amsüss                    Expires 8 August 2023                 [Page 2]
Internet-Draft  Concise Problem Details: Body Error Posi   February 2023

   This document will eventually expire as an Internet Draft, but
   nonetheless be usable as the permanent reference for the assigned
   problem detail.

2.  Request Body Error Position

   The Request Body Error Position problem detail indicates that the
   error described by the Concise Problem Details response resulted from
   processing the request body.  The numeric value indicates a byte
   position inside that body that corresponds to the error.  The precise
   error position for invalid data may vary by implementation -- for
   example, if a numeric value inside a CBOR ([STD94]) item exceeds the
   expected range, it may indicate the number's initial byte (typically
   if the implementation doesn't even implement the indicated argument
   size) or the argument (if it implements it).

   When the request's content format indicated a non-identity content
   coding, the offset points into the uncompressed body.  Consequently,
   this error detail is not suitable for pointing out errors that occur
   during uncompressing.

   The main envisioned use of this option is for the client to highlight
   or back-annotate (eg. to counteract minification, or to display it on
   some diagnostic notation) the erroneous item in the request body for
   a human author.

3.  Usage example

   The figures in this section illustrate a CoAP [RFC7252] message
   exchange using CBOR [STD94] bodies, and a hypothetical CoAP tool's
   output that utilizes this error detail.

   Req: FETCH coap://example.com/alpha/archive
   Content-Format: 60 (application/cbor)
   Payload:
     A2071A000123A0182C192118
   Payload (diagnostic notation):
     {7: 74656, 44: 8472}

   Res: 4.00 Bad Request
   Content-Format: 257 (application/concise-problem-details+cbor)
   Payload:
     A22071556E6B6E6F776E207175657279206B6579381808
   Payload (diagnostic notation):
     {
       / title /                        -1: "Unknown query key",
       / request-body-error-position / -25: 8
     }

Amsüss                    Expires 8 August 2023                 [Page 3]
Internet-Draft  Concise Problem Details: Body Error Posi   February 2023

           Figure 1: Messages exchanged between client and server

$ coap post coap://example.com/alpha/archive cbor '{7: 74656, 44: 8472}'
Error: Bad Request: Unknown query key
{7: 74656, 44: 8472}
           ^^ The server indicated that the error occurred here.

   Figure 2: Output of a hypothetical CoAP client that utilizes the
                  Request Body Error Position detail

4.  IANA considerations

   A new entry is requested for the "Standard Problem Detail Keys"
   subregistry of the "Constrained RESTful Environments (CoRE)
   Parameters" registry.

   Key value:  The value -25 is suggested

   Name:  request-body-error-position

   CDDL type:  uint

   Brief description:  Byte index inside the request body at which the
      error became apparent

   Reference:  This document

   Change controller:  IETF CoRE working group

5.  References

5.1.  Normative References

   [RFC9290]  Fossati, T. and C. Bormann, "Concise Problem Details for
              Constrained Application Protocol (CoAP) APIs", RFC 9290,
              DOI 10.17487/RFC9290, October 2022,
              <https://www.rfc-editor.org/rfc/rfc9290>.

   [RFC7959]  Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in
              the Constrained Application Protocol (CoAP)", RFC 7959,
              DOI 10.17487/RFC7959, August 2016,
              <https://www.rfc-editor.org/rfc/rfc7959>.

5.2.  Informative References

   [STD94]    Bormann, C. and P. Hoffman, "Concise Binary Object
              Representation (CBOR)", STD 94, RFC 8949, December 2020.

Amsüss                    Expires 8 August 2023                 [Page 4]
Internet-Draft  Concise Problem Details: Body Error Posi   February 2023

              <https://www.rfc-editor.org/info/std94>

   [RFC7252]  Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
              Application Protocol (CoAP)", RFC 7252,
              DOI 10.17487/RFC7252, June 2014,
              <https://www.rfc-editor.org/rfc/rfc7252>.

Author's Address

   Christian Amsüss
   Austria
   Email: christian@amsuess.com

Amsüss                    Expires 8 August 2023                 [Page 5]