diff --git a/python/client-contract/CHANGELOG.md b/python/client-contract/CHANGELOG.md index 37e7d4c..87cfe85 100644 --- a/python/client-contract/CHANGELOG.md +++ b/python/client-contract/CHANGELOG.md @@ -16,6 +16,7 @@ All notable changes to the `dfo-spec-kit-client-contract` Python package will be - `proxy-codes.json` and its schema, the website proxy's `rate_limited` and `transient_unavailable` codes with their statuses, and `warning-codes.json` and its schema, the 5 codes a client sets on the warnings it issues itself, with the `proxy_codes()` and `warning_codes()` accessors. - Error outcomes give the error's `trace_id`, the body's, else the `x-dfo-trace-id` header's, else null. Scenario outcomes give `retry_waits`, the waits before each retry, and `warnings`, the warning codes a step's responses issued. Scenario steps take no `timeout`. - `dataset-ref.schema.json`, the frozen `DatasetRef` format, with accepted and rejected examples. +- `without_party_totals` in the ref's artifact rendering, `true` for the version rendered with party totals left out and absent for a plain rendering, with `ref-without-party-totals` and `ref-without-party-totals-false-rejected` as its examples. - `tools/capture_client_contract.py`, which captures `served/openapi.json` from a dfo-apis checkout in process and records the scenarios against a base URL, dev by default, or with `record --offline` derives their outcomes again from the records with no request. A local app's signed URLs are written as the storage URLs a deployment signs. - `tools/validate_client_contract.py`, which checks the contract against its schemas, the served document and `registries/codes.json`, checks `client-codes.json` against them and against the reasons the key-lookup rule raises, and checks each scenario's `expect` against the outcomes its exchanges, `actions.json` and `client-codes.json` give, each Search request against the input its steps derive, a sentence lookup's `entity_groups` included, each build's `input.scope` against the narrowing its step names over the spec's bound roles, each build's options against its layout, each Search request's whole body, each download against its artifact's digest, each recorded scenario's commit against `served/SOURCE.json`, each proxy refusal's code against `proxy-codes.json`, and each absolute URL against the storage host, each ref example's members against the dataset members and downloaded files of the scenario it names, and the scenarios directory against a 16,000,000-byte budget for records and bodies together. A record that ends a run of retries while a retry remains does not fit. The outcomes include each long build's operation id, poll waits and resubmissions, and a `VersionUnavailableError`'s newest version. - The client rules and their vectors: the credentials path and file format, the key lookup order, with an empty `api_key` refused as `key_empty` and an empty profile key as `profile_without_key`, the key format check, and the cache directory and layout. diff --git a/python/client-contract/README.md b/python/client-contract/README.md index 6ab5070..1a175ec 100644 --- a/python/client-contract/README.md +++ b/python/client-contract/README.md @@ -211,7 +211,7 @@ A record's `origin.base_url` is the base URL the run was given, a local app's in ## DatasetRef -`dataset-ref.schema.json` is the frozen format a client writes for `data.ref` and reads back in any language: `format_version: 1` and one or more `members`, each `{parts, sentence, spec: {spec_id, definition}, content_version, artifact: {digest, rendering}}`. `parts` holds the variable text of each answer part the member answers, in query order, and is empty for a spec fetched outside an answer. `definition` is the server's definition unmodified, so it holds the `schema_version`, `spec_id` and `identity` the served `CanonicalDefinition` requires and no other member, and a rebuild posts it as it is. The format takes any integer `schema_version` and leaves the version to the server, which checks it when a rebuild posts the definition. `rendering` is the selector a client matches an artifact on, `{format, bundle}` with `layout: "frame"` for the frame layout, never the server's rendering object. Beyond the schema, each member's `definition.spec_id` equals its `spec.spec_id`, and members hold distinct `spec_id`s. `ref-bare-definition-rejected`, `ref-definition-without-identity-rejected` and `ref-definition-without-schema-version-rejected` pin the definition's required members, and `ref-definition-extra-member-rejected` a member it does not admit. `refs/` holds accepted examples and rejected ones, each `{format_version, name, description, scenario, ref}` with `expect: "accept"` or `error`, `{by: "schema"}` or `{by: "rule", reason}`, the reason `definition_spec_id_mismatch` or `repeated_spec_id`. `scenario` names the recorded scenario that serves the ref's members, and is left out of a ref with no members. Each member's `spec_id`, `content_version` and `sentence` are those of a dataset member of that scenario, and its artifact digest is the digest of a file the scenario downloads, so a re-recording that changes a member also fails the refs that still name the old one. +`dataset-ref.schema.json` is the frozen format a client writes for `data.ref` and reads back in any language: `format_version: 1` and one or more `members`, each `{parts, sentence, spec: {spec_id, definition}, content_version, artifact: {digest, rendering}}`. `parts` holds the variable text of each answer part the member answers, in query order, and is empty for a spec fetched outside an answer. `definition` is the server's definition unmodified, so it holds the `schema_version`, `spec_id` and `identity` the served `CanonicalDefinition` requires and no other member, and a rebuild posts it as it is. The format takes any integer `schema_version` and leaves the version to the server, which checks it when a rebuild posts the definition. `rendering` is the selector a client matches an artifact on, `{format, bundle}` with `layout: "frame"` for the frame layout and `without_party_totals: true` for the version rendered with party totals left out, never the server's rendering object. The `without_party_totals` key is written only when true, so a plain rendering omits it and `false` is not a valid value. Beyond the schema, each member's `definition.spec_id` equals its `spec.spec_id`, and members hold distinct `spec_id`s. `ref-bare-definition-rejected`, `ref-definition-without-identity-rejected` and `ref-definition-without-schema-version-rejected` pin the definition's required members, and `ref-definition-extra-member-rejected` a member it does not admit. `ref-without-party-totals` is the accepted cut rendering and `ref-without-party-totals-false-rejected` pins `false`. `refs/` holds accepted examples and rejected ones, each `{format_version, name, description, scenario, ref}` with `expect: "accept"` or `error`, `{by: "schema"}` or `{by: "rule", reason}`, the reason `definition_spec_id_mismatch` or `repeated_spec_id`. `scenario` names the recorded scenario that serves the ref's members, and is left out of a ref with no members. Each member's `spec_id`, `content_version` and `sentence` are those of a dataset member of that scenario, and its artifact digest is the digest of a file the scenario downloads, so a re-recording that changes a member also fails the refs that still name the old one. ## Rules diff --git a/python/client-contract/src/dfo_client_contract/dataset-ref.schema.json b/python/client-contract/src/dfo_client_contract/dataset-ref.schema.json index 88cbedf..4e59f21 100644 --- a/python/client-contract/src/dfo_client_contract/dataset-ref.schema.json +++ b/python/client-contract/src/dfo_client_contract/dataset-ref.schema.json @@ -117,6 +117,10 @@ }, "layout": { "const": "frame" + }, + "without_party_totals": { + "description": "Selects the artifact rendered with party totals left out. The key is absent for a plain rendering, so `false` is not a valid value.", + "const": true } } } diff --git a/python/client-contract/src/dfo_client_contract/refs/ref-without-party-totals-false-rejected.json b/python/client-contract/src/dfo_client_contract/refs/ref-without-party-totals-false-rejected.json new file mode 100644 index 0000000..d59e933 --- /dev/null +++ b/python/client-contract/src/dfo_client_contract/refs/ref-without-party-totals-false-rejected.json @@ -0,0 +1,99 @@ +{ + "format_version": 1, + "name": "ref-without-party-totals-false-rejected", + "description": "The rendering names without_party_totals only when it is true, so false is not a ref.", + "scenario": "fetch-spec-known-sentence", + "ref": { + "format_version": 1, + "members": [ + { + "parts": [], + "sentence": "Germany's gross ODA disbursements to Nigeria for basic health care, 2020 to 2023. Current US dollars · OECD Creditor Reporting System (CRS).", + "spec": { + "spec_id": "spec_cb5baa4161de718f18583060674dbca6", + "definition": { + "schema_version": 1, + "spec_id": "spec_cb5baa4161de718f18583060674dbca6", + "identity": { + "identity_version": "spec1", + "shape": { + "kind": "statvar_schema", + "population_type": "FinancialFlow", + "measured_property": "amount", + "stat_type": "measuredValue", + "measurement_qualifier": "Nominal" + }, + "slots": [ + { + "property": "crsCooperationModality", + "binding": { + "state": "unbound" + } + }, + { + "property": "crsPurpose", + "binding": { + "state": "value", + "ref": "CRSPurposeCode12220" + } + }, + { + "property": "crsTypeOfFinance", + "binding": { + "state": "unbound" + } + }, + { + "property": "crsTypeOfFlow", + "binding": { + "state": "value", + "ref": "CRSTypeOfFlow10" + } + }, + { + "property": "financialFlowType", + "binding": { + "state": "value", + "ref": "Disbursement" + } + }, + { + "property": "nettingBasis", + "binding": { + "state": "value", + "ref": "Gross" + } + } + ], + "entities": { + "destination": [ + "country/NGA" + ], + "origin": [ + "country/DEU" + ] + }, + "requested_window": { + "kind": "range", + "start_year": 2020, + "end_year": 2023 + } + } + } + }, + "content_version": "cv_bf242138f8d0a892c97da9373d1626f4", + "artifact": { + "digest": "sha256:c44200969f19d73104d1bc24ebca905e59f749c2939234cdde10ba6f5a131170", + "rendering": { + "format": "parquet", + "bundle": false, + "without_party_totals": false + } + } + } + ] + }, + "error": { + "by": "schema" + } +} diff --git a/python/client-contract/src/dfo_client_contract/refs/ref-without-party-totals.json b/python/client-contract/src/dfo_client_contract/refs/ref-without-party-totals.json new file mode 100644 index 0000000..e458ea3 --- /dev/null +++ b/python/client-contract/src/dfo_client_contract/refs/ref-without-party-totals.json @@ -0,0 +1,97 @@ +{ + "format_version": 1, + "name": "ref-without-party-totals", + "description": "A ref to the version rendered with party totals left out, the member of fetch-spec-known-sentence.", + "scenario": "fetch-spec-known-sentence", + "ref": { + "format_version": 1, + "members": [ + { + "parts": [], + "sentence": "Germany's gross ODA disbursements to Nigeria for basic health care, 2020 to 2023. Current US dollars · OECD Creditor Reporting System (CRS).", + "spec": { + "spec_id": "spec_cb5baa4161de718f18583060674dbca6", + "definition": { + "schema_version": 1, + "spec_id": "spec_cb5baa4161de718f18583060674dbca6", + "identity": { + "identity_version": "spec1", + "shape": { + "kind": "statvar_schema", + "population_type": "FinancialFlow", + "measured_property": "amount", + "stat_type": "measuredValue", + "measurement_qualifier": "Nominal" + }, + "slots": [ + { + "property": "crsCooperationModality", + "binding": { + "state": "unbound" + } + }, + { + "property": "crsPurpose", + "binding": { + "state": "value", + "ref": "CRSPurposeCode12220" + } + }, + { + "property": "crsTypeOfFinance", + "binding": { + "state": "unbound" + } + }, + { + "property": "crsTypeOfFlow", + "binding": { + "state": "value", + "ref": "CRSTypeOfFlow10" + } + }, + { + "property": "financialFlowType", + "binding": { + "state": "value", + "ref": "Disbursement" + } + }, + { + "property": "nettingBasis", + "binding": { + "state": "value", + "ref": "Gross" + } + } + ], + "entities": { + "destination": [ + "country/NGA" + ], + "origin": [ + "country/DEU" + ] + }, + "requested_window": { + "kind": "range", + "start_year": 2020, + "end_year": 2023 + } + } + } + }, + "content_version": "cv_bf242138f8d0a892c97da9373d1626f4", + "artifact": { + "digest": "sha256:c44200969f19d73104d1bc24ebca905e59f749c2939234cdde10ba6f5a131170", + "rendering": { + "format": "parquet", + "bundle": false, + "without_party_totals": true + } + } + } + ] + }, + "expect": "accept" +}