标准

Batch metadata schema

The off-chain document every batch commits to with metadataHash and points to with uri, generated from standard/schema/batch-metadata.schema.json on each build.

仅提供英文版

本文档以英文发布。白皮书章节和示意图已翻译；规范性标准、系统设计指南和决策记录保持英文，以确保只有一个权威文本。

Off-chain metadata document for an A-REX batch. The keccak256 of the canonical (RFC 8785 JCS) serialization of this document is stored on-chain as IARexBatch.Batch.metadataHash. Field names follow GS1 EPCIS 2.0 / CBV where a counterpart exists, and the FDA Food Traceability Rule key data elements (KDE) where relevant. Personal data of natural persons MUST NOT be placed in this document when it is published to a public location; use the restricted pointer instead.

Property	Value
Schema id	`https://arex.ag/schema/batch-metadata/1.0.0`
JSON Schema dialect	`https://json-schema.org/draft/2020-12/schema`
Required fields	`schemaVersion`, `commodity`, `unit`, `quantity`
Additional properties	allowed

How the document relates to the token

On-chain field	In the document
`metadataHash`	`keccak256` of the canonical (RFC 8785) serialization of this document
`uri`	where this document is published (IPFS, HTTPS, GS1 Digital Link)
`commodity`, `unit`	`commodity.scheme` + `commodity.code`, and `unit`, in readable form
`originRef`	`origin.originRef`; precise geodata only behind `restricted`
`status` values 1..254	`status.table`, the issuer's meaning of each value

Top-level fields

Field	Type	Required	Description
`schemaVersion`	const `1.0.0`	yes	Version of this schema the document conforms to. Always '1.0.0' for this schema.
`name`	string		Human-readable batch name, e.g. 'Hard red winter wheat, lot 2026-0412'.
`description`	string		Free-text description of the lot for people: what it is, where it is stored, special handling.
`image`	string (uri)		URI of a representative image (ERC-1155 metadata convention).
`commodity`	object	yes	Mirrors the on-chain bytes32 commodity code: keccak256(scheme + ':' + code).
`unit`	string	yes	UN/CEFACT Recommendation 20 code, e.g. KGM, TNE, LTR, BX.
`quantity`	number	yes	Quantity at creation, in `unit`. On-chain totalSupply is authoritative afterwards.
`traceabilityLotCode`	string		FSMA 204 Traceability Lot Code (TLC) assigned by the packer/initial packer. Not derived from the token id.
`gs1`	object		GS1 identifiers of the lot, when the issuer uses GS1.
`production`	object		When and how the goods were or will be produced.
`origin`	object		Origin evidence. Public documents carry references only; precise geolocation lives behind `restricted`.
`quality`	object		Grade and laboratory measurements of the lot.
`status`	object		Issuer-defined meaning of on-chain status values 1..254.
`attestations`	array of object		Informative copy of expected attestation topics; the on-chain IARexAttest registry is authoritative.
`documents`	array of object		Legal and commercial documents that govern the lot (warehouse receipts, bills of lading, certificates).
`epcis`	object		Optional EPCIS 2.0 context for indexers mapping on-chain events to EPCIS events.
`restricted`	object		Pointer to data that must not be public (precise plot polygons, producer identity). Access is governed off-chain.
`external_url`	string (uri)		Web page with more information about the lot (ERC-1155 metadata convention).
`attributes`	array of object		ERC-1155 metadata compatibility (OpenSea-style traits).

commodity

Mirrors the on-chain bytes32 commodity code: keccak256(scheme + ':' + code).

Field	Type	Required	Description
`scheme`	`HS` · `FAO` · `CPC` · `GTIN` · `NCM` · `CUSTOM`	yes	Code scheme: HS, FAO, GTIN, UNSPSC, or an issuer namespace.
`code`	string	yes	Code within the scheme, e.g. '100199' (HS, wheat).
`label`	string		Readable name of the commodity, e.g. 'Wheat, other than durum'.
`variety`	string		Variety, cultivar or breed, e.g. 'Baguette 802'.

gs1

GS1 identifiers of the lot, when the issuer uses GS1.

Field	Type	Description
`gtin`	string	GTIN of the trade item.
`lgtin`	string	GTIN plus batch/lot number (LGTIN), the GS1 identity of this lot.
`sscc`	string	SSCC of the logistic unit (pallet, container) if the lot ships as one.
`glnProducer`	string	GLN of the producing/packing location (FSMA 204 'location description' KDE).
`digitalLink`	string (uri)	GS1 Digital Link URI that resolves to this lot's information.

production

When and how the goods were or will be produced.

Field	Type	Description
`producedAt`	string (date-time)	Harvest / production time. Mirrors Batch.producedAt (empty if not yet produced).
`expectedAt`	string (date-time)	Expected harvest for pre-harvest batches.
`expiresAt`	string (date-time)	Expiry time. Mirrors Batch.expiresAt (empty if none).
`season`	string	e.g. 2025/26
`method`	string	e.g. conventional, organic, regenerative, no-till

origin

Origin evidence. Public documents carry references only; precise geolocation lives behind restricted.

