SKU, image & price contracts

Keep card identifiers, reference images and prices attached to their source and meaning.

Machine-readable contract · OpenAPI · Try an identifier

One identity, with an explicit scope

The SKU contract is cambridge.sku.v1. Its structure is game-set-number-language[-variant]. Preserve the returned legacy sku for existing URLs and lookups; the additive identity object carries its normalized spelling and parsed fields.

PK-SV2A-011-JP-V4K5
→ pkm-sv2a-011-ja-v4k5

This example demonstrates normalization only. Registered game aliases and Japanese language aliases normalize; set and number padding, and the order of variant tokens, stay significant. A two-letter language segment is a syntax check, not proof of an assigned language code.

Keep three questions separate: is the identifier well formed, does a catalogue record match it, and is an upstream observation mapped to that printing? Syntax does not answer the last two. Ambiguous and unmapped records remain explicit.

English reference images

The implemented ImageReference contract describes a selected English base-image row for One Piece or Fusion World. It preserves the requested identifier and the selected row’s identifier, each with its normalized syntax candidate. The relationship is always reference with syntax_only scope, including when the two canonical keys match. It never verifies an exact printing.

{
  "requested_sku": "OP-OP01-001-JP-V11DZ",
  "requested_canonical_sku": "op-op01-001-ja-v11dz",
  "depicted_sku": "OP-OP01-001-EN",
  "depicted_canonical_sku": "op-op01-001-en",
  "relationship": "reference",
  "scope": "syntax_only",
  "reason": "english_base_reference"
}

This is an illustrative Japanese-variant request linked to an English base key. No image row or provider was queried for this example. The resolver validates the complete identifiers and their supported base-key relationship; the JSON Schema checks structural shape only.

Eligible English references in market and universal-card responses carry image_url, image_attribution and image_reference together. Universal sparse responses omit all three. A retained catalogue fallback has no English-reference claim; a null reference does not prove that card art does not exist.

Publication permission is a separate decision. A valid reference, a hosted URL and a copyright caption do not grant reuse rights. This narrow contract does not implement the planned cross-source image record, verified printing crosswalk or rights-evidence model. See the image policy and integration roadmap.

How practice cards use images

A practice deck requests a card number, such as ST01-001, without choosing a language or printing. Its separate CardNumberImageReference schema preserves that request and the full selected English image key, including a parallel or reprint suffix. No requested printing SKU is invented. The existing base-image schema stays unchanged.

Starter responses carry the image URL, copyright and reference together; game-ready cards use the camelCase names imageUrl, imageAttribution and imageReference. Practice still builds the full encoded deck when images or catalogue details are unavailable.

Two existing price representations

Representation	Amount	Meaning
Legacy public fields such as `price_gbp`	Finite number or `null`, in pounds	Compatibility fields; permitted values only. No change to pennies.
Member observations	Decimal string and explicit native currency	Keep the source metric, mapping status, finish and source/retrieval times. No silent FX conversion.

The money primitive accepts zero as a numeric amount. Native source observations require positive amounts and quarantine zero sentinels; the legacy retail selector treats non-positive asking prices as unavailable. Missing, invalid and withheld values never become an invented zero or a substitute price.

Read the whole observation

Identity: use the mapped SKU only when mapping is exact. Preserve upstream identifiers when it is not.
Amount and currency: decimal text is in major units. Keep its original precision; do not use binary floating-point arithmetic to rewrite the observation.
Source and metric: a low ask, trend and recorded sale are distinct measurements. Never average them merely because their currency matches.
Time: source update time, retrieval time and pagination snapshot time describe different events. A freshly rendered response is not a freshly observed price.
Access and reuse: inspect permitted uses and attribution. Login and schema validation do not grant publication rights.

Make a request

GET /api/v1/contracts/card-data

POST /api/v1/identifiers/validate
Content-Type: application/json

{"identifier":"OP-OP01-001-JP"}

GET /api/v1/search/cards?game=op&q=OP01-001

Public search preserves the selected game and reports source unavailability separately from an empty result. Exact search results identify matching records; their syntax metadata still does not authenticate a physical copy.

The /api/v1/member-prices feed requires an account-owned member data key and applies source-specific API-use rules. Provisioning belongs in your account. Keep credentials out of URLs and public examples.

Validation and compatibility

The machine contract includes JSON Schemas for SKU identity, English image references, money and member observations. Schemas check response structure; regression fixtures check game isolation, image-reference consistency, price validation and mapping behavior. Existing endpoint names and legacy amount units remain stable.

Read the collector’s guide · Source and publication status · Agent workshop