# Project Ontology Instance Schema

Status: first contract
Date: 2026-06-28
Owner: NDC SEO mod

## Intent

`ProjectOntologyInstance` is the per-project/site ontology profile consumed by NDC SEO mod.
It is not the global ontology.

It gives the model enough grounded context to analyze and rewrite the current site without
injecting unrelated offers, markets, or product claims.

## Required Guarantees

- Every extracted entity, intent, tone rule, and constraint must have evidence or explicit user approval.
- Unknown entities are allowed but must stay local to the project until promoted.
- Market evidence is linked as project evidence, not ontology truth.
- Rewrite and apply stages must only consume approved scope items.
- Optional expansion proposals are not part of the default optimization path.

## JSON Fields

Top level:

- `schemaVersion`
- `projectId`
- `siteId`
- `coreOntologyVersion`
- `seoDomainPackageVersion`
- `source`
- `scope`
- `brand`
- `offers`
- `audiences`
- `pages`
- `sections`
- `intentClusters`
- `tone`
- `constraints`
- `evidence`
- `approvals`
- `ontologyDeltaProposals`

## Lifecycle

1. Source import or live crawl creates `scan_version`.
2. User-selected graph/scope creates `scope_contract`.
3. Extractor creates a draft `ProjectOntologyInstance`.
4. Dev Mode shows evidence, confidence, and unresolved questions.
5. User/model approvals produce an approved version.
6. Semantic analysis consumes approved ontology plus scope contract.
7. Market evidence, keyword map, plan, rewrite, validation, and changeset link back to ontology version.

## NODE.DC Seed

The NODE.DC project ontology seed should be kept as a fixture and regression target.
It must not stay embedded inside generic semantic analysis code.

