Module card 

Stable Dataset Card API — both halves of a card, so that every writer (rete build --card-file, the browser builder, any language binding, any third-party tool) produces the same card from the same graph.

• The curated half ([crate::card_input]) is the write-time rules a hand-authored card document must satisfy: the reserved top level, the theme IRI requirement, the bounded extra bag.
• The derived half ([crate::card_derive] + [crate::card_queries]) is the profile computed from the graph’s own statements — predicate/class histograms, vocabularies, datatypes, languages, the class-link quotient, hubs, affordance signals and the tiered starter-query library. card_derive::derive_card is the entry point for an in-memory quad slice; card_derive::derive_card_encoded for a streaming build that only has a dictionary + id-triples; card_derive::CardTripleSource for anything else.

Derivation is opt-in: it walks the graph a second time, so no build spends that pass unless the caller asks for a card.

Structs

CardInput

The curated subset, as supplied by a --card-file JSON document (every field optional). CLI flags override whatever the file provides. The identity/ provenance fields (version, creators, publisher, canonical_url, sparql_endpoint, source_date, derived_from, doi, cite_as, keywords, theme) have no CLI flag — they come from the card file only.

ClassLink

One edge of the effective schema graph: a predicate connecting subjects of class s_class to objects of class o_class, with the instance count. Mirrors crate::schema_summary rows (sentinels (literal)/(untyped)).

Coherence

The build-time OWL RL / RDFS coherence verdict, stamped into the card by rete build --reason. Deterministic and free of free-text detail (only a sorted by_kind histogram + short tags), so it folds into the file’s content hash without destabilizing it. scope records what was checked and rules the ruleset version, so coherent: true can’t be misread as a guarantee from a different scope or rule set.

Creator

A dataset creator: a person (or team) with an optional ORCID IRI.

DatasetCard

The embeddable dataset card. Curated fields come from rete build flags or a --card-file JSON document; the statistics are derived from the data at build time. Absent optional/empty fields are omitted from the JSON.

ExampleQuery

One vetted starter query, instantiated with the dataset’s real vocabulary.

Finding

One published query’s verdict, with the evidence behind it.

LabelIndexSignal

The file’s label-prefix-search affordance: does it carry a LABEL_INDEX section (kind 8), how many labels, and how large is it?

Observation

One starter query, actually run.

PermutationsSignal

The file’s index permutation set: how many orders of (s, p, o) it stores, and therefore whether its planner can run a sort-merge join.

Publisher

The publishing organisation, with an optional ROR IRI.

QuotedTriplesSignal

Whether the file contains quoted triples — statements standing inside other statements — and, if it does, what a consumer gets when they export it.

Recorded

The figures a build wrote into the file, beside the ones just measured.

Signals

Detected affordances — the index-free hints a newcomer (or the query-library generator) needs to know what the data supports and how to address it. Every field is optional/empty when the corresponding signal is absent, so geo/time query families are emitted only when the data actually has geometry/time.

StreamReport

How many statements a streamed card was derived from, and what the per-subject class map cost — for the caller’s progress report.

Substitution

A substituted term and where in the card profile it came from.

TextIndexSignal

The file’s full-text-search affordance: does it carry a TEXT_INDEX section (kind 6), and what does that index cost?

Enums

Claim

What the template behind an emitted query claims about its emptiness — the NonEmpty declaration, read back by id.

Tier

Which tier of the three-tier exploration model can answer a query cheapest: Card (precomputed in this metadata section, index-free), Summary (the pyramid superedge totals, index-free), or Index (needs the triple index).

Verdict

What a published starter query is worth on the file that carries it.

Constants

CARD_DESCRIPTION_MAX_BYTES

Maximum size (UTF-8 bytes) of the curated description.

CARD_EXTRA_MAX_BYTES

Maximum serialized size (compact JSON bytes) of the whole extra object.

CARD_EXTRA_MAX_DEPTH

Maximum container-nesting depth inside an extra value (see json_depth): three levels — a list of objects whose fields may be lists of scalars ([{"query": "…", "words": ["a", "b"]}]), no deeper.

CARD_EXTRA_MAX_KEYS

Maximum number of keys in extra. A key costs ≥ 8 serialized bytes, so 64 typical entries sit comfortably inside CARD_EXTRA_MAX_BYTES; needing more means the bag is being used as a data store — the graph itself is the place for data.

CARD_EXTRA_MAX_KEY_BYTES

Maximum bytes per extra key. Keys are identifiers, not values.

CARD_TOP_N

Cap for every top-N list embedded in the card. The metadata section is fetched on every overview (it is part of the index-free CARD tier), so an unbounded class_links (O(classes × predicates × classes)) or predicate list would bloat that fetch on a large schema (CIDOC-CRM/MMM). Capping keeps the card small and bounded; truncated flags when a list was actually cut.

CURATED_CARD_FIELDS

Every field a card file may carry at its top level, in the order they are declared on the CLI’s CardInput — which is also the order serde names them in its “expected one of” message, so validate_curated_card can reproduce that message verbatim.

GEO_ASWKT

GEO_HASGEOMETRY

O_LITERAL

The ClassLink::o_class sentinel for a literal object (the object of that row is a literal, so it has no class and no outgoing edges). pub: the query generator reads it to tell an entity-to-entity relation — one a path query can walk — from a literal-valued one.

QUOTED_TRIPLE_SURFACE_RDF12

