Metadata schemas

Each Boson offer (and the seller / collection / voucher entities around it) carries an off-chain metadata document pinned to IPFS, with its content hash stored on-chain. The schemas below define those documents.

@bosonprotocol/metadata wraps each schema with yup (via schema-to-yup) and exposes a validator per type. The JSON Schema is the source of truth.

Helpers

import {
  productV1MetadataSchema,
  bundleMetadataSchema,
  validateMetadata,
  createVariantProductMetadata,
} from "@bosonprotocol/metadata"
 
// There are no `*MetadataFactory()` helpers — construct the metadata object
// directly against the schema's required fields. `validateMetadata` (Yup)
// raises if anything is missing.
const metadata = {
  schemaUrl: "https://schema.org/Product",
  type: "PRODUCT_V1" as const,
  uuid: crypto.randomUUID(),
  // …all other required fields…
}
validateMetadata(metadata as any)  // throws on invalid; no return value

For PRODUCT_V1 offers with variants (e.g. multiple sizes), use createVariantProductMetadata(baseMetadata, variants) — that's the only metadata-building helper exported by the package.

`BASE`

Source: packages/metadata/src/base/schema.json

Field	Type	Required
`schemaUrl`	string	yes
`type`	`"BASE"`	yes
`name`	string	yes
`description`	string	yes
`image`	string	no
`imageData`	string	no
`externalUrl`	string	yes
`licenseUrl`	string	yes
`condition`	string	no
`animationUrl`	string	no
`youtubeUrl`	string	no
`attributes`	object[] — see attributes[]	no

`attributes[]`

Field	Type	Required
`traitType`	string	yes
`value`	string	yes
`displayType`	string	no

`PRODUCT_V1`

Source: packages/metadata/src/product-v1/schema.json

Field	Type	Required
`schemaUrl`	string	yes
`type`	`"PRODUCT_V1"`	yes
`uuid`	string	yes
`name`	string	yes
`description`	string	yes
`externalUrl`	string	yes
`licenseUrl`	string	yes
`youtubeUrl`	string	no
`condition`	string	no
`image`	string	yes
`imageData`	string	no
`animationUrl`	string	no
`attributes`	object[] — see attributes[]	yes
`product`	object — see product	yes
`variations`	object[] — see variations[]	no
`seller`	object — see seller	yes
`shipping`	object — see shipping	yes
`exchangePolicy`	object — see exchangePolicy	yes
`productOverrides`	object — see productOverrides	no

`attributes[]`

Field	Type	Required
`traitType`	string	yes
`value`	string	yes
`displayType`	string	no

`product`

Field	Type	Required
`uuid`	string	yes
`version`	number	yes
`title`	string	yes
`description`	string	yes
`identification_sKU`	string	no
`identification_productId`	string	no
`identification_productIdType`	string	no
`productionInformation_brandName`	string	yes
`productionInformation_manufacturer`	string	no
`productionInformation_manufacturerPartNumber`	string	no
`productionInformation_modelNumber`	string	no
`productionInformation_materials`	string[]	no
`details_category`	string	no
`details_subCategory`	string	no
`details_subCategory2`	string	no
`details_offerCategory`	`"PHYSICAL"` \| `"PHYGITAL"` \| `"DIGITAL"`	yes
`details_tags`	string[]	no
`details_sections`	string[]	no
`details_personalisation`	string[]	no
`visuals_images`	object[] — see product.visuals_images[]	yes
`visuals_videos`	object[] — see product.visuals_videos[]	no

`variations[]`

Field	Type	Required	Description
`type`	string	yes
`option`	string	yes

`seller`

Field	Type	Required
`defaultVersion`	number	yes
`name`	string	yes
`description`	string	no
`externalUrl`	string	no
`tokenId`	string	no
`images`	object[] — see seller.images[]	no
`contactLinks`	object[] — see seller.contactLinks[]	yes

`shipping`

