# Data Formats (https://eulabel.eu/docs/documentation/integrations/data-formats)

> Fetch the complete documentation index at: https://eulabel.eu/docs/llms.txt
> Use this file to discover all available pages before exploring further.
> Full content: https://eulabel.eu/docs/llms-full.txt
> Append .md to any page URL for markdown, or send Accept: text/markdown.



EUlabel outputs passport data in formats aligned with GS1 standards, EU regulatory requirements, and web interoperability best practices.

At a glance [#at-a-glance]

- [JSON-LD](#json-ld-primary-passport-format) — Structured passport datasets for regulators, search engines, and interoperability
- [Linkset](#linkset-machine-discoverable-links) — Discoverable link collections returned by the resolver (RFC 9264)
- [OpenAPI](#openapi-api-contract) — The API contract that powers the reference docs and SDK generation

### When should I use which format?

* Use **JSON-LD** when you need a machine-readable passport dataset (compliance, search indexing, interoperability).
    * Use **Linkset** when you need to discover *all* available resources for a product (product page, allergens, nutrition, etc.).
    * Use **OpenAPI** when you’re integrating with the REST API or generating clients and mocks.

JSON-LD: Primary passport format [#json-ld-primary-passport-format]

Product passport data is serialized as JSON-LD using schema.org as the semantic anchor, extended with GS1 Web Vocabulary terms where schema.org lacks coverage.

JSON-LD ensures that passport data is:

* **Machine-readable** by search engines, AI agents, and regulatory systems
* **Interoperable** across platforms without proprietary data mappings
* **Discoverable** when embedded in HTML pages

Example: Wine passport as JSON-LD [#example-wine-passport-as-json-ld]
```json
{
  "@context": ["https://schema.org", "https://www.gs1.org/voc/"],
  "@type": "Product",
  "name": "Quinta dos Carvalhais Alfrocheiro 2019",
  "gtin": "05601012012200",
  "brand": {
    "@type": "Brand",
    "name": "Quinta dos Carvalhais"
  },
  "countryOfOrigin": {
    "@type": "Country",
    "name": "Portugal"
  },
  "hasIngredientList": [
    {
      "@type": "gs1:FoodBeverageTobaccoIngredientDetails",
      "ingredientName": "Grapes (Alfrocheiro)",
      "ingredientContentPercentage": 99.986
    },
    {
      "@type": "gs1:FoodBeverageTobaccoIngredientDetails",
      "ingredientName": "Sulphites",
      "ingredientContentPercentage": 0.014
    }
  ],
  "hasAllergen": [
    {
      "@type": "gs1:AllergenDetails",
      "allergenType": "https://gs1.org/voc/AllergenTypeCode-AS",
      "allergenLevelOfContainment": "CONTAINS"
    }
  ],
  "nutritionInformation": {
    "@type": "NutritionInformation",
    "servingSize": "100 mL",
    "calories": "84 kcal",
    "fatContent": "0 g",
    "carbohydrateContent": "1 g",
    "sugarContent": "0.1 g",
    "proteinContent": "0 g",
    "sodiumContent": "0 g"
  }
}
```

> **Note**
> If you’re embedding passport data in your own pages, JSON-LD is the most portable representation: it works across regulatory systems and web tooling.

Content negotiation [#content-negotiation]

Request `Accept: application/ld+json` from the passport endpoint to receive JSON-LD instead of the default JSON response:
```bash
export EULABEL_API_KEY="sk_test_..."

curl https://api.eulabel.eu/v1/products/a1b2c3d4-.../passport \
  -H "Authorization: Bearer $EULABEL_API_KEY" \
  -H "Accept: application/ld+json"
```
Embedding in HTML [#embedding-in-html]

Structured data is embedded in passport web pages using a `<script>` tag, invisible to consumers but discoverable by machines:
```html
<script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "Product",
    "name": "Quinta dos Carvalhais Alfrocheiro 2019",
    "gtin": "05601012012200"
  }
</script>
```
This satisfies two requirements simultaneously: a human-readable passport page for consumers and a machine-readable dataset for regulators and search engines.

Linkset: machine-discoverable links [#linkset-machine-discoverable-links]

Use a linkset when you want to discover what resources exist for a product (product page, nutrition section, allergen section, compliance datasets) in a single request.

* Guide: [Linkset (RFC 9264)](https://eulabel.eu/docs/documentation/integrations/linkset)
* Resolver behavior: [How the Resolver Works](https://eulabel.eu/docs/knowledge-base/concepts/resolver)

OpenAPI: API contract [#openapi-api-contract]

EUlabel publishes an OpenAPI 3.1 spec that powers this documentation and the SDK generators.

* Reference: [API Reference](https://eulabel.eu/docs/api-reference)
* SDKs: [SDK Overview](https://eulabel.eu/docs/documentation/sdks)