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.
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.
sizeref://schema/chart-v1
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.
Twelve fields.
Eight required.
All numbers in a chart use one unit. Normalize and export drop any field the format does not know.
| FIELD | REQUIRED | VALUE | MEANING |
|---|---|---|---|
v | Yes | 1 | The format version. Always 1. |
unit | Yes | "in" or "cm" | Inches or centimeters, for every number in rows and kept. |
kind | Yes | "body" or "garment" | Do the numbers measure the wearer's body ("to fit") or the clothing itself? |
flat | Yes | true or false | true if the garment was measured laid flat. For a body chart, use false. Flat has no effect there. |
children | Yes | true or false | true for a children's chart. |
category | Yes | One of a list | Tops, Bottoms, Leggings, Outerwear, Dresses or Other. |
fit | No | One of a list | compression, bodyfit, fitted, regular, relaxed or oversized. |
stretch | No | One of a list | low, medium or high. |
sizes | Yes | List of text | Size labels, smallest first. 1 to 60 labels, up to 64 characters each, no repeats. |
rows | Yes | Object | One entry per size. Each holds that size's measurements: a positive number or a [min, max] range. |
aliases | No | Object | Chart size to the product's option name, such as {"2XL": "XXL"}. Shown, never used for sizing. |
kept | No | Object | Extra 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.
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_chartsets it tofalsewithout 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.
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.
"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
sizesneeds 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.
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": { "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": {
"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.
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.
{
"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.
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).
| CODE | WHAT IT MEANS |
|---|---|
NOT_V1 | Not a JSON object, or v is not 1. |
UNIT, KIND, FLAT, CHILDREN | The field is not one of its allowed values. |
CATEGORY, FIT, STRETCH | The value is not on the list. |
NO_SIZES, BLANK_SIZE, DUP_SIZE | No sizes, a blank label, or a label listed twice. |
ROW_MISSING, CELL | A size has no row, or a value is not a positive number or a [min, max] pair. |
NO_SIZING_AREAS | No chest, waist or hips is given for every size. |
FALLING | Chest, waist or hips falls from one size to the next. |
BAD_ALIASES, BAD_KEPT | aliases or kept is not in the right shape. |
BRA | Band-and-cup bra sizes. SizeRef does not size these. |
TOO_LARGE | Over 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.
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.
| FORMAT | WHAT IT IS | FOR |
|---|---|---|
sizeref_json | The chart in format v1, with $schema first. | Tools, and SizeRef's Shopify plugin (in testing). |
jsonld | A whole <script type="application/ld+json"> block. One schema.org SizeSpecification per size. | A brand's own product page. |
csv | One row per size, columns such as chest (in). | Spreadsheets. |
text | One 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.
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.
"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
}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, orurn: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 undersuggestedMeasurement. - Each value is a
QuantitativeValue:valuefor one number, orminValueandmaxValuefor a range.unitCodeisINHfor inches orCMTfor centimeters.valueReferencenames 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
namesuch asbody chest, and no measurement type. <,>and&inside the JSON are written as\uescapes, so no size label or product name can end the block. It parses back to the same JSON.
Measurement types
| MEASUREMENT | GARMENT CHART | BODY CHART |
|---|---|---|
chest | WearableMeasurementChestOrBust | BodyMeasurementChest |
waist | WearableMeasurementWaist | BodyMeasurementWaist |
hips | WearableMeasurementHips | BodyMeasurementHips |
inseam | WearableMeasurementInseam | BodyMeasurementInsideLeg |
sleeve | WearableMeasurementSleeve | Left out |
length | WearableMeasurementLength | Left out |
shoulders | Left out | Left 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.
<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>"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.
{
"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 }
}
}{
"@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 blockYour 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.
- Export for one product.Call
export_agent_ready_chartwith that product's chart, and its name and URL inproduct. - Review the result.A chart it exports can be wrong or incomplete. Check the numbers, the unit and the
omittedlist before you publish. - Paste the whole block.The
jsonldvalue 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. - Check the page.View the page source afterwards and check the block appears once.
<!-- 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.
For spreadsheets.
And for people.
CSV
- A
sizecolumn, then one column per measurement with its unit, such aschest (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.
size,chest (in),length (in),shoulders (in) S,40,27,17 M,42,28,18 L,44,29,19
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.
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.