Field	Type	Required
`defaultVersion`	number	no
`countryOfOrigin`	string	no
`supportedJurisdictions`	object[] — see shipping.supportedJurisdictions[]	no
`redemptionPoint`	string	no
`returnPeriod`	string	yes

`exchangePolicy`

Field	Type	Required
`uuid`	string	yes
`version`	number	yes
`label`	string	no
`template`	string	yes
`sellerContactMethod`	string	yes
`disputeResolverContactMethod`	string	yes

`productOverrides`

Field	Type	Required
`title`	string	no
`description`	string	no
`identification_sKU`	string	no
`identification_productId`	string	no
`identification_productIdType`	string	no
`productionInformation_brandName`	string	no
`productionInformation_manufacturer`	string	no
`productionInformation_manufacturerPartNumber`	string	no
`productionInformation_modelNumber`	string	no
`productionInformation_materials`	string[]	no
`visuals_images`	object[] — see productOverrides.visuals_images[]	no
`visuals_videos`	object[] — see productOverrides.visuals_videos[]	no

`product.visuals_images[]`

Field	Type	Required	Description
`url`	string	yes
`tag`	string	no

`product.visuals_videos[]`

Field	Type	Required	Description
`url`	string	yes
`tag`	string	no

`seller.images[]`

Field	Type	Required	Description
`url`	string	yes
`tag`	string	no

`seller.contactLinks[]`

Field	Type	Required	Description
`url`	string	yes
`tag`	string	yes

`shipping.supportedJurisdictions[]`

Field	Type	Required	Description
`label`	string	yes
`deliveryTime`	string	yes

`productOverrides.visuals_images[]`

Field	Type	Required	Description
`url`	string	yes
`tag`	string	no

`productOverrides.visuals_videos[]`

Field	Type	Required	Description
`url`	string	yes
`tag`	string	no

`BUNDLE`

Source: packages/metadata/src/bundle/schema.json

Field	Type	Required
`schemaUrl`	string	yes
`type`	`"BUNDLE"`	yes
`name`	string	yes
`description`	string	yes
`image`	string	no
`imageData`	string	no
`externalUrl`	string	yes
`licenseUrl`	string	yes
`youtubeUrl`	string	no
`condition`	string	no
`animationUrl`	string	no
`attributes`	object[] — see attributes[]	no
`bundleUuid`	string	yes
`seller`	object — see seller	yes
`items`	object[] — see items[]	yes

`attributes[]`

Field	Type	Required
`traitType`	string	yes
`value`	string	yes
`displayType`	string	no

`seller`

Field	Type	Required
`defaultVersion`	number	yes
`name`	string	yes
`description`	string	no
`externalUrl`	string	no
`tokenId`	string	no
`images`	object[] — see seller.images[]	no
`contactLinks`	object[] — see seller.contactLinks[]	yes

`items[]`

Field	Type	Required	Description
`url`	string	yes

`seller.images[]`

Field	Type	Required	Description
`url`	string	yes
`tag`	string	no

`seller.contactLinks[]`

Field	Type	Required	Description
`url`	string	yes
`tag`	string	yes

`ProductV1 bundle item`

Source: packages/metadata/src/productV1Item/schema.json

Field	Type	Required
`schemaUrl`	string	yes
`type`	`"ITEM_PRODUCT_V1"`	yes
`uuid`	string	yes
`product`	object — see product	yes
`variations`	object[] — see variations[]	no
`shipping`	object — see shipping	yes
`exchangePolicy`	object — see exchangePolicy	yes
`productOverrides`	object — see productOverrides	no

`product`

