# Data asset schema

> The schema.org Dataset properties IXO uses to describe a data asset: required, recommended and optional fields, catalog and download entries, and an example.

A data asset is any data you publish on IXO and want others to find, use and credit: a set of
claims, a model, a table of sensor readings. IXO describes data assets with structured metadata
based on schema.org, so that other systems can read the description, find the asset and attribute
it correctly.

Use this page when you write the metadata for a dataset. It lists the properties, which ones are
required, how to describe a catalog and a download, and a complete example.

## Kinds of data asset

| Kind | Examples |
| --- | --- |
| Structured data | Verifiable Claims, data models, processing algorithms, tabular data |
| Collections | Related file sets, data catalogs, search queries, dataset collections |
| Machine learning | Training parameters, neural networks, model definitions, learning datasets |
| Media assets | Data visualizations, captured metrics, sensor readings, impact evidence |

## Schema structure

### Required properties

| Property | Type | Description |
| --- | --- | --- |
| `description` | `Text` | Summary of the dataset (50-5000 chars) |
| `name` | `Text` | Descriptive name of the dataset |

The description may include Markdown syntax with absolute URLs for images.

### Recommended properties

| Property | Type | Description |
| --- | --- | --- |
| `alternateName` | `Text` | Alternative names or aliases |
| `creator` | `Person/Organisation` | Author with ORCID/ROR ID |
| `citation` | `Text/CreativeWork` | Related academic citations |
| `identifier` | `URL/Text/PropertyValue` | DOI or other identifiers |
| `license` | `URL/CreativeWork` | Distribution license |
| `version` | `Text/Number` | Version identifier |

### Optional properties

| Property | Type | Description |
| --- | --- | --- |
| `keywords` | `Text` | Search keywords |
| `spatialCoverage` | `Text/Place` | Geographic scope |
| `temporalCoverage` | `Text` | Time period covered |
| `variableMeasured` | `Text/PropertyValue` | Measured variables |
| `url` | `URL` | Dataset landing page |

## Implementation guide

1. Define the basic metadata: create a unique identifier, set the name and description, add version
   information, and specify the creator.
2. Add context: set the temporal coverage, define the spatial scope, list the measured variables,
   and add relevant keywords.
3. Configure access: set the license terms, define the distribution method, specify the formats,
   and add download URLs.
4. Link related resources: add citations, link to catalogs, reference related datasets, and include
   documentation.

## Data catalog integration

### Catalog properties

```json
{
  "@type": "DataCatalog",
  "name": "Impact Registry",
  "url": "https://registry.emerging.eco",
  "dataset": [{
    "@type": "Dataset",
    "name": "Clean Cooking Metrics",
    "includedInDataCatalog": {
      "@type": "DataCatalog",
      "name": "Impact Registry"
    }
  }]
}
```

### Download options

```json
{
  "@type": "Dataset",
  "distribution": {
    "@type": "DataDownload",
    "contentUrl": "https://data.emerging.eco/dataset.csv",
    "encodingFormat": "text/csv"
  }
}
```

## Example implementation

Illustrative example. A dataset, and the catalog entry that lists it.

<CodeGroup>
```json Dataset
{
  "@context": "https://schema.org/",
  "@type": "Dataset",
  "name": "Clean Cooking Impact Metrics",
  "description": "Monthly measurements of clean cooking adoption...",
  "creator": {
    "@type": "Organisation",
    "@id": "https://ror.org/04wxnsj81",
    "name": "Impact Organisation"
  },
  "license": "https://creativecommons.org/licenses/by/4.0",
  "identifier": "https://doi.org/10.1234/example",
  "temporalCoverage": "2023-01-01/2023-12-31",
  "variableMeasured": [
    "Fuel consumption",
    "Emissions reduction",
    "Usage patterns"
  ]
}
```

```json Catalog Entry
{
  "@context": "https://schema.org/",
  "@type": "DataCatalog",
  "name": "Impact Registry",
  "dataset": {
    "@type": "Dataset",
    "name": "Clean Cooking Impact Metrics",
    "url": "https://registry.emerging.eco/datasets/123",
    "distribution": {
      "@type": "DataDownload",
      "contentUrl": "https://data.emerging.eco/123.csv",
      "encodingFormat": "text/csv"
    }
  }
}
```
</CodeGroup>

## Best practices

| Area | Practice |
| --- | --- |
| Metadata quality | Use clear descriptions, include all required fields, add relevant keywords, and maintain version info |
| Data access | Specify clear licenses, provide download options, include format details, and document access methods |
| Identifiers | Use persistent IDs, include DOIs when available, link to canonical sources, and reference related works |
| Documentation | Add usage examples, document variables, include citations, and maintain a changelog |

## Resources

| Resource | What it is |
| --- | --- |
| [schema.org Dataset](https://schema.org/Dataset) | The full schema documentation |
| [Schema Markup Validator](https://validator.schema.org) | Checks your structured data |
| [Structured Data Markup Helper](https://www.google.com/webmasters/markup-helper/) | Google's tool for writing structured data |
| [SDK patterns](/guides/dev/examples) | Illustrative IXO code examples |
| [Developer community on Slack](https://ixofoundation.slack.com/archives/C04UERAUHQT) | Help with implementing data asset schemas |