Skip to content
Sarj Repo Standards
rest/errors/problem-contract

RFC 9457 error contract

Opted-in error responses remain compatible with Problem Details.

warning beta

Examples

FlaggedFails
{
  "documents": {
    "openapi.json": {
      "info": {
        "title": "Fixture",
        "version": "1"
      },
      "openapi": "3.1.2",
      "paths": {
        "/widgets": {
          "get": {
            "responses": {
              "422": {
                "content": {
                  "application/json": {
                    "schema": {
                      "type": "object"
                    }
                  }
                },
                "description": "wrong media"
              }
            }
          }
        }
      }
    }
  },
  "entrypoint": "openapi.json",
  "semantics": {
    "artifacts": [],
    "operations": [
      {
        "error_profile": "rfc9457",
        "operation_ref": "#/paths/~1widgets/get"
      }
    ],
    "schema_version": 1
  }
}
PassesClean
{
  "documents": {
    "openapi.json": {
      "info": {
        "title": "Fixture",
        "version": "1"
      },
      "openapi": "3.1.2",
      "paths": {
        "/widgets": {
          "get": {
            "responses": {
              "422": {
                "content": {
                  "application/problem+json": {
                    "schema": {
                      "type": "object"
                    }
                  }
                },
                "description": "problem"
              }
            }
          }
        }
      }
    }
  },
  "entrypoint": "openapi.json",
  "semantics": {
    "artifacts": [],
    "operations": [
      {
        "error_profile": "rfc9457",
        "operation_ref": "#/paths/~1widgets/get"
      }
    ],
    "schema_version": 1
  }
}
FlaggedFails
{
  "documents": {
    "openapi.json": {
      "info": {
        "title": "Fixture",
        "version": "1"
      },
      "openapi": "3.1.2",
      "paths": {
        "/widgets": {
          "get": {
            "responses": {
              "422": {
                "content": {
                  "application/problem+json": {
                    "schema": {
                      "properties": {
                        "status": {
                          "type": "string"
                        }
                      },
                      "type": "object"
                    }
                  }
                },
                "description": "wrong status"
              }
            }
          }
        }
      }
    }
  },
  "entrypoint": "openapi.json",
  "semantics": {
    "artifacts": [],
    "operations": [
      {
        "error_profile": "rfc9457",
        "operation_ref": "#/paths/~1widgets/get"
      }
    ],
    "schema_version": 1
  }
}
PassesClean
{
  "documents": {
    "openapi.json": {
      "info": {
        "title": "Fixture",
        "version": "1"
      },
      "openapi": "3.1.2",
      "paths": {
        "/widgets": {
          "get": {
            "responses": {
              "422": {
                "content": {
                  "application/problem+json": {
                    "schema": {
                      "properties": {
                        "status": {
                          "const": 422,
                          "type": "integer"
                        }
                      },
                      "type": "object"
                    }
                  }
                },
                "description": "problem"
              }
            }
          }
        }
      }
    }
  },
  "entrypoint": "openapi.json",
  "semantics": {
    "artifacts": [],
    "operations": [
      {
        "error_profile": "rfc9457",
        "operation_ref": "#/paths/~1widgets/get"
      }
    ],
    "schema_version": 1
  }
}

Why it matters

Consumers cannot handle opted-in errors through one predictable Problem Details contract.

How detection works

An operation opted into RFC 9457 documents an error body with the wrong media type, an unresolved schema, an incompatible member type, or a status constant that contradicts the response.

What is inspected

  • an explicit RFC 9457 sidecar opt-in and parsed 4xx, 5xx, 4XX, or 5XX response content

Limits

  • requiring optional Problem Details members
  • replacing domain-specific errors
  • Only explicitly opted-in operations and documented error bodies are checked.
  • Bodyless errors remain valid, and optional Problem Details members are not required.
  • Only directly resolved local schemas and declared member contradictions are checked.

How to fix it

Align the opted-in error representation.

  1. Use application/problem+json with an inline or supplied local object schema.
  2. Correct declared member types and any status constant, or remove the explicit opt-in.

Verify

  • Run repo-lint rest check again against the same tracked contract and semantics.