Manifests
Both kinds use apiVersion: datanivra.io/v1alpha1 and the envelope apiVersion, kind, metadata (name, optional description) and spec. Inside spec the field names are the canonical v1 contract names (snake_case), so a manifest and a REST body are the same data.
Parsing is deliberately conservative, in the CLI and in both SDK helpers:
- at most 256 KiB and one document; nesting deeper than 32 levels is refused;
- YAML anchors and aliases, explicit tags (such as
!!python/object) and duplicate keys are refused; - unknown fields are errors; nothing is evaluated, interpolated or executed;
- errors name the field path and a machine code (for example
spec.scenarios.0.count: LESS_THAN_EQUAL), never the submitted value.
datanivra test-data validate FILE checks a manifest locally and prints its canonical checksum.
TestDataProfile (privileged definition)
A profile is a TEST_DATA_PROFILE policy. Its name is a portable slug (lower-case letters, digits, ., _, -, at most 63 characters). Versions are immutable; each is submitted for review and approved by someone other than the author or submitter, who confirms the exact checksum. The checksum of a profile manifest's spec equals the checksum DataNivra records for the version created from it.
datanivra test-data define profiles/healthcare-integration.yaml --submit # creates a DRAFT version
datanivra policies approve <POLICY_ID> <VERSION> --expected-checksum <CHECKSUM> --reason "Reviewed" # a second person| Profile field | Meaning |
|---|---|
fulfilment | LEASE_CERTIFIED_VERSION (hydrate an already certified version) or BUILD_DATASET (build and certify a new dataset) |
delivery_boundary | CUSTOMER_RUNNER_ONLY (the only value): data is consumed from customer-controlled targets by your own runners |
lease | Lease settings (exactly when fulfilment is LEASE_CERTIFIED_VERSION) |
build | Build settings (exactly when fulfilment is BUILD_DATASET) |
automation | Optional automation envelope for named workload identities |
audit_tags | Up to 16 codes recorded on every request |
lease
| Lease field | Meaning |
|---|---|
dataset_id | Certified dataset to lease |
dataset_version | Pinned version, or omitted for the dataset's current version at request time (recorded in the request) |
agent_id | Customer agent that hydrates and tears down the targets |
tier | Tier of the leased environments (default QA) |
provider_kind | Kind of customer-controlled target, e.g. POSTGRESQL_CONTAINER |
target_pool | 1–64 secret references (for example vault://ci/qa-db-1); each live request holds one exclusively |
default_ttl_seconds, max_ttl_seconds | Lease lifetime when the request does not choose, and the largest it may ask for (300 s – 7 days) |
The pool is what makes concurrent pull requests safe: every live request gets its own approved target, and a request can never name a target itself. When every target is in use the request fails with TARGET_POOL_EXHAUSTED; retry after a running request is released.
build
| Build field | Meaning |
|---|---|
business_domain, pack_id, dataset_kind | As in an ordinary dataset request (SYNTHETIC_ONLY, MASKED_PRODUCTION_LIKE, HYBRID) |
source_ids, subset | Approved sources and subset, fixed by the profile; a synthetic-only profile has none |
masking_policy, certification_policy, identity_graph | Pinned policy references (policy_id, kind, version, checksum) |
target_environment_id | The approved target environment |
retention_days | Days until the built dataset expires |
synthetic_augmentation_ratio | Synthetic rows per subset row |
scenarios | Up to 32 offered scenarios: scenario_code, kind, pack_id, default_count, max_count, included_by_default |
max_total_records | Hard ceiling of the sum of scenario counts in one request |
automation (envelope)
| Envelope field | Meaning |
|---|---|
workload_identity_ids | Workload identity trusts allowed to invoke this profile (1–16) |
max_ttl_seconds | Longest lease approved automatically (lease profiles) |
scenario_limits | Tighter per-scenario counts approved automatically (scenario_code, max_count) |
max_total_records | Largest total approved automatically (build profiles) |
max_live_requests | Live requests per identity (default 10) |
max_requests_per_hour | Requests per identity per hour (default 60) |
escalate_out_of_envelope | Outside the envelope but inside the profile: wait for a person (true, default) or deny (false) |
An envelope can never be wider than its profile: the contract refuses limits above the profile's own bounds. See Automatic approval.
TestDataRequest (invocation)
| Request field | Meaning |
|---|---|
profile | name, version (an approved version) and optional checksum you reviewed — a mismatch is refused |
scenarios | Optional list of scenario_code and exact count; omitted = the profile's defaults (build profiles only) |
ttl_seconds | Optional lease lifetime (lease profiles only) |
purpose_ref | Optional ticket, e.g. QA-1234 |
ci_ref | Optional CI reference: provider, repository, pr_number, run_id, commit_sha. A live request of the same identity, profile version and run is returned instead of creating a second one |
Count semantics. Counts are exact: the engine generates exactly the number requested. Minimum, maximum or best-effort counts are not offered. A count above the profile's max_count, or a total above max_total_records, is denied.
Pinned versions. Older approved versions stay pinnable after a newer one is approved, so existing CI files keep working; a deprecated or revoked version is refused (PROFILE_DEPRECATED, PROFILE_REVOKED). Updating a profile never silently widens what existing pins allow.
Reproducibility. Every plan and request carries a request_checksum: the SHA-256 of the resolved request (profile checksum, scenarios, counts, TTL, dataset and version).
Validation and decision codes
A denied request answers 403 TEST_DATA_REQUEST_DENIED with the reason codes in details, and nothing is created. The full list is in Automatic approval.