# Mosaicora OG Overrides v3

The `mosaicora:og` block adds exact, semantic Open Graph image values to the
structured data you already publish. It does not replace your Schema.org data.

Version 3 requires `schemaVersion` and `semanticValues`:

```json
{
  "@context": {
    "schema": "https://schema.org",
    "mosaicora": "https://mosaicora.io/ns#"
  },
  "@type": "Product",
  "name": "Example product",
  "mosaicora:og": {
    "schemaVersion": 3,
    "templateId": "6a36446a0021410e8044",
    "semanticValues": {
      "content.title": "Example product",
      "product.price": "$49",
      "product.features": ["Fast setup", "Consistent previews"],
      "social.verified": true,
      "image.primary": "https://example.com/product.png"
    }
  }
}
```

Legacy flat fields and presentation settings are not part of v3. Add only the
semantic values that must override Mosaicora's automatic extraction.

`templateId` is optional. Mosaicora uses it only when the template
belongs to the same account as the site.

## Text roles

- `content.title`, `content.description`, `content.category`, `content.url`
- `organization.name`
- `person.name`, `person.role`, `person.image`, `person.honorificPrefix`
- `article.datePublished`, `publication.frequency`
- `product.price`, `product.originalPrice`
- `offer.discount`, `offer.couponCode`, `offer.shippingDetails`, `offer.validThrough`
- `aggregateRating.ratingValue`, `aggregateRating.reviewCount`
- `software.releaseStatus`, `software.status`, `software.version`
- `job.baseSalary`, `job.experienceRequirements`, `job.skills`
- `place.name`
- `recipe.season`, `recipe.prepTime`, `recipe.cookTime`, `recipe.recipeYield`
- `creativeWork.collectionLabel`, `creativeWork.dateCreated`, `creativeWork.collectionId`
- `interaction.commentsCount`
- `social.followersCount`, `social.followingCount`, `social.postsCount`, `social.mutualFriends`
- `collection.productCount`
- `image.primary`

Text roles accept non-empty strings.

## List, boolean, and metric roles

- `product.features`, `navigation.items`, and `image.secondary` accept non-empty string arrays.
- `social.verified` accepts a boolean.
- `analytics.metrics` accepts metric objects with non-empty `id`, `label`, and `value` strings.

```json
{
  "schemaVersion": 3,
  "semanticValues": {
    "navigation.items": ["Overview", "Pricing", "Documentation"],
    "analytics.metrics": [
      { "id": "reach", "label": "Reach", "value": "1.2M" }
    ]
  }
}
```

## Contract

- `schemaVersion` must be the number `3`.
- `templateId`, when present, must be a non-empty string.
- `semanticValues` is required and may be empty.
- Unknown roles, aliases, legacy flat fields, and presentation settings are not supported.
- The package provides exact TypeScript types; runtime validation remains the responsibility of the service consuming the JSON-LD.
- The canonical machine-readable schema is available at `https://mosaicora.io/ns/og/v3/schema.json`.