rete · Guides Dataset Cards

Dataset Cards

A Dataset Card describes the data inside a .rete file: its title, licence, source and a profile of the classes and relationships it contains. Read the card before querying an unfamiliar graph. It helps you choose identifiers from the actual data rather than guessing them.

Read a card

rete card data.rete
rete card data.rete --json
rete card-url https://example.org/data.rete

The first command prints a readable summary; --json returns the structured metadata. Replace the example URL with a published graph. A remote card read uses the header and metadata ranges rather than downloading the graph's indexes. Current source builds write format 0x06, with the card region at the front; older 0x05 files locate metadata through their section directory. Published readers through 0.4.2 cannot read 0x06; see Compatibility. In the Playground, open Card to inspect the same metadata.

A file may have no card. A profile may also be partial: capped lists and truncated do not mean the graph contains only the displayed entries. See the field reference for the distinction between curated, derived and measured values.

Describe a graph you build

rete build data.nt -o data.rete --card \
  --title "My graph" --license "CC0-1.0" \
  --source "https://example.org/source"
rete card data.rete

Use the licence and source that actually apply to your data. Rete derives the profile; you supply the description and provenance. A bare build does not add a card. --card or a card metadata flag opts into one.

For a description, creators or example queries, put the curated metadata in a JSON file and pass --card-file card.json. Explicit command-line metadata overrides the corresponding file values. The complete example shows the schema.

Descriptions support Markdown, not raw HTML. Use extra for bounded publisher-defined fields rather than inventing top-level keys.

Update a published card

Fixing a card generator changes future builds, not files already published. Inspect the existing card first, preserve its curated fields, and use rete recard when only the card and build record need changing. For example, --keep-curated carries the existing publisher metadata forward; --card-file supplies it explicitly. Read the maintenance procedure before running the operation.

The card is part of the file's content hash, so changing it changes the file's identity. Keep a recovery copy before replacing a published file, verify the result and its metadata, then update the published copy and any recorded hash. --in-place avoids copying the data sections but still changes the original file; it is not a backup or an unchanged identity. In 0x06, the update uses free space in the front card region. If the new card and record do not fit, the operation falls back to copying the file.

Look up the details

The Dataset Card reference covers every field, starter queries, named-graph profiles, build records and JSON-LD/Croissant projections. The format specification owns the on-disk contract; hosting explains how to serve a graph.

Detailed topics and links from the earlier guide

What's in a card

The full-text signal: measured, not stored

The permutation signal: measured, not stored

The quoted-triple signal: measured, not stored

Time: dates, not digits

Querying the star layer

Where to get theme IRIs

One card, three versions

The description: Markdown, not HTML

Supported

Raw HTML is not supported — and that is the point

Writing a multi-line description

How long may it be?

Where a description is shown

Custom fields: the extra bag

First-class field or the bag? The rule

Why one bag, not prefixed keys

What custom fields actually cost — and the limits

Overflow: the build fails

Deterministic, hashed, tamper-evident

How the projections treat custom fields

Build conditions: the build-info section

Phases

Inputs: names, never paths; digests in the same pass

Written last, in place

Reproducible records

Compatibility

In JSON-LD

Why it sits outside the content hash

The starter-query cost figures

A build does not ship a query it just measured at zero rows

Measuring a file that already exists

The one-row smoke query

The three-tier exploration model

The starter-query library

Bounded by construction

Presence is not co-occurrence

Named-graph datasets

Fixing the card on an existing named-graph .rete

How a card goes stale

Survey first — the survey is free, the re-card is not

Deciding one file: rete card-audit

Which re-card path

What a re-card changes — and what it must not

Carrying forward is a floor — filling a blank is not rewriting

Publishing the result

Interoperability: JSON at rest, RDF on demand

The JSON-LD projection (--format jsonld)

Croissant — the honest subset (--format croissant)

Back-compatibility

In the browser

How it sits in the file