Skip to content
TRY THE PILOT
CHART FORMAT v1

One shape for a chart.
Four ways to export it.

SizeRef chart format v1 says what every number means: the unit, body or garment, flat or all the way round. The export tool writes it out as SizeRef JSON, schema.org JSON-LD, CSV and text.

Format v1JSON Schema 2020-12Server v0.1.0
01 / The format

Every chart.
The same shape.

Every chart normalize returns, and every chart export takes, has the same shape. normalise_size_chart produces it. export_agent_ready_chart takes it. It is the same format SizeRef's Shopify plugin sizes from. The plugin is in testing and not yet in the Shopify App Store.

A JSON Schema sets the shape. Read it from the server as a resource, or from its web address.

SCHEMA RESOURCE
sizeref://schema/chart-v1
SCHEMA URL
https://mcp.sizeref.online/schema/chart-v1.json

This server takes size charts, never a person's measurements, and keeps none of the charts you send. Every chart on this page is fictional.

See the pilot terms and the privacy details. It is for use in the US and India, and not in the EU, EEA or UK.

02 / Field by field

Twelve fields.
Eight required.

All numbers in a chart use one unit. Normalize and export drop any field the format does not know.

FIELDREQUIREDVALUEMEANING
vYes1The format version. Always 1.
unitYes"in" or "cm"Inches or centimeters, for every number in rows and kept.
kindYes"body" or "garment"Do the numbers measure the wearer's body ("to fit") or the clothing itself?
flatYestrue or falsetrue if the garment was measured laid flat. For a body chart, use false. Flat has no effect there.
childrenYestrue or falsetrue for a children's chart.
categoryYesOne of a listTops, Bottoms, Leggings, Outerwear, Dresses or Other.
fitNoOne of a listcompression, bodyfit, fitted, regular, relaxed or oversized.
stretchNoOne of a listlow, medium or high.
sizesYesList of textSize labels, smallest first. 1 to 60 labels, up to 64 characters each, no repeats.
rowsYesObjectOne entry per size. Each holds that size's measurements: a positive number or a [min, max] range.
aliasesNoObjectChart size to the product's option name, such as {"2XL": "XXL"}. Shown, never used for sizing.
keptNoObjectExtra columns of the other kind (body or garment), kept for export only.

A chart may also carry $schema. The SizeRef JSON export puts the schema URL there.

03 / What a number means

Body or garment.
Flat or all the way round.

The same number can mean very different things. Three fields remove the doubt.

kind: "body"
The numbers describe the person a size is meant for. A "to fit" chart.
kind: "garment"
The numbers describe the clothing itself, measured on the item.
flat: true
The garment was laid flat and measured across, so chest, waist and hips are half the full measurement. For sizing and for the CSV, text and JSON-LD exports, those three are doubled to the full circumference. Other measurements, such as length or sleeve, are never doubled.
flat: false
The numbers are already the full measurement. On a body chart flat has no effect. When a body chart leaves flat out, normalise_size_chart sets it to false without asking.

Flat is stated, never guessed. A flat width of 20 inches becomes a circumference of 40 inches. The tools double a number only when the chart says flat: true. Nothing is inferred from the numbers.

04 / Sizes and rows

One row per size.
A number or a range.

sizes lists the labels in order, smallest first. rows holds one object per label, keyed by the label.

ROWS · A NUMBER AND A RANGE
"sizes": ["S", "M"],
"rows": {
  "S": { "waist": [71, 76], "inseam": 81 },
  "M": { "waist": [77, 82], "inseam": 81 }
}
  • A value is a positive number, or a [min, max] pair with min at most max.
  • Every size in sizes needs a row. Rows for sizes not in the list are dropped.
  • Up to 60 sizes, and up to 40 measurements in one size. Size labels and measurement names are up to 64 characters.

Measurement names

The names the tools understand are chest, waist, hips, inseam, sleeve, shoulders and length. Only chest, waist and hips are used to pick a size. The others are carried through and exported.

At least one of chest, waist or hips must be given for every size. Length and sleeve alone cannot pick a size. As sizes grow, each of chest, waist and hips that is given for every size must rise or stay level. On a Tops chart with chest, hips is not checked unless the product title names a long top such as a kurta or a dress.

