govstack-cfr-architecture#req-6 (REQUIRED) and #req-7 (RECOMMENDED) both make conformance
depend on the TM Forum REST API Design Guidelines, linked as:
https://www.tmforum.org/resources/specification/tmf630-rest-api-design-guidelines-4-2-0/
The landing page is publicly reachable, but the specification document itself cannot be
downloaded from it without a TM Forum account. A REQUIRED requirement in an ecosystem intended
for open adoption by government teams and vendors of any size should not have a normative
reference that cannot be read without registering with a trade association.
The two requirements are affected differently and need different fixes.
#req-6 (REQUIRED EXTENSIBLE AUDITABLE): the link is already redundant
#req-6's own body already states the principles it requires:
no PII or session keys in URLs (use POST or request bodies for sensitive data), support for
caching and retries, resource identification via URIs, separation between server-internal
representation and client-facing representation, self-descriptive messages that include
enough information for the receiver to know how to process them
and the block below it restates them at greater length. The normative content is therefore
already local, and TMF630 is doing no work the requirement text does not already do.
Proposed: mark the TMF630 link informative (Further reading: rather than See:), leaving
the requirement's normative content exactly as it is today. No behavioural change, no
reclassification.
Separate, smaller point: "support for caching and retries" is not testable as written, which
sits awkwardly inside a REQUIRED requirement. Either state what is required (for example,
GET responses carry validators, and unsafe operations are safe to retry) or move that clause
to #req-7.
#req-7 (RECOMMENDED REPLACEABLE AUDITABLE): unimplementable as written
#req-7 requires that "APIs follow the extended TM Forum REST API Design Guidelines (parts 2
through 7)" and, unlike #req-6, inlines none of that content. Its entire normative substance
lives in a document a reader cannot obtain. An implementer acting in good faith has no way to
determine what compliance means, and an auditor has no way to assess it.
Proposed: replace the reference with a specific, retrievable one, or state the handful of
conventions actually intended (parts 2-7 mainly cover error handling, filtering, sorting,
pagination and notification patterns) directly in the requirement body, as #req-6 does. If
neither is practical in the short term, reclassifying #req-7 to DRAFT would be more honest
than leaving a RECOMMENDED requirement whose content is unavailable.
Longer term
A GovStack-owned cross-Building-Block API specification is currently in draft. If and when it is
ratified, it would be the natural replacement for both references, and would let these two
requirements point at a document the ecosystem controls and can freely distribute. Flagging that
as context rather than proposing it here: it is not a ratified artifact yet, and these two fixes
stand on their own regardless of what happens to it.
govstack-cfr-architecture#req-6(REQUIRED) and#req-7(RECOMMENDED) both make conformancedepend on the TM Forum REST API Design Guidelines, linked as:
The landing page is publicly reachable, but the specification document itself cannot be
downloaded from it without a TM Forum account. A REQUIRED requirement in an ecosystem intended
for open adoption by government teams and vendors of any size should not have a normative
reference that cannot be read without registering with a trade association.
The two requirements are affected differently and need different fixes.
#req-6(REQUIRED EXTENSIBLE AUDITABLE): the link is already redundant#req-6's own body already states the principles it requires:and the block below it restates them at greater length. The normative content is therefore
already local, and TMF630 is doing no work the requirement text does not already do.
Proposed: mark the TMF630 link informative (
Further reading:rather thanSee:), leavingthe requirement's normative content exactly as it is today. No behavioural change, no
reclassification.
Separate, smaller point: "support for caching and retries" is not testable as written, which
sits awkwardly inside a REQUIRED requirement. Either state what is required (for example,
GETresponses carry validators, and unsafe operations are safe to retry) or move that clauseto
#req-7.#req-7(RECOMMENDED REPLACEABLE AUDITABLE): unimplementable as written#req-7requires that "APIs follow the extended TM Forum REST API Design Guidelines (parts 2through 7)" and, unlike
#req-6, inlines none of that content. Its entire normative substancelives in a document a reader cannot obtain. An implementer acting in good faith has no way to
determine what compliance means, and an auditor has no way to assess it.
Proposed: replace the reference with a specific, retrievable one, or state the handful of
conventions actually intended (parts 2-7 mainly cover error handling, filtering, sorting,
pagination and notification patterns) directly in the requirement body, as
#req-6does. Ifneither is practical in the short term, reclassifying
#req-7to DRAFT would be more honestthan leaving a RECOMMENDED requirement whose content is unavailable.
Longer term
A GovStack-owned cross-Building-Block API specification is currently in draft. If and when it is
ratified, it would be the natural replacement for both references, and would let these two
requirements point at a document the ecosystem controls and can freely distribute. Flagging that
as context rather than proposing it here: it is not a ratified artifact yet, and these two fixes
stand on their own regardless of what happens to it.