Field	Type	Description
`country`	string pattern `^[A-Z]{2}$`	ISO 3166-1 alpha-2
`region`	string	First-level administrative region (state, province, department). Never a plot.
`originRef`	string	Hex of the on-chain originRef and what it references (e.g. 'sha256 of EUDR DDS #...').
`eudr`	object	Data of the EUDR due-diligence statement covering this lot, for commodities in scope.
`geohashPrecision`	integer	If a truncated geohash is published, its precision (length). Precision > 6 (~1 km) is discouraged for natural persons' plots.
`geohash`	string	Truncated geohash, only when publishing it is lawful; see geohashPrecision.

quality

Grade and laboratory measurements of the lot.

Field	Type	Description
`gradeScheme`	string	e.g. USDA, EU_FRUIT_VEG, CODEX, BR_MAPA, AR_SENASA
`grade`	string	Grade within gradeScheme, e.g. 'US No. 2'.
`measurements`	array of object	Individual laboratory or field measurements.

status

Issuer-defined meaning of on-chain status values 1..254.

Field	Type	Required	Description
`table`	object		Map from status value (as string) to label, e.g. {"1":"IN_STORAGE","2":"IN_TRANSIT","3":"DELIVERED"}

attestations

Informative copy of expected attestation topics; the on-chain IARexAttest registry is authoritative.

Field	Type	Required	Description
`topic`	string	yes	e.g. AREX:CERT:ORGANIC_EU, EUDR:DDS, GLOBALGAP:IFA
`topicHash`	string		keccak256 of topic, as used on-chain by IARexAttest.
`certificateId`	string		Identifier of the certificate at its issuer.
`issuer`	string		Issuer name or on-chain address expected to attest.

documents

Legal and commercial documents that govern the lot (warehouse receipts, bills of lading, certificates).

Field	Type	Required	Description
`type`	string	yes	e.g. warehouse_receipt, bill_of_lading, phytosanitary_certificate, lab_report, cpr
`hash`	string	yes	sha256 or keccak256 of the document
`uri`	string (uri)		May be an encrypted or access-controlled location.
`registry`	string		External registry holding the legal instrument (e.g. USDA EWR provider, B3/registradora for CPR-e).
`registryId`	string		Identifier of the instrument in that registry.

epcis

Optional EPCIS 2.0 context for indexers mapping on-chain events to EPCIS events.

Field	Type	Description
`bizStep`	string	CBV bizStep of the creation event, e.g. commissioning, harvesting, packing
`disposition`	string	CBV disposition at creation, e.g. active, in_progress.
`readPoint`	string	EPCIS readPoint of the creation event (SGLN or URI).
`bizLocation`	string	EPCIS bizLocation of the creation event (SGLN or URI).
`eventId`	string	EPCIS eventID of the off-chain event this batch mirrors, if any.

restricted

Pointer to data that must not be public (precise plot polygons, producer identity). Access is governed off-chain.

Field	Type	Description
`uri`	string (uri)	Location of the restricted document, reachable only by authorized parties.
`hash`	string	Hash of the restricted document, so authorized parties can verify what they receive.
`accessPolicy`	string	Who may access the restricted document and under which legal basis.

attributes

ERC-1155 metadata compatibility (OpenSea-style traits).

Field	Type	Required	Description
`trait_type`	string		Name of the trait, e.g. 'Grade'.
`value`			Value of the trait.

Example

From standard/examples/batch-metadata.example.json; it validates against the schema.

{
  "schemaVersion": "1.0.0",
  "name": "Trigo pan, lote 2026-0412, Cooperativa Sur",
  "description": "Hard wheat, campaign 2025/26, stored at silo 3.",
  "commodity": { "scheme": "HS", "code": "100199", "label": "Wheat, other than durum", "variety": "Baguette 620" },
  "unit": "KGM",
  "quantity": 250000,
  "traceabilityLotCode": "CS-2026-0412",
  "gs1": { "gtin": "07791234567891", "glnProducer": "7791234000012" },
  "production": {
    "producedAt": "2025-12-18T00:00:00Z",
    "expiresAt": "2027-06-30T00:00:00Z",
    "season": "2025/26",
    "method": "conventional"
  },
  "origin": {
    "country": "AR",
    "region": "Buenos Aires, partido de Tres Arroyos",
    "originRef": "keccak256 of the warehouse certificate of deposit #CD-88213",
    "geohashPrecision": 4,
    "geohash": "6dqz"
  },
  "quality": {
    "gradeScheme": "AR_SENASA",
    "grade": "Grado 2",
    "measurements": [
      { "parameter": "moisture", "value": 13.2, "unit": "%", "method": "ISO 712", "laboratory": "Lab Cámara Arbitral", "measuredAt": "2025-12-20T00:00:00Z" },
      { "parameter": "protein", "value": 11.8, "unit": "%", "method": "ISO 20483" }
    ]
  },
  "status": { "table": { "1": "IN_STORAGE", "2": "IN_TRANSIT", "3": "DELIVERED" } },
  "attestations": [
    { "topic": "AR:SENASA:PHYTOSANITARY", "certificateId": "FS-2026-1183" }
  ],
  "documents": [
    { "type": "warehouse_receipt", "hash": "sha256:9f2c…", "registry": "Warrant Ley 9.643", "registryId": "CD-88213" }
  ],
  "epcis": { "bizStep": "commissioning", "disposition": "in_progress", "bizLocation": "urn:epc:id:sgln:7791234.00001.0" },
  "restricted": { "uri": "https://vault.example/batches/2026-0412", "hash": "sha256:1a7d…", "accessPolicy": "buyer, certifier, regulator on request" }
}