# Data contracts

This reference describes the implemented browser application's portable formats. It does not introduce a REST API, SDK, MCP server or automation endpoint. Use the real interface for supported tasks. Documentation examples are inert data and contain no production credentials.

## Network schema version 1

The durable Network document has `schemaVersion: 1`. Its top-level fields are `id`, `title`, `description`, `entities`, `relationships`, `sources`, `citations`, `layout`, `createdAt` and `updatedAt`. The source contract is `contracts/graph-document.schema.json`; the implementation additionally validates cross-record invariants in `src/domain/schemas/network.ts`.

A minimal, complete synthetic Network follows. The fixed ID and timestamps belong to this example, not to a real investigation or publication date. Import it only once into a browser profile unless the existing copy has been deliberately removed by a supported workflow.

```json
{
  "schemaVersion": 1,
  "id": "b584a8f6-49b3-4d46-8d77-dd0d51fb1171",
  "title": "LB Docs — Empty practice Network",
  "description": "Fictional documentation example. No real entities or evidence.",
  "entities": [],
  "relationships": [],
  "sources": [],
  "citations": [],
  "layout": {
    "positions": {},
    "viewport": { "x": 0, "y": 0, "zoom": 1 }
  },
  "createdAt": "2026-09-05T00:00:00.000Z",
  "updatedAt": "2026-09-05T00:00:00.000Z"
}
```

## Referential and vocabulary rules

IDs are globally unique across the Network and all its durable records. A relationship's `sourceEntityId` and `targetEntityId` must resolve to entities and be legal for its relationship kind. A Citation's `sourceId` and target must resolve. Layout positions must match existing entity IDs; every entity needs a position.

The registry defines 15 entity and 33 relationship kinds. Stored codes such as `person`, `company`, `online-account`, `director-of` and `operates-account` stay the same in English and German. Registered property names and option values also remain stable. For example, a company can use `jurisdiction`, `registrationNumber` and `legalForm`; a selected status uses an allowed code such as `active` or `unknown`.

Each entity and relationship carries `confidence`: `confirmed`, `probable`, `unconfirmed` or `disputed`. Citation stance is separately `supports`, `disputes` or `context`. Creation `origin.kind` is `manual`, `csv`, `ai` or `legacy`. Do not add an unrecognized property to a registered field map; custom imported attributes have their own descriptor-backed map.

## Interchange boundaries

| Format            | Input/output boundary                                                                                                       |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Network JSON      | Complete Network import/export; schema version and references are validated; IDs are preserved and collisions reject import |
| CSV               | Header mapping and row preview for entity creation only; not a complete Network interchange format                          |
| AI graph proposal | Untrusted structured suggestions validated against the request, vocabulary, evidence and accepted dependencies              |
| Hosted snapshot   | A separately published immutable envelope; copying remaps all durable IDs into an independent local Network                 |

Accepted pasted-text citations can include UTF-16 `startOffset` and `endOffset` values. The exact source slice must equal the excerpt; offsets are not byte positions. URL Sources accept HTTP/HTTPS addresses without embedded credentials. Retained pasted text is part of the Network and its JSON export.

## Compatibility and version review

The importer accepts supported version 1 documents and supplies `legacy` origin metadata for older records missing it. That compatibility behavior is not a general promise to accept arbitrary graph JSON, other applications' exports, desktop vaults or future schema versions. Account tokens, provider credentials and renderer internals do not belong in a Network document.

Before publishing a documentation update, compare the app revision, contract hashes and visible labels recorded in the documentation index. Revalidate examples and replay the affected UI task when any of those sources change. Schema validation proves structural validity; it does not prove that a research claim is true.