Field	Type	Required
`uuid`	string	yes
`version`	number	yes
`title`	string	yes
`description`	string	yes
`identification_sKU`	string	no
`identification_productId`	string	no
`identification_productIdType`	string	no
`productionInformation_brandName`	string	yes
`productionInformation_manufacturer`	string	no
`productionInformation_manufacturerPartNumber`	string	no
`productionInformation_modelNumber`	string	no
`productionInformation_materials`	string[]	no
`details_category`	string	no
`details_subCategory`	string	no
`details_subCategory2`	string	no
`details_offerCategory`	`"PHYSICAL"` \| `"PHYGITAL"` \| `"DIGITAL"`	yes
`details_tags`	string[]	no
`details_sections`	string[]	no
`details_personalisation`	string[]	no
`visuals_images`	object[] — see product.visuals_images[]	yes
`visuals_videos`	object[] — see product.visuals_videos[]	no

`variations[]`

Field	Type	Required	Description
`type`	string	yes
`option`	string	yes

`shipping`

Field	Type	Required
`defaultVersion`	number	no
`countryOfOrigin`	string	no
`supportedJurisdictions`	object[] — see shipping.supportedJurisdictions[]	no
`redemptionPoint`	string	no
`returnPeriod`	string	yes

`exchangePolicy`

Field	Type	Required
`uuid`	string	yes
`version`	number	yes
`label`	string	no
`template`	string	yes
`sellerContactMethod`	string	yes
`disputeResolverContactMethod`	string	yes

`productOverrides`

Field	Type	Required
`title`	string	no
`description`	string	no
`identification_sKU`	string	no
`identification_productId`	string	no
`identification_productIdType`	string	no
`productionInformation_brandName`	string	no
`productionInformation_manufacturer`	string	no
`productionInformation_manufacturerPartNumber`	string	no
`productionInformation_modelNumber`	string	no
`productionInformation_materials`	string[]	no
`visuals_images`	object[] — see productOverrides.visuals_images[]	no
`visuals_videos`	object[] — see productOverrides.visuals_videos[]	no

`product.visuals_images[]`

Field	Type	Required	Description
`url`	string	yes
`tag`	string	no

`product.visuals_videos[]`

Field	Type	Required	Description
`url`	string	yes
`tag`	string	no

`shipping.supportedJurisdictions[]`

Field	Type	Required	Description
`label`	string	yes
`deliveryTime`	string	yes

`productOverrides.visuals_images[]`

Field	Type	Required	Description
`url`	string	yes
`tag`	string	no

`productOverrides.visuals_videos[]`

Field	Type	Required	Description
`url`	string	yes
`tag`	string	no

`NFT bundle item`

Source: packages/metadata/src/nftItem/schema.json

Field	Type	Required
`schemaUrl`	string	yes
`type`	`"ITEM_NFT"`	yes
`name`	string	yes
`description`	string	no
`image`	string	no
`imageData`	string	no
`externalUrl`	string	no
`animationUrl`	string	no
`youtubeUrl`	string	no
`image_data`	string	no
`external_url`	string	no
`animation_url`	string	no
`youtube_url`	string	no
`attributes`	object[] — see attributes[]	no
`chainId`	number	no
`contract`	string	no
`tokenId`	string	no
`tokenIdRange`	object — see tokenIdRange	no
`terms`	object[] — see terms[]	no
`quantity`	number	no

`attributes[]`

Field	Type	Required
`traitType`	string	no
`trait_type`	string	no
`value`	string	yes
`displayType`	string	no
`display_type`	string	no

`tokenIdRange`

Field	Type	Required	Description
`min`	string	no
`max`	string	no

`terms[]`

Field	Type	Required
`key`	string	yes
`value`	string	yes
`displayKey`	string	no

`rNFT`

Source: packages/metadata/src/rNFT/schema.json

Field	Type	Required
`schemaUrl`	string	yes
`type`	`"rNFT"`	yes
`name`	string	yes
`description`	string	yes
`image`	string	no
`externalUrl`	string	yes
`licenseUrl`	string	yes
`condition`	string	no
`animationUrl`	string	no
`attributes`	object[] — see attributes[]	no

`attributes[]`

Field	Type	Required
`traitType`	string	yes
`value`	string	yes
`displayType`	string	no

`SELLER`

Source: packages/metadata/src/seller/schema.json

