Concise Problem Details: 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.¶

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

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.¶

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
  }

$ 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.

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¶

Author's Address