The --quoted-triple-syntax value that writes the RDF 1.2 triple term <<( s p o )>>, and rete export’s default.

QUOTED_TRIPLE_SURFACE_RDF_STAR

The --quoted-triple-syntax value that writes the RDF-star surface <<s p o>>, which is also the token rete stores.

STARTER_MAX_BYTES

The most bytes a starter query may read when the build (or rete recard) measures it, counted once the file is open — the measured backstop to STARTER_SCAN_BUDGET’s estimate. A query that asks for more is dropped from the card and the drop is recorded (“did not finish”). The open is not charged: it reads the section directories (~44 MB on a 26 GB file) whatever the query, a cost no starter can change. 64 MiB is ~3× the heaviest exact body on a budget-sized graph and ~40× the heaviest bounded one.

STARTER_SCAN_BUDGET

How many statements a starter query’s body may have to read before the generator swaps it for its Bounded form (or drops it).

UNKNOWN_FIELD_HINT

The pointer appended to an unknown-top-level-key error. A stray key is usually a typo — or a custom field that belongs in the bag — and saying so costs one line and saves a round trip to the docs.

Traits

CardTripleSource

A replayable source of a graph’s default-graph triples for card derivation. replay may be called more than once (the derivation makes two passes); every call MUST yield the same triples in the same order. Terms are passed as borrowed &str valid only for that call — so the derivation owns (clones) any key it retains, letting one code path serve both an in-memory quad slice and a streaming build’s dictionary + id-triples.

Functions

audit

Audit every starter query a card already ships.

audit_examples

Audit the curated example_queries a card carries — the half of a card a publisher wrote, which audit (the generated half) never looks at.

canonicalize_json

Rebuild every nested object with its keys inserted in sorted order, so the bag’s bytes — which fold into the reproducible content hash — never depend on author key order. With today’s serde_json (no preserve_order) maps are BTree-backed and this is a no-op in effect; it is insurance that a future feature unification can’t quietly make map order mean insertion order.

check_description_len

The size half of normalize_description, split out so the CLI’s serde-typed path — where --description may override whatever the file said — can apply it to the final text without re-parsing anything.

claim_of

The Claim behind a shipped query id.

claim_of_query

The Claim behind a shipped query, read from its body as well as its id — the form to use whenever the SPARQL is at hand, because the exact and the bounded form of one template claim different things.

compose_curated_card

Finish a validated curated document into a complete card, by adding the four counts the build just measured and the format version the writer stamps.

curated_counts_card

Derive a full card from the parsed quads plus a few build-time counts — the in-memory build path. Statistics are over the default graph only (named-graph statistics are summarized by quad_count/named_graph_count), matching rete stats/rete predicates. A card holding curated fields + top-line counts only — for the external (memory-bounded) build, where deriving the profile lists (predicates/classes/ hubs/links) would need unbounded RAM. Every derived list is left empty and truncated is unset (the lists are absent, not cut).

derive_card

derive_card_encoded

Derive a card from a built dictionary + default-graph id-triples — the streaming (low-RAM) build path, where the raw quads were never retained. Resolves each id-triple back to its terms through the dictionary, yielding the same (s, p, o) strings in file order, so the card is byte-identical to the in-memory derivation on the same graph.

derive_card_from

The shared card derivation, over any CardTripleSource. Two passes: the first builds the subject→class map needed to classify both endpoints of every relation (the class_links quotient — the same logic as crate::schema_summary, folded in here to avoid a second full materialization); the second tallies everything else. All counts are over the raw (pre-dedup) default-graph multiset, matching the existing card stats and rete progressive.

derive_card_streaming

Derive a full card — profile, signals and starter queries — from a .rete that already exists, streaming its sections in sorted order with memory that does not grow with the statement count (see the section notes above).

example_query_id

The id rete card-audit gives the curated example_queries entry at index (0-based): example-1, example-2, … — curated queries carry no id of their own, and a stable positional one is what --only can name.

generate

Generate the tiered starter-query library for a card: emit each template whose required capabilities are all present, with the body picked for where the data lives (GraphScope), placeholders substituted, and the shared PREFIX block prepended. A body whose Scan is over STARTER_SCAN_BUDGET statements is replaced by its bounded form, or dropped when it has none.

json_depth

Container-nesting depth of a JSON value: scalars are 0, an array/object is 1 + its deepest child. (Recursion here is bounded by serde_json’s own 128-level parse limit.)

load_card

Read the dataset card embedded in a .rete file image, or None if it has no metadata section. Parses only the header and the metadata range — it never decodes the dictionary, index or pyramid, so a client that just built a file can read back the card it wrote for the price of a slice.

normalize_description

Accept a description written either way, and bound it — the write-time gate every card-writing path funnels through.

normalize_extra

Canonicalize and bounds-check the extra bag — the write-time gate.

normalize_string_list

Canonicalize a curated string list (keywords, theme) — the write-time gate every card-writing command funnels through (like normalize_extra).

normalize_themes

normalize_string_list plus the theme requirement: every entry must be an IRI into a controlled vocabulary. This is what keeps theme from becoming a second keywords field — a free-text theme carries no more meaning than a keyword, and keywords already holds those; the agreed concept scheme behind the IRI is the whole value dcat:theme adds.

validate_curated_card

Validate and canonicalize a whole curated card document — the JSON a publisher writes for --card-file, or types into the playground’s builder.