Field	Type	Required
`type`	`"SELLER"`	yes
`name`	string	no
`description`	string	no
`legalTradingName`	string	no
`kind`	string	yes
`website`	string	no
`images`	object[] — see images[]	no
`contactLinks`	object[] — see contactLinks[]	no
`contactPreference`	string	yes
`socialLinks`	object[] — see socialLinks[]	no
`salesChannels`	object[] — see salesChannels[]	no

`images[]`

Field	Type	Required
`url`	string	yes
`tag`	string	no
`type`	string	yes
`width`	number	no
`height`	number	no
`fit`	string	no
`position`	string	no

`contactLinks[]`

Field	Type	Required	Description
`url`	string	yes
`tag`	string	yes

`socialLinks[]`

Field	Type	Required	Description
`url`	string	yes
`tag`	string	yes

`salesChannels[]`

Field	Type	Required
`tag`	string	yes
`name`	string	no
`settingsUrl`	string	no
`settingsEditor`	string	no
`link`	string	no
`deployments`	object[] — see salesChannels[].deployments[]	no

`salesChannels[].deployments[]`

Field	Type	Required
`product`	object — see salesChannels[].deployments[].product	no
`status`	string	no
`link`	string	no
`lastUpdated`	string	no

`salesChannels[].deployments[].product`

Field	Type	Required	Description
`uuid`	string	no
`version`	number	no

`COLLECTION`

Source: packages/metadata/src/collection/schema.json

Field	Type	Required
`schemaUrl`	string	yes
`type`	`"COLLECTION"`	yes
`name`	string	yes
`description`	string	no
`image`	string	no
`externalLink`	string	no
`external_link`	string	no
`collaborators`	string[]	no

Source

Package: @bosonprotocol/metadata
Schemas: packages/metadata/src/<domain>/schema.json

Helpers

BASE

attributes[]

PRODUCT_V1

attributes[]

product

variations[]

seller

shipping

exchangePolicy

productOverrides

product.visuals_images[]

product.visuals_videos[]

seller.images[]

seller.contactLinks[]

shipping.supportedJurisdictions[]

productOverrides.visuals_images[]

productOverrides.visuals_videos[]

BUNDLE

attributes[]

seller

items[]

seller.images[]

seller.contactLinks[]

ProductV1 bundle item

product

variations[]

shipping

exchangePolicy

productOverrides

product.visuals_images[]

product.visuals_videos[]

shipping.supportedJurisdictions[]

productOverrides.visuals_images[]

productOverrides.visuals_videos[]

NFT bundle item

attributes[]

tokenIdRange

terms[]

rNFT

attributes[]

SELLER

images[]

contactLinks[]

socialLinks[]

salesChannels[]

salesChannels[].deployments[]

salesChannels[].deployments[].product

COLLECTION

Source

Related

`BASE`

`attributes[]`

`PRODUCT_V1`

`attributes[]`

`product`

`variations[]`

`seller`

`shipping`

`exchangePolicy`

`productOverrides`

`product.visuals_images[]`

`product.visuals_videos[]`

`seller.images[]`

`seller.contactLinks[]`

`shipping.supportedJurisdictions[]`

`productOverrides.visuals_images[]`

`productOverrides.visuals_videos[]`

`BUNDLE`

`attributes[]`

`seller`

`items[]`

`seller.images[]`

`seller.contactLinks[]`

`ProductV1 bundle item`

`product`

`variations[]`

`shipping`

`exchangePolicy`

`productOverrides`

`product.visuals_images[]`

`product.visuals_videos[]`

`shipping.supportedJurisdictions[]`

`productOverrides.visuals_images[]`

`productOverrides.visuals_videos[]`

`NFT bundle item`

`attributes[]`

`tokenIdRange`

`terms[]`

`rNFT`

`attributes[]`

`SELLER`

`images[]`

`contactLinks[]`

`socialLinks[]`

`salesChannels[]`

`salesChannels[].deployments[]`

`salesChannels[].deployments[].product`

`COLLECTION`