Token efficiency. A typical product page (HTML + JSON-LD) is ~200 KB. CommerceTXT is ~10 KB. For AI agents processing thousands of products, this reduces token costs and bandwidth by ~95%.

A more interesting comparison would be to compare your format versus a pure JSON-LD payload, after http's gzip compression.

Basically, you are suggesting to replace this (200 bytes):

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Sony WH-1000XM5",
  "gtin": "027242919412",
  "sku": "WH1000XM5",
  "url": "https://techstore.example.com/products/sony-wh-1000xm5",
  "model": "WH-1000XM5"
}

With this (144 bytes)

# @PRODUCT
Name: Sony WH-1000XM5
GTIN: 027242919412
SKU: WH1000XM5
URL: https://techstore.example.com/products/sony-wh-1000xm5
Model: WH-1000XM5

So we are talking about a saving of 56 bytes (28%) before compression. These days, it is not rare to have half a kilobyte of http headers. I personally don't think such a saving are worth introducing a new format, but that's just my claim. At any rate, schema.org is just a schema which defines what object have what properties, how it is serialised is orthogonal.

What we are asking: We want to ensure our usage of the vocabulary is semantically correct. We welcome any technical guidance on the cleanest way to map these flat text keys to Schema.org properties (e.g. best practices for an external Context definition).

The cleanest thing to do is to parse the schema turtle files and generate your serialisation / deserialisation logic based on that. Note that there is typographic convention that types start with an Upper-case and properties with a lower-case letter.

The core issue I see is that schema.org (actually JSON-LD) is structured so flattening might not be trivial, or even efficient, how do you represent something like this (the reason I omitted brand above, also note that WH1000XM5 is an MPN ):

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@id": "https://www.sony.com/#organization",
      "@type": ["Brand", "Organization"], 
      "name": [
        { "@language": "en", "@value": "Sony" },
        { "@language": "ja", "@value": "ソニー" }
      ],
      "url": "http://sony.com"
    },
    {
      "@type": "ProductModel",
      "@id": "https://techstore.example.com/products/sony-wh-1000xm5/#product",
      "name": "Sony WH-1000XM5",
      "gtin": "027242919412",
      "mpn": "WH1000XM5",
      "brand": { "@id": "https://www.sony.com/#organization" },
      "manufacturer": { "@id": "https://www.sony.com/#organization" },
      "url": "https://www.sony.ch/de/electronics/kopfband-kopfhoerer/wh-1000xm5",
      "offers": [
        {
          "@type": "Offer",
          "price": 200,
          "priceCurrency": "EUR",
          "url": "https://techstore.example.com/products/sony-wh-1000xm5?curr=EUR",
          "availability": "https://schema.org/InStock"
        },
        {
          "@type": "Offer",
          "price": 190,
          "priceCurrency": "CHF",
          "url": "https://techstore.example.com/products/sony-wh-1000xm5?curr=CHF",
          "availability": "https://schema.org/InStock"
        }
      ]
    }
  ]
}

Just to add a working example to the conversation, @jdevalk implemented an Alternate Document Location, as described in the json-ld specs.

For example:
This page has its json-ld embedded in the HTML of the page, whereas its http header mentions its alternate location with Link: <https://joost.blog/path-forward-for-wordpress/schema/>; rel="alternate"; type="application/ld+json", while the alternate location only serves the json-ld.

1. On your JSON-LD comparison (200 bytes vs 144 bytes)
You're right-after compression, the byte difference is modest. But LLM cost is measured in tokens, not bytes.

• Your JSON-LD example: 87 tokens
• Your CommerceTXT example: 57 tokens
• Token reduction: ~35%

This matters at scale. For AI agents, tokens = cost.Gemini 3 Pro charges ~$2 per 1M input tokens and has a 1M token context limit.

The Context Window Constraint:
It's not just about cost, it's about capacity. Gemini 3 Pro has a 1M token context limit.

• HTML scraping (~25K tokens/product): An agent can compare ~40 products max before hitting context limits.
• CommerceTXT (~2.5K tokens/product): An agent can compare ~400 products.

This directly impacts UX: enabling better recommendations, comprehensive comparisons, and smarter shopping assistance.

2. Retrieval Cost
Merchants don't serve pure JSON-LD files. They embed JSON-LD inside HTML product pages.

• Typical Product Page: 300 KB - 1 MB HTML (Many complex sites exceed this significantly)
• CommerceTXT: ~10 KB

AI agents must:

1. Fetch entire HTML page (parsing heavy DOMs)
2. Filter out noise (scripts, ads, navigation)
3. Extract the JSON-LD block

The inefficiency isn't JSON-LD itself- it's the cost of extracting it from the heavy HTML wrapper. That represents thousands of wasted tokens per product visit.

3. Headers vs. Files
@jvandriel's suggestion of an Alternate Document Location via Link headers is architecturally elegant. However, platforms like Shopify, Wix and Squarespace do not expose HTTP header control to merchants.

CommerceTXT democratizes this by using a simple Static Asset Workflow:

1. Export from CRM/PIM once a day.
2. Upload commerce.txt (via FTP or Admin Panel).
3. Update: Price change? Just overwrite the text file.

CommerceTXT follows the success of robots.txt / ads.txt: a static file uploadable via FTP or admin panel. No dev team, no server config required.

4. Fault Tolerance
JSON is brittle and breaks on a single syntax error. CommerceTXT is line-based. A parser can skip malformed lines and continue parsing the rest of the catalog. For merchant-generated content, this resilience is critical.

5. Agent-Specific Features
JSON-LD represents structured data. CommerceTXT can add explicit agent instructions/logic:

# @SEMANTIC_LOGIC
If user asks "battery life" -> reply "24+ hours typical use"

There is no Schema.org equivalent for this type of behavioral guidance.

We're not trying to replace JSON-LD's semantic richness. We are proposing a commerce-optimized, agent-first protocol that complements JSON-LD. Different tools, different jobs.

Look, as I said, this is not the place to discuss serialisation methods. If you think this commerce.txt is better, have fun evangelising for its adoption.

If the format supports the full schema.org model, meaning you can serialise schema.org data in the commerce.txt format, then your documentation (not the thread here) needs to explain how this is achieved, and what kind of relationship there is (injection, bijection, etc), and how the translation is done, and how coupling is enforced – as I mentioned – importing schema.org turtle files seems like the most straightforward approach.

If the format is loosely based on the schema.org model (as the brand example seems to show), then this should be explicitly stated, and the documentation should probably explain the relationship with flat commerce file structures, like the Google Shopping Feed (and the Facebook Open-AI variants). In that case, further discussion here, does not seem warranted.

Thank you for the guidance, @MatthiasWiesmann.

You're right- the best comparison is to a Google Shopping Feed: a domain-specific format that uses Schema.org vocabulary but isn't a general Schema.org serialization.

CommerceTXT uses Schema.org concepts (Product, Offer, Brand) implemented in flat text optimized for LLM token efficiency. It solves the specific problem of AI agents reading commerce data without the overhead of HTML scraping.

Our request to this community is strictly for semantic validation (mapping properties like @INVENTORY to schema:inventoryLevel) and vocabulary guidance. We are not asking for CommerceTXT to become an official Schema.org serialization format, nor do we intend to handle the full complexity of the Schema.org graph.

We will update our documentation to clarify that CommerceTXT uses Schema.org as a semantic vocabulary, not as a web serialization format. It complements JSON-LD by providing an LLM-optimized interface. We will publish a formal mapping table and focus our efforts on AI platform adoption.

Thank you for helping us find the right framing.