Hi Richard, all,
I think for consistency, it would make sense to rename E_JSON_VALUE_TYPE
to E_INVALID_FIELD_TYPE
Furthermore, we should make clear that the text below the table
is a non-normative illustration how these error codes might be used,
but not a mandatory-to-implement-like-this way of doing sanity checks.
My proposal is:
> 8.5.1. Media Type
>
> The media type for an ALTO Error Response is "application/
> alto-error+json".
>
> 8.5.2. Response Format and Error Codes
>
> An ALTO Error Response MUST include the "code" key in the "meta"
> field of the response. The value of "code" MUST be an ALTO Error
> Code defined in Table 1. Note that the ALTO Error Codes defined in
> Table 1 are limited to support the error conditions needed for
> purposes of this document. Additional status codes may be defined in
> companion or extension documents.
>
> +-----------------------+-------------------------------------------+
> | ALTO Error Code | Description |
> +-----------------------+-------------------------------------------+
> | E_SYNTAX | Parsing error in request (including |
> | | identifiers) |
| E_MISSING_FIELD | Required JSON field missing |
| E_INVALID_FIELD_TYPE | The type of a JSON field is invalid |
> | E_INVALID_FIELD_VALUE | The value of a JSON field is invalid |
> +-----------------------+-------------------------------------------+
>
> Table 1: Defined ALTO Error Codes.
After an ALTO Server receives a query message, it needs to verify the
syntactic and semantic validity. The following paragraphs in this
section are intended to illustrate the usage of the error codes
defined above. Note that the order of the checks is implementation
specific.
In the first step after an ALTO Server receives a query, it checks
the syntax of the query, i.e., whether the JSON structure can be
parsed, and indicates a syntax error using the error code E_SYNTAX.
> A query without syntax error may still be invalid. An error case is
> that the query misses a required field. The server indicates such an
> error using error code E_MISSING_FIELD. This document defines
> required fields for Network Map Filtering (Section 11.3.1.3), Cost
> Map Filtering (Section 11.3.2.3), Endpoint Properties
> (Section 11.4.1.3), and Endpoint Cost (Section 11.5.1.3). For an
> E_MISSING_FIELD error, the server may include the optional "field"
> key in the "meta" field of the response, to indicate the missing
> field.
A query with correct query fields might use a wrong type for a field.
For example, a request could use a JSONString when a JSONNumber is
expected. The server indicates such an error using error code
E_INVALID_FIELD_TYPE. The server may include the optional "field"
key in the "meta" field of the response, to indicate the field that
contains the wrong type.
> A query with correct query fields may specify a wrong value for a
> field. For example, a cost map filtering query may specify a wrong
> value of CostMode in the "cost-type" field (Section 11.3.2.3). The
> server indicates such an error with error code E_INVALID_FIELD_VALUE.
> For an E_INVALID_FIELD_VALUE error, the server may include the
> optional "field" key in the "meta" field of the response, to indicate
> the field that contains the wrong value. The server may also include
> the optional "value" key in the "meta" field of the response to
> indicate the wrong value that triggered the error.
>
> If multiple errors are present in a single request (e.g., a request
> uses a JSONString when a JSONNumber is expected and a required field
> is missing), then the ALTO Server MUST return exactly one of the
> detected errors. However, the reported error is implementation
> defined, since specifying a particular order for message processing
> encroaches needlessly on implementation techniques.
Thanks
Sebastian
_______________________________________________
alto mailing list
[email protected]
https://www.ietf.org/mailman/listinfo/alto