05 / The other fields

Context for the numbers.
Kept separate from them.

category, children, fit, stretch

category and children are required. fit and stretch are optional. When normalize works from a table, it asks for category and children, unless you already gave them in answers. For a garment table it also asks for stretch, and for fit unless product_text names one. For a chart, it asks only for missing required fields. Each answer must be one of the values in the fields table.

aliases

Maps a chart size to the size name the product uses, when the two differ. Every key must be a size in the chart. Every value must be non-blank, and no two sizes may share an option.

ALIASES
"aliases": { "2XL": "XXL" }

kept

Some tables hold body and garment columns side by side. The chart sizes by one kind. The other kind's columns can travel in kept: they are exported, never used for sizing.

KEPT · SHAPE
"kept": {
  "kind": "body",
  "columns": ["chest"],
  "rows": { "S": { "chest": [34, 36] } }
}

When a chart has kept columns, the CSV and text name every column with its kind, such as garment chest and body chest.

06 / A full example

A fictional tee.
Measured flat, in inches.

This chart is made up for this page. It is a garment chart: chest is a flat width, length runs top to hem, shoulders is across the back.

CHART V1 · FICTIONAL SAMPLE TEE
{
  "v": 1,
  "unit": "in",
  "kind": "garment",
  "flat": true,
  "children": false,
  "category": "Tops",
  "fit": "regular",
  "stretch": "low",
  "sizes": ["S", "M", "L"],
  "rows": {
    "S": { "chest": 20, "length": 27, "shoulders": 17 },
    "M": { "chest": 21, "length": 28, "shoulders": 18 },
    "L": { "chest": 22, "length": 29, "shoulders": 19 }
  }
}

The export examples below all come from this chart, sent to the live server with a fictional product: name Sample Tee, brand Example Co, URL https://shop.example.com/products/sample-tee.

07 / Checks

A chart that fails
says why.

Audit and normalize report each problem with a code, a short text and a fix. The text names the field and the size. It does not repeat a value that is not allowed, such as a wrong unit or category. A warning can show the number it questions, in centimeters. Export refuses a chart with any error, or with a required field missing (code MISSING).

CODEWHAT IT MEANS
NOT_V1Not a JSON object, or v is not 1.
UNIT, KIND, FLAT, CHILDRENThe field is not one of its allowed values.
CATEGORY, FIT, STRETCHThe value is not on the list.
NO_SIZES, BLANK_SIZE, DUP_SIZENo sizes, a blank label, or a label listed twice.
ROW_MISSING, CELLA size has no row, or a value is not a positive number or a [min, max] pair.
NO_SIZING_AREASNo chest, waist or hips is given for every size.
FALLINGChest, waist or hips falls from one size to the next.
BAD_ALIASES, BAD_KEPTaliases or kept is not in the right shape.
BRABand-and-cup bra sizes. SizeRef does not size these.
TOO_LARGEOver a limit: sizes, measurements, or characters in a name.

One more code is only a warning. IMPLAUSIBLE means a value, in centimeters, falls outside a usual range. Check the unit and the digits. A warning never makes a chart fail.

08 / Exports

One call.
Four formats.

export_agent_ready_chart takes a valid chart in chart_v1. It returns each format in formats, or all four when you leave that out.

FORMATWHAT IT ISFOR
sizeref_jsonThe chart in format v1, with $schema first.Tools, and SizeRef's Shopify plugin (in testing).
jsonldA whole <script type="application/ld+json"> block. One schema.org SizeSpecification per size.A brand's own product page.
csvOne row per size, columns such as chest (in).Spreadsheets.
textOne readable line per size.People, emails, notes.

Each answer also holds:

  • omitted: each measurement left out of the JSON-LD, and why. It is empty when nothing was left out.
  • jsonld_note, when JSON-LD was asked for.
  • warnings, when there are any.
  • note: "SizeRef stored nothing from this request."

