Skip to content

HistoryLength is seconds: fix the Authorization Server defaults and the REQ.21.6.3 example #284

Open

Description

@dfcoffin

Decision

HistoryLength in an ESPI scope (FB=...;HistoryLength=n) is a number of seconds: the most history the Data Custodian returns, counted back from now. It is a ceiling, not a selection; the published-min/max query parameters choose the data, with a 24-hour default (#279).

REQ.21 v4.1 defines it in seconds in two places:

  • REQ.21.6.1.2.1 (p. 164): "The amount of historical information available from the Data Custodian in seconds. For example, a years worth of data is represented by a value of "31536000" (365 days * 24 hours * 60 mins * 60 secs)".
  • REQ.21.4.2.1.3.3 ScopeValueTerms (p. 65): the same definition.

Certified practice matches. In the GBA CMD certification test logs, every ApplicationInformation scope that carries HistoryLength (46 distinct scope strings) uses seconds: 31557600 (1 year of 365.25 days), 63072000, 63115200, 31536000 and 34128000. None uses a month count.

What is wrong

  • Authorization Server default scopes use month and day counts, which a REQ.21 Data Custodian reads as 13 or 7 seconds, so a token gets almost no history:
    • HistoryLength=13 with BlockDuration=monthly: AuthorizationServerConfig (lines 265-266), OAuth2ClientManagementController (lines 102-103, 306), and the AS Flyway seed data (V1_0_0__create_oauth2_schema.sql, V3_0_0__add_default_data_and_test_clients.sql).
    • HistoryLength=7 with BlockDuration=daily: OAuth2ClientManagementController (lines 104-105) and the V3 seed data.
  • REQ.21 example: REQ.21.6.3 (pp. 180-181) shows scope=FB=1_3_4_5_10_11_12_13_14_37_39;IntervalDuration=3600;BlockDuration=daily;HistoryLength=13 in the authorization request and token response. That contradicts the definition; the other REQ.21 examples use seconds (34128000 on p. 59, 94608000 on pp. 61-62). This is the likely source of the 13 in the AS defaults.
  • Other REQ.21 example defects seen while checking: p. 59's BlockDuration=Daily; HistoryLength=... has a space after ;, which splits it into two OAuth scope tokens (OAuth 2.1 draft-17 §1.4.1); pp. 61-62 list ..._15_1937_39 (missing _).

The Data Custodian already reads seconds (ScopeResolver.historyLengthSeconds, SubscriptionFeedAssembler, PR #282). Only scopes that grant a usage-data FB count, and the shortest applies.

To do

  • Convert the AS default scopes and seed data to seconds: HistoryLength=13 (monthly) to e.g. 34128000 (395 days) or 31536000, and HistoryLength=7 (daily) to 604800, or whatever the intended history is.
  • State the unit (seconds) in the AS scope documentation and in EspiScope's Javadoc and examples, which still show HistoryLength=13.
  • Decide whether the AS should reject a HistoryLength that is implausibly small (e.g. below one day), to catch month or day counts.
  • Prepare a NAESB minor correction request for the REQ.21.6.3 example (HistoryLength=13), and consider the p. 59 space and the pp. 61-62 FB list in the same request; track it per the errata process.

Related: #279, #282.

Activity

  1. added a commit that references this issue on Nov 19, 2026
  2. changed the title [-]HistoryLength is months: align the Authorization Server, Data Custodian and the REQ.21 text[/-] [+]HistoryLength is seconds: fix the Authorization Server defaults and the REQ.21.6.3 example[/+] on Nov 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions