[Tools](https://oods-foundry.com/tools) / structured_data_fetch

# `structured_data_fetch`

Fetch live registry datasets, archived token/export data, or captured-run artifacts.

Generated from @oods/foundry 0.10.1

One of the 20 tools your assistant sees by default.

Use it when you need complete machine-readable data; use catalog_list instead for component selection, object_registry for one object's definition, or registry_snapshot for mappings together with traits and objects. Returns data with provenance, version and cache metadata. dataset selects registry/export mode; version pins an archived export and listVersions lists dates. kind plus runPath selects captured artifacts, while derived_analysis reads an analysis directory via runPath; version/listVersions are refused in kind mode. includeInternal exposes hidden objects, and ifNoneMatch checks the canonical payload ETag. Reference: TOOL-REFERENCE.md#structured_data_fetch; full schema: oods\://schemas/structured_data_fetch.input.json.

## Inputs

| Name | Type | Required | Description |
| - | - | - | - |
| `dataset` | `"components" \| "tokens" \| "manifest"` | no | Local structured dataset to return (components/tokens/manifest). Mutually exclusive with kind+runPath. |
| `kind` | `"identity_graph" \| "capability_rollup" \| "object_rollup" \| "drift_report" \| "derived_analysis" \| "a11y_report" \| "report_index" \| "a11y_evidence" \| "run_manifest"` | no | Stage1 structured artifact kind to read from runPath. See full schema for details. |
| `runPath` | `string` | no | Filesystem path to a Stage1 run directory or its artifacts/ subdirectory. Required when kind is set. |
| `ifNoneMatch` | `string` | no | Return matched=true without payload when the ETag matches. |
| `includePayload` | `boolean` | no | When false, omit payload even if no ETag match occurs. |
| `version` | `string` | no | Request a specific date-stamped version (e.g., '2026-02-24'). Omit for latest. Applies to dataset mode only. |
| `listVersions` | `boolean` | no | When true, return available version dates instead of payload. |
| `includeInternal` | `boolean` | no | Live components dataset only: also list OODS Foundry's internal (non-business) objects, after the business objects. Without it they are left out and registry.hiddenInternal counts them; a dated export is served unchanged. |

## Outputs

| Name | Type | Required | Description |
| - | - | - | - |
| `dataset` | `"components" \| "tokens" \| "manifest"` | no | Dataset that was requested (dataset mode only). |
| `kind` | `"identity_graph" \| "capability_rollup" \| "object_rollup" \| "drift_report" \| "derived_analysis" \| "a11y_report" \| "report_index" \| "a11y_evidence" \| "run_manifest"` | no | Stage1 structured artifact kind that was requested (kind mode only). |
| `schemaVersion` | `string` | no | Stage1 artifact schema_version (kind mode only). |
| `runId` | `string` | no | Stage1 run_id extracted from the artifact (kind mode only). |
| `version` | `string \| null` | no | Version tag (usually the YYYY-MM-DD stamp from the manifest). |
| `generatedAt` | `string \| null` | no | Timestamp recorded in the payload. |
| `etag` | `string` | yes | Stable hash of the payload (generatedAt excluded). |
| `matched` | `boolean` | yes | True when ifNoneMatch matched the current ETag and payload was skipped. |
| `payloadIncluded` | `boolean` | yes | True when the payload field is returned. |
| `path` | `string` | yes | Resolved export path. For the live components projection, this supplies historical evidence and annotations; the returned definitions come from the live registry. |
| `manifestPath` | `string \| null` | no | Manifest path when available. |
| `sizeBytes` | `integer` | yes | Serialized payload byte size for the live projection; file size for committed exports. |
| `schemaValidated` | `boolean` | yes | True when the payload was validated against a schema. |
| `validationErrors` | `string[]` | no | Optional validation error messages. |
| `warnings` | `string[]` | no | Non-fatal warnings encountered during resolution. |
| `meta` | `object` | no | Lightweight summary for the payload. |
| `payload` | `object` | no | Payload contents when payloadIncluded=true. |
| `availableVersions` | `string[]` | no | Available version dates when listVersions=true. |
| `requestedVersion` | `string \| null` | no | The version that was requested (null if latest). |
| `resolvedVersion` | `string \| null` | no | The version that was actually resolved (may differ from requested if nearest match used). |

## A real call

Recorded by this site's `system` run, step `components-export`, with the published OODS Foundry 0.10.1.

Its input:

```
{
  "dataset": "components"
}
```

Its result, first lines:

```
{
  "dataset": "components",
  "version": "2026-10-06",
  "generatedAt": "2026-10-06T04:59:14Z",
  "etag": "b956a05523d1d08ce5acdefd4d64646f1bac329150de674ba6c08c4f9d8caa2c",
  "matched": false,
  "payloadIncluded": true,
  "path": "artifacts/structured-data/oods-components-2026-10-06.json",
  "manifestPath": "artifacts/structured-data/manifest.json",
  "sizeBytes": 727861,
  "schemaValidated": true,
  "meta": {
    "componentCount": 114,
    "traitCount": 49,
    "objectCount": 11,
    "domainCount": 1,
    "patternCount": 2,
    "source": "live-registry"
  },
  "payload": {
    "$schema": "./component-schema.json",
    "obligationScope": {
      "schemaVersion": "1.0.0",
      "decisionId": 2527,
      "disposition": "retain-all-obligations",
      "controllingObligationDenominator": 114,
      "approvedRuntimeCensus": null,
      "classificationStatus": "proposed-awaiting-approval"
    },
    "generatedAt": "2026-10-06T04:59:14Z",
    "stats": {
      "componentCount": 114,
      "traitCount": 49,
      "objectCount": 11,
      "domainCount": 1,
      "patternCount": 2
    },
    "components": [
      {
        "id": "AddressCollectionPanel",
        "displayName": "AddressCollectionPanel",
        "categories": [
          "core"
        ],
        "tags": [
          "address",
          "delivery",
          "location",
          "validation"
        ],
        "contexts": [
          "detail"
        ],
        "regions": [
          "detail",
          "form",
          "list"
        ],
        "traitUsages": [
          {
```

[The whole call, 1144 KB of JSON](https://oods-foundry.com/tools/structured-data-fetch/call.json)