SpecDefinition referenceView source

Data Source Ref

Provenance of inline data or a dataset: the file, sheet and range it came from and when. Engines never read, fetch or refresh it; they keep it through editing, export and re-import. Re-import the data to update it.

Metadata

Definition: #/$defs/DataSourceRef
Form: object
Source: spec/schemas/opf.schema.json

Field index

Field	Type	Req.	Description
src	string	yes	Where the data came from: an 'asset:<id>' reference, a URL, or a relative or local path.
sheet	string	—	Sheet or table name inside a spreadsheet source.
range	string	—	A1-style range inside a spreadsheet source.
fields	array<string>	—	The source fields the data was taken from, in order.
retrieved	object \| object	—	When the data was taken from the source: an ISO 8601 date or date-time.
description	string	—	Free-form note about the source.

`src`

typestringrequiredyesdefault—

Where the data came from: an 'asset:<id>' reference, a URL, or a relative or local path.

Field fragment · src.json

{
  "src": "./data/revenue.csv"
}

`sheet`

typestringrequirednodefault—

Sheet or table name inside a spreadsheet source.

Field fragment · sheet.json

{
  "sheet": "Sheet1"
}

`range`

typestringrequirednodefault—

A1-style range inside a spreadsheet source.

Field fragment · range.json

{
  "range": "A1:D8"
}

`fields`

typearray<string>requirednodefault—

The source fields the data was taken from, in order.

Field fragment · fields.json

{
  "fields": [
    "Quarter",
    "Revenue"
  ]
}

`retrieved`

typeobject | objectrequirednodefault—

When the data was taken from the source: an ISO 8601 date or date-time.

Field fragment · retrieved.json

{
  "retrieved": "2026-10-05"
}

`description`

typestringrequirednodefault—

Free-form note about the source.

Field fragment · description.json

{
  "description": "Finance export, unaudited"
}

Complete definition constraints

Exact schema constraints

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "src"
  ],
  "description": "Provenance of inline data or a dataset: the file, sheet and range it came from and when. Engines never read, fetch or refresh it; they keep it through editing, export and re-import. Re-import the data to update it.",
  "properties": {
    "src": {
      "type": "string",
      "description": "Where the data came from: an 'asset:<id>' reference, a URL, or a relative or local path.",
      "examples": [
        "./data/revenue.csv",
        "asset:revenue",
        "https://cdn.acme.com/data/revenue.csv"
      ]
    },
    "sheet": {
      "type": "string",
      "description": "Sheet or table name inside a spreadsheet source.",
      "examples": [
        "Sheet1"
      ]
    },
    "range": {
      "type": "string",
      "description": "A1-style range inside a spreadsheet source.",
      "examples": [
        "A1:D8"
      ]
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The source fields the data was taken from, in order.",
      "examples": [
        [
          "Quarter",
          "Revenue"
        ]
      ]
    },
    "retrieved": {
      "type": "string",
      "anyOf": [
        {
          "format": "date"
        },
        {
          "format": "date-time"
        }
      ],
      "description": "When the data was taken from the source: an ISO 8601 date or date-time.",
      "examples": [
        "2026-10-05",
        "2026-10-05T09:30:00Z"
      ]
    },
    "description": {
      "type": "string",
      "description": "Free-form note about the source.",
      "examples": [
        "Finance export, unaudited"
      ]
    }
  },
  "examples": [
    {
      "src": "./data/revenue.csv",
      "retrieved": "2026-10-05"
    }
  ]
}