# Manifest standard v0.1

> The nine mandatory fields, the four interface types, the four validation stages and the typical mistakes.


This summary is **not normative**; wording and details are governed solely by the standard's source in the registry repository (`registry/standard/README.md`). Version 0.1, draft of 15.08.2026, binding only after ratification by the standards commission (Art. 13 of the statutes).

## Mandatory fields {#pflichtfelder}

| Field | Form | Example |
|---|---|---|
| `$schema` | dated, immutable schema URL | `https://ld.openhelvetia.swiss/ns/manifest/schema/2026-08-15/manifest.schema.json` |
| `@context` | exactly one string | `https://ld.openhelvetia.swiss/ns/manifest/v1` |
| `@id` | stable HTTPS URI; filename = slug | `https://ld.openhelvetia.swiss/registry/openhelvetia-fedlex-mcp` |
| `@type` | constant | `Manifest` |
| `title` | language map, one string per language (de, fr, it, rm, en) | `{"de": "…", "en": "…"}` |
| `publisher` | IRI | `https://ld.openhelvetia.swiss/org/openhelvetia` |
| `license` | IRI | `https://dcat-ap.ch/vocabulary/licenses/terms_open` |
| `interfaces` | array of typed objects; per object mandatory: `@type`, `endpoint`, `auth.authType` | `[{"@type": "McpInterface", "endpoint": "…", "auth": {"authType": "none"}}]` |
| `issued` | ISO date | `2026-08-26` |

Optional and recommended: `description` and `keyword` (language maps), `landingPage`, `conformsTo`, `legalBasis`, `exactMatch`, `modified`; per interface `docs`, `conformsTo`, `tier` and `probe`. Unknown keys are validation errors.

## Interface types {#schnittstellentypen}

| Type | Meaning | Usual probe |
|---|---|---|
| `McpInterface` | MCP server, directly usable by AI systems | `mcp-discover` or `mcp-initialize` |
| `SparqlInterface` | SPARQL endpoint for linked-data queries | `sparql-ask` |
| `RestInterface` | REST API; documentation, e.g. OpenAPI, in `docs` | `http-get` or `http-head` |
| `DownloadInterface` | dumps and file distributions | `http-head` |

`auth.authType`: `none` · `apikey` · `oauth2` · `other`. `tier` per interface: `base` (stateless, low-cost) · `semantic` · `generative`. The mapping type → probe is usual, not prescribed; the standard only closes the list of probe kinds.

## How it is validated {#so-wird-geprueft}

1. **JSON Schema.** Structure and mandatory fields, `additionalProperties: false`. Possible yourself with any validator for JSON Schema 2020-12.
2. **JSON-LD round trip.** Enforces the one canonical form (key order, language order de/fr/it/rm/en, two spaces, LF). In `oh-validate`, Rust, offline.
3. **SHACL.** Against the versioned shapes; every shape rule has a negative case that provably fires.
4. **Whole graph.** After the merge: an RDFC-1.0 fingerprint and the critical invariants as SPARQL queries; every violation names its nodes.

All four stages run as a gate before every change to the register.

## Typical mistakes {#fehler}

- `"@context": [ … ]` — arrays and inline contexts are not allowed; exactly one string
- `"title": "…"` — the title is a language map, not a string
- `"license": "CC BY 4.0"` — the licence is an IRI; for 10 of 19 proven sources it was not machine-unambiguous
- `"licence": …` — unknown key: a validation error, not silent ignoring
- filename ≠ slug of the `@id` — filename = slug, unique across the registry

## Proving ground {#erprobung}

The standard is developed and validated against an internal test corpus of 19 real Swiss data sources. The corpus is proving material, not directory content. One finding: for 10 of the 19 sources the licence is not machine-unambiguous, the reason for the licence as a mandatory IRI field.

## Files {#dateien}

The canonical data host is `https://ld.openhelvetia.swiss` (mirror `w3id.org/openhelvetia`). In the repository: `registry/standard/README.md` (normative source), `context/v1.jsonld`, `frame/v1.frame.jsonld`, `schema/manifest.schema.json`, `oh-validate/`. Publicly served, byte-identical: `/ns/manifest/v1` and `/ns/manifest/schema/2026-08-15/manifest.schema.json`.

---

Source: docs/en/reference/manifest-standard.md