The optional product takes name and brand (up to 255 characters each) and url (starting http:// or https://, up to 2048 characters). name labels the JSON-LD and the text heading. brand and url are used in the JSON-LD only. The numbers never change.

09 / SizeRef JSON

The chart itself.
Nothing added.

The sizeref_json export is the chart as sent, with $schema set to the schema URL. Only format v1 fields are written, in schema order. Rows are kept for the listed sizes only. Numbers stay as stated: a flat chest stays a flat width.

OUTPUT FROM THE LIVE SERVER, v0.1.0, 17 NOV 2026 · TRIMMED
"sizeref_json": {
  "$schema": "https://mcp.sizeref.online/schema/chart-v1.json",
  "v": 1,
  "unit": "in",
  "kind": "garment",
  "flat": true,
  …the other fields, the same as in the sample chart above
}
10 / schema.org JSON-LD

Open vocabulary.
One entry per size.

The jsonld export uses the open schema.org vocabulary for sizes. Each size becomes a SizeSpecification inside one @graph.

How each size is written

  • @id. With a product URL: <url>#size-<size>. Without one: urn:sizeref:<product name>:<size>, with the name lowercased and hyphenated, or urn:sizeref:chart:<size> when no name is given. The size is URL-encoded, and any # part of the product URL is dropped.
  • name. Brand, product name and size, such as Example Co Sample Tee - S. Just the size when no product is given.
  • alternateName. The product's option name, when the chart has an alias for that size.
  • Garment charts list values under hasMeasurement. Body charts list them under suggestedMeasurement.
  • Each value is a QuantitativeValue: value for one number, or minValue and maxValue for a range. unitCode is INH for inches or CMT for centimeters. valueReference names the schema.org measurement type.
  • A flat garment's chest, waist and hips are written as the full circumference, with the note "measured flat, shown as full circumference".
  • Kept columns are written with a name such as body chest, and no measurement type.
  • <, > and & inside the JSON are written as \u escapes, so no size label or product name can end the block. It parses back to the same JSON.

Measurement types

MEASUREMENTGARMENT CHARTBODY CHART
chestWearableMeasurementChestOrBustBodyMeasurementChest
waistWearableMeasurementWaistBodyMeasurementWaist
hipsWearableMeasurementHipsBodyMeasurementHips
inseamWearableMeasurementInseamBodyMeasurementInsideLeg
sleeveWearableMeasurementSleeveLeft out
lengthWearableMeasurementLengthLeft out
shouldersLeft outLeft out

A measurement with no type in this table is left out of the JSON-LD and listed once in omitted, with the reason. It still appears in the CSV and text.

What the block leaves out on purpose

  • No Product node. The block holds sizes only, so it does not repeat what the product page already says about the product.
  • No sizeSystem, sizeGroup, suggestedAge or suggestedGender. The export does not write them.
  • No category, fit, stretch or children. These stay in SizeRef JSON.

The fictional tee, exported

The sample chart, with the fictional product above. The chest is doubled because the chart says flat: true. Shoulders is left out.

OUTPUT FROM THE LIVE SERVER, v0.1.0, 17 NOV 2026 · TRIMMED TO SIZE S
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "SizeSpecification",
      "@id": "https://shop.example.com/products/sample-tee#size-S",
      "name": "Example Co Sample Tee - S",
      "hasMeasurement": [
        {
          "@type": "QuantitativeValue",
          "value": 40,
          "unitCode": "INH",
          "valueReference": "https://schema.org/WearableMeasurementChestOrBust",
          "description": "chest measured flat, shown as full circumference"
        },
        {
          "@type": "QuantitativeValue",
          "value": 27,
          "unitCode": "INH",
          "valueReference": "https://schema.org/WearableMeasurementLength"
        }
      ],
      "description": "Example Co Sample Tee, size S. chest measured flat, shown as full circumference."
    },
    …sizes M and L follow in the same shape (chest 42 and 44, length 28 and 29)
  ]
}
</script>
OUTPUT FROM THE LIVE SERVER, v0.1.0, 17 NOV 2026 · OMITTED AND NOTES
"omitted": [
  { "area": "shoulders",
    "reason": "schema.org has no wearable measurement type for shoulders." }
],
"jsonld_note": "Optional: the theme can link each variant's size to the matching @id in this block. This step is not required.",
"note": "SizeRef stored nothing from this request."

A body chart, with ranges

A second fictional chart: body measurements in centimeters for a Sample Pant, with no product URL. Values sit under suggestedMeasurement, and ranges use minValue and maxValue.

