problem-details-core/io.github.ilyankin.rfc9457/Problem

Problem

@Serializable(with = ProblemSerializer::class)

class Problem(val type: String = ABOUT_BLANK, val status: Int? = null, val title: String? = null, val detail: String? = null, val instance: String? = null, extensions: Map<String, ProblemValue> = emptyMap())(source)

An RFC 9457 problem detail. This is the document carried by application/problem+json and application/problem+xml.

The five members §3.1 defines are named properties here. Anything else becomes a §3.2 extension member. It lives in Problem.extensions, and both codecs place it as a sibling of the standard members, not inside an extensions key.

Extension names are checked against RESERVED_MEMBERS alone, since reusing one of those five would produce a document with a duplicate key. §3.2 also suggests starting with a letter, using only [A-Za-z0-9_], and staying at least three characters long. That guidance is a SHOULD a valid document can ignore, so it stays documented here instead of enforced.

Constructors

Problem

constructor(type: String = ABOUT_BLANK, status: Int? = null, title: String? = null, detail: String? = null, instance: String? = null, extensions: Map<String, ProblemValue> = emptyMap())

Types

Companion

object Companion

Holds what RFC 9457 fixes on the wire, the nesting limit both codecs share, and the about:blank factory.

Properties

detail

val detail: String?

a human-readable explanation of this occurrence. It exists to help the client correct the problem, not to carry debugging information, and §3.1 asks consumers to leave it unparsed. Machine-readable data belongs in an extension member.

extensions

val extensions: Map<String, ProblemValue>

A snapshot of the extension members supplied to the constructor.

instance

val instance: String?

URI reference identifying this specific occurrence. It need not be dereferenceable. Treat it as an opaque server-assigned identifier when it isn't.

status

val status: Int?

the HTTP status code the origin server generated. §3.1 treats this as advisory only. Generators must make it agree with the real response status, but §5 still allows the two to diverge once an intermediary rewrites a response without touching its body, so consumers should key off the real status. §3.1 fixes what this member means without saying which values are legal, so this stays unchecked too.

title

val title: String?

a short human-readable summary of the type. §3.1 asks it to stay constant across occurrences, localization aside.

type

val type: String

URI reference identifying the problem type. §3.1 treats this as the primary identifier of what went wrong, ahead of Problem.title. An absent type means ABOUT_BLANK, which is why this has a default value instead of being nullable. Use an absolute URI where you can. A relative one resolves against the document's base URI, so its meaning shifts depending on where the document was fetched.

Functions

component1

operator fun component1(): String

The type component for destructuring.

component2

operator fun component2(): Int?

The status component for destructuring.

component3

operator fun component3(): String?

The title component for destructuring.

component4

operator fun component4(): String?

The detail component for destructuring.

component5

operator fun component5(): String?

The instance component for destructuring.

component6

operator fun component6(): Map<String, ProblemValue>

The extensions component for destructuring.

copy

fun copy(type: String = this.type, status: Int? = this.status, title: String? = this.title, detail: String? = this.detail, instance: String? = this.instance, extensions: Map<String, ProblemValue> = this.extensions): Problem

Returns a problem with the supplied members replaced, preserving data-class-style ergonomics.

equals

open operator override fun equals(other: Any?): Boolean

Two problems are equal when all five standard members and all extension members match.

extension

inline fun <T> Problem.extension(name: String, json: Json = ProblemJson): T?

Decodes a single extension member with the deserializer resolved from T, or returns null when the member is absent.

fun <T> Problem.extension(name: String, deserializer: DeserializationStrategy<T>, json: Json = ProblemJson): T?

Decodes a single extension member, or returns null when it is absent.

extensionsAs

inline fun <T> Problem.extensionsAs(json: Json = ProblemJson): T

Decodes the whole extension map into T, with the deserializer resolved from T. Members T does not declare are ignored, as RFC 9457 §3.2 requires.

fun <T> Problem.extensionsAs(deserializer: DeserializationStrategy<T>, json: Json = ProblemJson): T

Decodes the whole extension map into T. This is the typed consuming edge.

hashCode

open override fun hashCode(): Int

Derived from the same members as equals.

toString

open override fun toString(): String

Lists the five standard members and extensions, matching the former data-class format.

Problem

See also

Constructors

Types

Properties

Functions