Repository navigation
feat(client-contract): add the SDK 0.2 rules and codes, adopt party_totals, and re-record at apis 133262c5e - #52
Merged
Conversation
…file schema Adds the timeout-and-retries rule for DFO_TIMEOUT and DFO_MAX_RETRIES, with a strict ASCII grammar and precedence call > client > variable > default. The cache-dir rule roots the platform default at `dfo` and reads the legacy readerkit directory, artifacts and manifests, when no explicit root is set, copying a verified hit in. cache-layout gains the `fetched/sha256/<hex>` entry. client-codes.json gains the FormatError and BundleError reasons and ref_unavailable, proxy_invalid and match_unresolved; invalid_argument covers settings variables. Scenarios gain a party_totals_left_out dataset outcome, read leniently as Strict fields reads. A new saved-file.schema.json describes the Parquet dfo.* keys, with accept and reject examples the validator checks. `party_totals: false` is the request spelling of the party totals cut. Refs accept it beside `without_party_totals: true` in the same format version, a disagreeing pair or a keep value is invalid, and the recorder posts `party_totals: false`. The README names `licence*` as the preferred spelling on served citation and graph source shapes.
… apis 133262c5e served/openapi.json is captured from DevelopmentFinanceObservatory/apis 133262c5e, which accepts party_totals on requests and serves licence beside license. Every scenario is re-recorded against dev at that commit, so builds post party_totals: false. The two-place question names Congo in both parts, since dev now reads "Kenya's GDP" as definite, and the long-build picks move to 1970 and 1971.
…mpossible saved-file dates derived_identities compared raw root renderings, so a root spelling the cut party_totals: false conflicted with the same root spelled without_party_totals: true. It now folds each through served_rendering. The saved-file check refuses a dfo.fetched_at or held_until date that does not exist, such as 2026-02-30, as format_invalid, as both SDK loaders do, with a reject example for each.
… totals per series rules/role-keys.json gains `columns`, the frame party columns that name each caller key (dfo-apis `ROLE_AXES`), so a client can show `origin` beside a party-totals entry's `financingProvider`. Party-totals entries carry an optional `kept_in`: each series once, with the sorted time periods in which the listed totals stayed. Readers take the server's order and drop an entry that breaks it or holds an empty string. A derived member's saved entries name its roots, in the order of the member's roots, and its own id is refused. New saved-file examples cover kept series, root entries and each refusal.
…t apis aacbe6a4 The served document gains `kept_in` and the derived manifest root's `party_totals_left_out`. The long-build scenarios start one year later, as each re-record does.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The client contract gains the rules, client codes and saved-file schema that SDK 0.2.0 implements, adopts
party_totals: falseas the request spelling of the party totals cut, and is re-recorded against dev running DevelopmentFinanceObservatory/apis aacbe6a4, which accepts that spelling, serveslicencebesidelicense, and reports party totals kept per series and per derived root.Part of DevelopmentFinanceObservatory/sdk#19
Changes
rules/timeout-and-retries.json(new):DFO_TIMEOUTandDFO_MAX_RETRIES, 42 vectors, precedence call > client argument > variable > default, an ASCII grammar, andwith_optionstaking no variable. Listed inRULES,rules.schema.jsonand both READMEs.rules/cache-dir.json: the platform default root isdfo, withv1/dfo/cache1below it. With no explicit root a client reads the legacyreaderkitdirectory, artifacts by digest and manifests under the cached-manifest checks, and copies a hit in.BBLOCKS_CACHE_DIRstays the lowest explicit root.rules/cache-layout.json: thefetched/sha256/<hex>entry, holding the fetch time as UTC seconds, removed and counted with its artifact.client-codes.json: the FormatError and BundleError reasons as codes (carried ascode, withreasonequal),ref_unavailable,proxy_invalidandmatch_unresolved, andinvalid_argumentcovering settings variables. Both classes join the scenario class enum.scenario.schema.json,tools/validate_client_contract.py,tools/capture_client_contract.py: aparty_totals_left_outdataset outcome, derived by both tools, read leniently as "Strict fields" reads.saved-file.schema.jsonandsaved-files/(new): the Parquetdfo.*keys, four accepted and nine rejected examples, checked by the validator, including the format version against the ref and party-totals members against the ref.dataset-ref.schema.json,refs/,rules/file-selector.json,rules/output-comparison.json, the validator and the recorder:party_totals: falseandwithout_party_totals: trueboth mark a cut in the same format version; a disagreeing pair or a keep value is invalid; builds postparty_totals: false.rules/role-keys.json:columns, the frame party columns that name each caller key (financingProviderand the other origin columns toorigin, the recipient columns todestination), equal to dfo-apisROLE_AXES, with vectors.scenario.schema.json,saved-file.schema.json, the README and the validator carry an optionalkept_in: each series once, with the sorted time periods in which the listed totals stayed, in the server's order. Readers drop an entry that breaks the order or holds an empty string. A derived member's saved entries name its roots in the member's root order, and its own id is refused. Five new saved-file examples cover kept series, root entries and each refusal.served/openapi.jsonand every scenario: recaptured and re-recorded at apis aacbe6a4. The served document gainskept_inand the derived manifest root'sparty_totals_left_out; the long-build scenarios start one year later.Notes for reviewers
without_party_totalsin renderings, and clients keep writing it in refs, until 0.1.x clients are retired, because SDK 0.1.0 rejects an unknown member there. The README states this transition.TWO_PLACESnames Congo in both parts to keep twoentity_ambiguousparts. That is a change in dev's search, independent of this PR.kept_inor a derived member's entries, so saved-file examples and validator tests pin those rules. Dev serveskept_infor "OOF to India by donor" (1968,DACOfficialDonors), which is not a recorded scenario.columnsagainstROLE_AXES.Testing: in
python/client-contract,ruff check,ruff format --checkandpytest(307 passed); at the root,tools/validate_client_contract.py(valid, 126 scenarios) andpytest tools/tests(719 passed); the repo's pre-commit hooks. A differential check of 2,407kept_inlists found the dfo-apis writer, this validator and both SDK readers in agreement on every accept and reject. SDK 0.1.0 and 0.2.0 live journeys against dev at 133262c5e: 8 passed and 2 skipped each.