INPUT · FICTIONAL SAMPLE PANT
{
  "v": 1, "unit": "cm", "kind": "body", "flat": false,
  "children": false, "category": "Bottoms",
  "sizes": ["S", "M"],
  "rows": {
    "S": { "waist": [71, 76], "hips": [91, 96], "inseam": 81 },
    "M": { "waist": [77, 82], "hips": [97, 102], "inseam": 81 }
  }
}
OUTPUT FROM THE LIVE SERVER, v0.1.0, 17 NOV 2026 · TRIMMED TO SIZE S
{
  "@type": "SizeSpecification",
  "@id": "urn:sizeref:sample-pant:S",
  "name": "Sample Pant - S",
  "suggestedMeasurement": [
    {
      "@type": "QuantitativeValue",
      "minValue": 71,
      "maxValue": 76,
      "unitCode": "CMT",
      "valueReference": "https://schema.org/BodyMeasurementWaist"
    },
    {
      "@type": "QuantitativeValue",
      "minValue": 91,
      "maxValue": 96,
      "unitCode": "CMT",
      "valueReference": "https://schema.org/BodyMeasurementHips"
    },
    {
      "@type": "QuantitativeValue",
      "value": 81,
      "unitCode": "CMT",
      "valueReference": "https://schema.org/BodyMeasurementInsideLeg"
    }
  ],
  "description": "Sample Pant, size S."
}
…size M follows in the same shape, inside the same @graph and script block
11 / On a product page

Your page.
Your block.

The JSON-LD is something a brand adds to its own product page, if it wants to. SizeRef does not publish it, and the server never touches a store. Any store that can add a block of HTML to a product page can use it. It does not need Shopify.

  1. Export for one product.Call export_agent_ready_chart with that product's chart, and its name and URL in product.
  2. Review the result.A chart it exports can be wrong or incomplete. Check the numbers, the unit and the omitted list before you publish.
  3. Paste the whole block.The jsonld value already includes the opening and closing script tags. Add it once to that product's page, in that product's own HTML, not in a template other products share.
  4. Check the page.View the page source afterwards and check the block appears once.
WHERE IT GOES · ILLUSTRATIVE PRODUCT PAGE
<!-- Your existing product page -->
<h1>Sample Tee</h1>
…

<!-- Pasted once: the jsonld value from export_agent_ready_chart -->
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [ …one SizeSpecification per size… ]
}
</script>

Put one block on each product page, made for that product. A block made for one product does not belong on another. Linking each variant's size to its @id in the theme is optional, as jsonld_note says.

No reader is promised. The block uses the open schema.org format for size data. What any AI assistant or search engine reads from a page is up to it. No assistant is promised to read this block, and whether any reads these measurements today has not been tested.

12 / CSV and text

For spreadsheets.
And for people.

CSV

  • A size column, then one column per measurement with its unit, such as chest (in).
  • A flat garment's chest, waist and hips are doubled to the full measurement.
  • Ranges are written as 71-76. An empty cell means the size has no value for that column.
  • A field that a spreadsheet could read as a formula gets a leading '. A field with a quote, comma or line break is quoted.
OUTPUT FROM THE LIVE SERVER, v0.1.0, 17 NOV 2026 · FICTIONAL TEE
size,chest (in),length (in),shoulders (in)
S,40,27,17
M,42,28,18
L,44,29,19
OUTPUT FROM THE LIVE SERVER, v0.1.0, 17 NOV 2026 · FICTIONAL PANT
size,waist (cm),hips (cm),inseam (cm)
S,71-76,91-96,81
M,77-82,97-102,81

Text

A heading line, then one line per size. A doubled value shows the flat number after it. A size with an alias shows the product's option name.

OUTPUT FROM THE LIVE SERVER, v0.1.0, 17 NOV 2026 · FICTIONAL TEE
Sample Tee: size chart, garment measurements in inches
S: chest 40 in (20 in flat), length 27 in, shoulders 17 in
M: chest 42 in (21 in flat), length 28 in, shoulders 18 in
L: chest 44 in (22 in flat), length 29 in, shoulders 19 in

The CSV and text keep every measurement, including the ones the JSON-LD leaves out.

13 / Next

Bring your own chart.
Start with an audit.