Skip to content

Input validation issue types

Jump to bottom
Peter Van den Bosch edited this page Sep 17, 2024 · 5 revisions

Scope

Standardize common additional types of input validation issues.

As-is

When an input message is incorrect, a problem response of type badRequest has to be returned.

In this response, a list of input validation issues can be listed of which these are currently standardized:

type description

urn:problem-type:belgif:input-validation:schemaViolation

violation of the OpenAPI schema

urn:problem-type:belgif:input-validation:unknownInput

Request contains an unknown (unexpected/undefined) input field (like [req-valid])

Proposed new issue types

The prefix urn:problem-type:belgif:input-validation is omitted in the proposed issue types listed below.

type description rationale

invalidStructure

input with invalid structure e.g. checksum invalid for SSIN or enterprise number, YearMonth value with month higher than 12

invalidPeriod

period with end date before begin date

bc two inputs (start+end) that may be split in query parameters

outOfRange

value out of range e.g. timestamp that should be in future or past

referencedResourceNotFound

when request references another resource by its identifier, that doesn’t exist e.g. unknown SSIN

not for identifiers that are in path params; 404 with resourceNotFound should be used in that case

replacedSsin, canceledSsin

given SSIN was replaced/canceled

rejectedInput,requiredInput

permissive schemas that are reused in multiple operations, but should be more restricted according to the specific operation

Cross-parameter validation: based on issue #113

type description

exactlyOneOfExpected

Exactly one of these inputs must be present

anyOfExpected

Any of these inputs must be present

zeroOrExactlyOneOfExpected

Exactly one or none of these inputs must be present

zeroOrAllOfExpected

All or none of these inputs must be present

equalExpected

These inputs must be equal

Other: payload is not valid to content-type (e.g. no valid JSON payload for content-type application/json)

Considerations

Issue types specific to a business concept

replacedSsin and canceledSsin are specific to a single business concept (Ssin, defined in belgif-person-identifier). Whether to check input on replaced or canceled SSIN, depends on business context of the API. It may make sense to allow replaced or canceled SSINs.

Other similar scenarios:

  • a stopped enterprise

  • an enterprise merged with another

  • a deceased person

Should the REST guide remain agnostic of specific (Belgian government) definitions? Or should they be documented somewhere alongside fedvoc artifacts or next to the business-specific openapi schemas; but less easy to find them there?

For the issue type, should we add the related domain (and subdomain as defined in the corresponding reusable OpenAPI e.g.:

  • urn:problem-type:belgif:input-validation:person:canceledSsin or, including subdomain urn:problem-type:belgif:input-validation:person-identifier:canceledSsin

  • urn:problem-type:belgif:input-validation:person:deceased (in this case, person-identifier can’t be used bc deceased applies to the person)

  • urn:problem-type:belgif:input-validation:organization:merged

  • urn:problem-type:belgif:input-validation:organization:stopped

  • urn:problem-type:belgif:input-validation:time:invalidPeriod

Level of detail in issue types

Arguments for low level of detail:

  • verbose rules to read and interpret + work on standardization itself

  • more difficult to enforce rules on APIs to comply

  • validation rules are easier to change in a backwards-compatible way without impact on issue type

Arguments for high level of detail:

  • Reusable belgif library can provide structured validation (but only available for certain technologies)

  • Client would be able to perform logic based on specific issue type

    • But clients are supposed to perform a certain degree of input validation, to be able to provide a readable feedback message to the end-user’s input, rather than based on the API Problem response. The API problem response’s content explains the problem based on the JSON request format, rather than a web form’s input (or client application’s generated input). A free text message with a generic issue type would be sufficient for troubleshooting in case the client application’s input validation misses a violation.

      • this argument doesn’t apply to referencedResourceNotFound, replacedSsin or canceledSsin as these validations can’t easily be done client-side

Issue type depending on implementation details

  • Newer OpenAPI versions allow more expressive validation constraints. Should the problem response (issue type) depend on what’s possible in the OpenAPI schema to validate?

    • Cross-parameter validation can be expressed in single schemas (e.g. different input in a single JSON payload) but not across query parameters

  • rejectedInput and requiredInput heavily depend on OpenAPI design; whether to use dedicated schemas for different operations (PATCH vs POST/PUT vs GET)

  • if the pattern for YearMonth would be more precise, the issue type would change from invalidStructure to schemaViolation

Clone this wiki locally