Open standardv0.3.1

The WineGraph Open Data Model

Name: WineGraph Open Data Model
Creator: WineGraph
License: https://opendatacommons.org/licenses/odbl/

One canonical model for the wine trade. Producer → wine → vintage → SKU, joined to who imports, distributes, and pours it, with the source behind every field.

Building a wine site, or moving data between layers of the trade? Adopt this model, publish to it, and plug into the graph. It is the same model WineGraph runs in production: open, versioned, and machine-readable. The spec is free to use. Entity resolution and the resolved corpus are the hosted product.

Machine-readable

Artifacts

JSON Schemaschema+json JSON-LD contextld+json OpenAPI (the /v1 API)openapi Discovery descriptor.well-known

The wall

Data classification

Every entity, edge, and field carries a visibility tier. Most of the graph is public; some data is walled off by design — and the standard says so explicitly.

Public

Free, anonymous, crawlable. Identities, relationships, and public web presence — the neutral moat.

Gated gated · paid

Paid account required. Publicly-sourced but sensitive in aggregate: license-holder names/addresses/permit dossiers, precise geo, contacts.

Private private · tenant-authorized

The publishing tenant’s authorization, per recipient. Pricing (always), inventory, sales, customer/CRM. Never public.

The model

Entities

Supply — producers & wines

producerProducer

A winery / estate / négociant that makes wine.

founded · sizeHa · farming · philosophy · production · org.legal [gated] · org.contact [gated] · geo.precise [gated]

skuWine (SKU)

A specific bottling — the canonical wine unit. Producer + cuvée + vintage + format.

wine.color · wine.sparkling · wine.grapes · wine.farming · wine.abv · wine.appellation · facets

vintageVintage

A vintage-level grouping (optional intermediate between wine and SKU).

brandBrand

A commercial brand spanning bottlings.

personPerson

An individual in the wine world (winemaker, vineyard manager, owner, oenologist, consultant). Role is carried on the person_of edge, not the type.

person.bio · web

vineyardVineyard

A named vineyard / parcel / cru site (distinct from a region). Rich parcel detail is optional + provenance-stamped.

vineyard.hectares · vineyard.soil · vineyard.elevation · vineyard.aspect · vineyard.planted

Trade — importers & distributors

export_agentExport Agent

An export agent / courtier (e.g. Becky Wasserman & Co) that represents grower domaines for export — the layer between producer and importer.

org.role · org.seat · web

importerImporter

A US importer of record (TTB permit holder).

org.permit · org.dba · org.legal [gated] · org.contact [gated]

distributorDistributor

A wholesaler / distributor (state-licensed).

org.legal [gated] · org.contact [gated]

Demand — shops & restaurants

retailerWine Shop

An off-premise retailer.

geo · web

restaurantRestaurant

An on-premise venue with a wine list.

geo · web

Reference — regions, grapes, places, terms

regionRegion

A wine region / appellation with content + hierarchy.

reference.slug* · reference.content · reference.parentSlug

grapeGrape

A grape variety with content.

reference.slug* · reference.content

placePlace

A town / site / landmark.

reference.slug*

termTerm

A glossary concept / technique / classification.

reference.slug*

Accolades — critics, awards, publications

awardAward

A discrete honor (Michelin star, Wine Spectator Grand Award, …).

accolade.issuer* · accolade.scale

criticCritic

A wine/restaurant critic or critic-outlet.

accolade.issuer

publicationPublication

An editorial outlet (reviews, lists).

accolade.issuer

Commerce — pricing, inventory, accounts (private / gated)

pricePriceprivate · tenant-authorized

A tenant's price for a wine — by tier, jurisdiction, and volume. Default-private, tenant-elected visibility: defaults to private and is shared only with accounts the publishing tenant authorizes (the price-feed model), but the tenant MAY widen visibility at its own election. The hard antitrust fence is on cross-tenant Ring-3 aggregates, not on a tenant publishing its own list.

skuRef* · tenantRef* · tier · jurisdiction · amountCents · currency · unit · minQty · validFrom · validTo · authorizedFor

inventoryInventoryprivate · tenant-authorized

On-hand + allocated stock for a wine, per tenant. PRIVATE.

skuRef* · tenantRef* · onHand · allocated · asOf

accountAccountprivate · tenant-authorized

A tenant's commercial relationship with a buyer (a retailer/restaurant/distributor). Sales + CRM are PRIVATE; contact + detailed profile are GATED; the buyer's existence/type is public via its retailer/restaurant entity.

buyerRef · type · profile [gated] · contact [gated] · metrics [private] · crm [private]

The graph

Relationships

producesproducer → skuA producer makes a wine.

representsexport_agent → producerAn export agent represents a producer/domaine for export.

person_ofperson → producerA person works at a producer; the role is on the edge.

farmsproducer → vineyardA producer farms a vineyard.

sourced_fromsku → vineyardA bottling's fruit comes from a vineyard.

farmed_assku|producer|vineyard → termA farming practice (term.kind=farming).

uses_techniquesku|producer → termA winemaking technique (term.kind=technique).

importsimporter → skuAn importer brings a wine into the US.

distributesdistributor → skuA distributor carries a wine.

listed_byretailer|restaurant → skuA venue lists/pours a wine.

in_regionproducer|sku → regionLocated in / from a region.

has_grapesku → grapeMade from a grape variety.

subregion_ofregion → regionRegion hierarchy.

related_toreference → referenceCross-link between reference entries.

awardedaward → restaurant|retailer|sku|producerAn award held by an entity.

rated_bycritic|publication → sku|restaurantA rating from a critic/outlet.

reviewed_bypublication → restaurant|skuAn editorial review.

listed_inaward|publication → restaurant|retailerMembership in a curated list (Resy/OpenTable/50 Best).

The trust layer

Provenance envelope

Every enriched field carries provenance — value, source, confidence, and when it was observed — so merges are highest-confidence-wins and never silently overwrite. This is what makes the model trustworthy across many publishers.

value*objectThe asserted value.

source*stringSource identifier (connector / publisher).

confidence*number0–1 confidence.

observedAt*dateWhen observed (ISO date).

refstringSource URL / reference.

Cross-system

Identifiers

ttb_permit

US TTB importer/wholesaler permit number.

osm

OpenStreetMap `<type>/<id>`.

slug

WineGraph URL slug.

learned

A learned match key from the resolver corpus.

importer_site

Importer/distributor portfolio site-local id.

producer_name

Normalized producer name.

accolade_slug

Award/critic/publication slug.

Controlled

Vocabularies

Colours

red · white · rose · orange

Reference types

region · grape · place · term

Entity types (21)

producer · sku · vintage · brand · person · vineyard · export_agent · importer · distributor · retailer · restaurant · region · grape · place · term · award · critic · publication · price · inventory · account

Get involved

Build on the commons

The model is open and versioned, and it grows with the trade. However you fit in, there is a way to use it and to give back.

Read the data. The /v1 API and the dataset both speak this model.
Publish your data. Expose a /.well-known/winegraph.json and a conformant feed, and anyone can ingest it, us included.
Build on it. Type definitions, a connector SDK, a validator CLI, and a one-click site starter are on the way, all open source.

Spec licensed Apache-2.0 · open graph data ODbL · v0.3.1, semantically versioned.