DatasetMetadata
Canonical JSON document anchored on-chain by DatasetVersionRegistry.
A document of this kind carries a schema field matching xny://schemas/dataset-metadata/<major>.<minor> — the version is part of the URI, and it is the only place a document's version is recorded.
Canonical JSON document anchored on-chain by DatasetVersionRegistry. Supersedes DatasetMetadata.schema.json (which is now deprecated). Describes the dataset version's storage coordinates, CF list, and encryption metadata. The contributions field has been removed; CF attribution is now derived from the cfListUri merkle tree.
Fields
| Field | Type | Required | Description |
|---|---|---|---|
schema | string | yes | Per-kind versioned schema identifier. Format: xny://schemas/dataset-metadata/<major.minor>. This is the single source of truth for document version; do not use schema_version. |
kind | string | yes | Document kind discriminator. Always 'dataset-metadata' for this schema. |
publisher | string | yes | DID of the entity that published this document. Pseudonymous identifier written to the permanent Arweave layer. DID-to-identity mapping exists only in an off-chain deletable layer (GDPR note: deletion right does not cover this field). |
published_at | string | yes | RFC 3339 / ISO 8601 UTC timestamp of document publication. |
tags | object | yes | Free-form key-value metadata tags for indexing and filtering. Bounded to 32 entries with keys up to 64 characters — conservative structural limits to keep the anchored document small, not a semantic constraint on tag content. Values are permanently written to Arweave alongside the rest of this document: do not put personal data in a tag (see CONVENTIONS.md's GDPR Note). |
datasetId | string | yes | Dataset version identifier. On-chain bytes32 = keccak256(abi.encodePacked(assemblerDidId, manifestId, versionNumber)). 0x-prefixed bytes32 hex: the executor's injectDatasetFields always writes common.Hash.Hex() into this field, and the indexer's decodeBytes32 already requires exactly this shape when reading it back. |
versionNumber | integer | yes | Contract-assigned dataset version (1-based) — the third input to datasetId = keccak256(abi.encodePacked(assemblerDidId, manifestId, versionNumber)). The indexer cross-checks it against the on-chain DatasetVersionRegistry anchor. Because it is a JSON integer read by arbitrary (often IEEE-754-backed) parsers, the executor refuses to serialize a version above 2^53-1 (the max safe JSON integer) rather than emit one that would round; on-chain versions are sequential, so this bound is unreachable in practice. |
primaryFrontierId | string | yes | Claimed primary frontier for this dataset version. Verification input ONLY — not to be trusted directly; authoritative result comes from the derivation chain (cf → task → campaign → frontier). |
cfListUri | string | yes | URI pointing to the ordered list of ContributionFingerprint identifiers included in this dataset version (e.g. arweave://...). |
cfListHash | string | yes | Integrity anchor for the document at cfListUri: sha256 of its raw bytes, bare hex without 0x prefix. Mirrors the manifestUri/manifestHash pairing rather than contributorsMerkleRoot's 0x-keccak256 on-chain convention, because cfListUri (like manifestUri) is a plain off-chain document reference with no on-chain register of its own -- see CONVENTIONS.md's metadataHash Semantics section for the two off-chain-vs-on-chain hash conventions this repo uses. Required for every new dataset publication. |
contributorsMerkleRoot | string | yes | Root of the two-layer Ownership Merkle Tree built over the CF list at cfListUri (see docs/contracts/ownership-merkle-tree.md): Layer-1 is a per-contributor tree over raw cfIds (cfMerkleRoot); Layer-2 has one leaf per contributor DID. This is the SAME value anchored on-chain in DatasetVersionRegistry.contributorsMerkleRoot and verified by OwnershipRegistry.claimDatasetShares; the metadata carries it for offline self-contained verification. 0x-prefixed bytes32 keccak256 hex — unlike the bare-hex sha256 manifestHash, this field mirrors an on-chain bytes32, so it keeps the 0x prefix for direct comparison against the on-chain root. |
cfCount | integer | yes | Number of ContributionFingerprints in the CF list. |
cfListFormat | string | yes | Serialisation format of the CF list document (e.g. 'ndjson', 'csv'). Consumers use this to select the correct parser. |
manifestUri | string | yes | Inner-layer encrypted chunk manifest URI — points at the payload listing encrypted under the dataset-version DEK. This field does not define key custody or authorised key release. Distinct from the CF list (cfListUri). Retained from DatasetMetadata for read-path compatibility. |
manifestHash | string | yes | Hash of the encrypted chunk manifest bytes referenced by manifestUri. SHA-256 hex digest without a 0x prefix. Inner-layer integrity anchor. |
encryptionSuite | string | yes | Symmetric encryption algorithm used for the inner-layer payload (e.g. 'AES-256-GCM'). |
status | ACTIVE | REVOKED | ARCHIVED | yes | DEPRECATED: this value records publication-time intent ONLY and can NEVER transition afterward -- the document is hash-anchored (metadataHash = keccak256(exact bytes), no in-place editing) and DatasetVersionRegistry exposes no metadata-update entry point (only assembleDataset + getters). Consumers MUST NOT render this field as the dataset version's current lifecycle state. Scheduled for removal at the next major bump; see CONVENTIONS.md's Dataset lifecycle ownership matrix for which registry actually owns each real lifecycle transition (stop-sale, grant revocation, content takedown, quality supersession). |
Example
5 rejection cases are kept alongside the schema in docs/schemas/examples/, exercised by validate_schemas.py.
Last updated