Skip to content
Sarj Repo Standards
rest/lifecycle/sunset-order

Sunset after deprecation

Explicit lifecycle timestamps provide a positive migration window.

error

Examples

FlaggedFails
{
  "documents": {
    "openapi.json": {
      "info": {
        "title": "Fixture",
        "version": "1"
      },
      "openapi": "3.1.2",
      "paths": {
        "/widgets": {
          "get": {
            "responses": {
              "200": {
                "description": "ok"
              }
            }
          }
        }
      }
    }
  },
  "entrypoint": "openapi.json",
  "semantics": {
    "artifacts": [],
    "operations": [
      {
        "deprecation_at": "2027-01-01T00:00:00Z",
        "operation_ref": "#/paths/~1widgets/get",
        "sunset_at": "2026-12-01T00:00:00Z"
      }
    ],
    "schema_version": 1
  }
}
PassesClean
{
  "documents": {
    "openapi.json": {
      "info": {
        "title": "Fixture",
        "version": "1"
      },
      "openapi": "3.1.2",
      "paths": {
        "/widgets": {
          "get": {
            "responses": {
              "200": {
                "description": "ok"
              }
            }
          }
        }
      }
    }
  },
  "entrypoint": "openapi.json",
  "semantics": {
    "artifacts": [],
    "operations": [
      {
        "deprecation_at": "2026-01-01T00:00:00Z",
        "operation_ref": "#/paths/~1widgets/get",
        "sunset_at": "2026-12-01T00:00:00Z"
      }
    ],
    "schema_version": 1
  }
}

Why it matters

Consumers receive no valid migration window.

How detection works

An operation's explicit sunset timestamp is equal to or earlier than its deprecation timestamp.

What is inspected

  • two explicit strict-RFC3339 sidecar timestamps for one operation

Limits

  • inferring dates from prose or examples
  • No finding is emitted unless both exact timestamps are declared.
  • Malformed sidecar timestamps make analysis inconclusive instead of being guessed.
  • Equal timestamps are treated as having no migration window.

How to fix it

Provide a positive migration window.

  1. Move sunset_at after deprecation_at.

Verify

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